# How the i18n Plugin Handles Chinese and English Content in MkDocs

> Learn how the mkdocs-static-i18n plugin manages Chinese and English content. Discover its approach to serving default Chinese content and routing English translations for a bilingual site.

- Repository: [Yinmin Zhong/cs-self-learning](https://github.com/PKUFlyingPig/cs-self-learning)
- Tags: internals
- Published: 2026-03-02

---

**The mkdocs-static-i18n plugin manages bilingual content by serving Simplified Chinese (`zh`) as the default locale from base `.md` files while routing English (`en`) translations from [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) suffix files to a separate `/en/` directory, using the `nav_translations` configuration in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml) to localize navigation labels.**

The PKUFlyingPig/cs-self-learning repository powers the CSDIY wiki, a popular computer science self-learning guide. To support both Chinese and English readers, the project leverages the **mkdocs-static-i18n** plugin (version 1.2.0), enabling automatic locale detection, file routing, and navigation translation without duplicating the entire site structure.

## Configuration Structure in mkdocs.yml

The i18n implementation centers on the plugin configuration inside [[`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml)](https://github.com/PKUFlyingPig/cs-self-learning/blob/master/mkdocs.yml). The setup defines two language blocks under the `plugins.i18n.languages` key.

- **Default Locale**: `zh` (Simplified Chinese) marked as `default: true`, which generates content at the site root.
- **Secondary Locale**: `en` (English) with `build: true`, generating content under the `en/` subdirectory.

The English locale overrides the global `site_name` to `csdiy.wiki` (line 70), ensuring locale-specific branding while the Chinese version inherits the default site name.

## Content File Organization

The plugin uses a file suffix convention to distinguish between language versions without requiring separate folder structures.

- **Chinese content** uses the base filename with the `.md` extension (e.g., `docs/必学工具/翻墙.md`).
- **English content** adds the locale suffix [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) to the corresponding path (e.g., `docs/必学工具/翻墙.en.md`).

When building the site, the plugin automatically selects the appropriate file based on the active locale. If a visitor accesses the English version, the plugin serves `翻墙.en.md`; otherwise, it defaults to the Chinese `翻墙.md`.

## Navigation Translation via nav_translations

To ensure the navigation menu displays correctly in both languages, the configuration defines a `nav_translations` mapping for the English locale (lines 71–84 in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml)). This dictionary maps every Chinese navigation title to its English equivalent.

For example, if the Chinese navigation includes "必学工具", the translation entry maps this to "Must Learn Tools" for English visitors. This allows a single `nav` structure in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml) to serve both languages while displaying locale-appropriate labels.

## Build Output and URL Structure

Running `mkdocs build` generates distinct static outputs for each locale:

1. **Chinese build**: Outputs to the `site/` root directory, preserving all original URLs.
2. **English build**: Outputs to `site/en/`, maintaining parallel URL paths (e.g., `/en/必学工具/翻墙/`).

This structure ensures shared assets like images and CSS files remain in the root, accessible to both language versions via relative paths, while keeping content cleanly separated by locale.

## Practical Implementation Example

To add a new bilingual page to the repository:

1. Create the Chinese version at `docs/机器学习/ML.md`:

```markdown

# 机器学习

机器学习是一门研究如何让计算机从经验中自动改进的学科。

```

2. Create the English version at `docs/机器学习/ML.en.md`:

```markdown

# Machine Learning

Machine Learning studies how computers can automatically improve from experience.

```

3. Update [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml) to include the navigation translation:

```yaml
plugins:
  - i18n:
      languages:
        - locale: zh
          default: true
          name: 简体中文
          build: true
        - locale: en
          name: English
          build: true
          site_name: csdiy.wiki
          nav_translations:
            机器学习: Machine Learning
            必学工具: Must Learn Tools

```

4. Build the site:

```bash
mkdocs build

```

The output generates `site/机器学习/ML/index.html` for Chinese readers and `site/en/机器学习/ML/index.html` for English readers, with navigation menus displaying the appropriate language labels.

## Summary

- The **mkdocs-static-i18n** plugin in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml) configures `zh` as the default locale and `en` as a secondary build target.
- Chinese content lives in base `.md` files while English translations use the [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) suffix convention.
- The `nav_translations` dictionary (lines 71–84) maps Chinese navigation titles to English equivalents for the `en` locale.
- Build output places Chinese content at the root (`site/`) and English content under `site/en/`, enabling parallel URL structures.
- File selection is automatic based on the active locale, requiring no manual routing logic in templates.

## Frequently Asked Questions

### How does the plugin decide which language file to serve?

The plugin examines the active locale and looks for files matching the pattern `<filename>.<locale>.md`. For English (`en`), it searches for [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) files first; if absent, it falls back to the base `.md` file. For the default Chinese (`zh`) locale, it uses the base `.md` file directly without checking for suffixes.

### What happens if an English translation file is missing?

If a corresponding [`.en.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.en.md) file does not exist for a given page, the plugin serves the base Chinese `.md` file as a fallback. This ensures no broken links while encouraging incremental translation of content.

### Where is the navigation translation configured?

Navigation translations are defined in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml) within the `nav_translations` key under the English locale configuration (approximately lines 71–84). Each entry maps a Chinese navigation string to its English translation, allowing the same `nav` structure to display localized labels.

### Can additional languages be added using this configuration?

Yes. The plugin supports multiple locales by adding new language blocks to the `languages` list in [`mkdocs.yml`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/mkdocs.yml). Each new locale requires a unique identifier, `name` for display, optional `site_name` override, `build: true`, and corresponding content files using the appropriate suffix (e.g., [`.fr.md`](https://github.com/PKUFlyingPig/cs-self-learning/blob/main/.fr.md) for French).