How the i18n Plugin Handles Chinese and English Content in MkDocs

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 suffix files to a separate /en/ directory, using the nav_translations configuration in 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/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 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). 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 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:

# 机器学习

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

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

# Machine Learning

Machine Learning studies how computers can automatically improve from experience.

3. Update mkdocs.yml to include the navigation translation:

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:

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 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 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 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 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 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. 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 for French).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}