How to Configure MkDocs for Multi-Language Support: A Complete Implementation Guide

To configure MkDocs for multi-language support, define language mappings in the extra.languages section of mkdocs.yml, load internationalization assets via extra_javascript, configure language-specific search tokenization, and structure your navigation paths using language prefixes.

The bojieli/ai-agent-book repository demonstrates how to configure MkDocs for multi-language support when building the "AI Agents in Depth" website. While MkDocs does not provide native internationalization out of the box, you can extend the Material theme with custom configurations that handle language switching, localized navigation, and search indexing across multiple languages.

Defining Language Mappings in mkdocs.yml

The foundation of multi-language configuration resides in the extra.languages section of mkdocs.yml. This custom configuration maps language identifiers to their corresponding directory structures and display labels.

Configuring the Language Switcher

Add each supported language to the extra block with a label, folder prefix, and optional source file suffix:

# mkdocs.yml - inside the `extra` block

extra:
  languages:
    en: { label: English, prefix: book-en/, readmeSuffix: en }
    zh: { label: 中文, prefix: book-zh/, readmeSuffix: zh }
    fr: { label: Français, prefix: book-fr/, readmeSuffix: fr }

The prefix parameter directs MkDocs to language-specific content folders (e.g., book-en/), while readmeSuffix identifies corresponding README files (e.g., README.fr.md). The label value appears as the text on the language tab bar.

Loading Internationalization Assets

Multi-language functionality requires client-side JavaScript to render the language switcher and handle translation fallbacks. Configure these through extra_javascript and extra_css in mkdocs.yml:

extra_javascript:
  - extras/site-i18n.generated.js
  - extras/lang-switcher.js
  - extras/auto-translate.js

extra_css:
  - extras/custom.css

The extras/lang-switcher.js file injects the language tab bar into the header and manages URL rewriting when users switch languages. For languages lacking dedicated translations, extras/auto-translate.js loads the translate.js library to provide on-demand machine translation as a fallback.

Setting the Base Theme Language

Configure the default language for the Material theme using the theme.language setting. The AI Agent Book uses Chinese (zh) as the default, which the language switcher overrides at runtime when users select alternatives:

theme:
  name: material
  language: zh

This ensures that UI elements like "Search" and "Next" appear in the default language when the site first loads, before JavaScript initializes the switcher.

Structuring Per-Language Navigation

Each language requires its own navigation structure pointing to prefixed file paths. The nav section in mkdocs.yml references these language-specific directories:

nav:
  - 首页: index.md
  - Introduction: book-en/introduction.md
  - 第1章 Agent基础知识:
      - book-en/chapter1/index.md
      - 配套实验: chapter1/README.md

The scripts/build_site.sh script automates the preparation of these paths. It copies source Markdown files from the repository into language-specific trees under the _web/ directory, applying the prefixes defined in extra.languages to organize content for each language edition.

Configuring Multi-Language Search

Enable search functionality across languages by configuring the search plugin with language-specific tokenizers. This ensures proper handling of character sets including CJK (Chinese, Japanese, Korean) and Arabic scripts:

plugins:
  - search:
      lang:
        - ja
        - ko
        - en
        - ar
        - fr

Adding a language code (e.g., fr for French) ensures the search index builds with a language-aware tokenizer capable of parsing that language's morphology and character boundaries.

Customizing Theme Overrides

Place custom templates and partials in the overrides/ directory to modify the Material theme's header and inject the language switcher markup. The scripts/site_i18n.py script generates the browser-side translation catalog by processing Material's locales and the book's navigation labels, outputting the results to extras/site-i18n.generated.js. This generated file provides the mapping data required by lang-switcher.js to display correct labels for each language.

Summary

• Define language mappings in mkdocs.yml using the extra.languages section to map identifiers to folder prefixes and README suffixes.
• Load i18n assets via extra_javascript to enable the language switcher (lang-switcher.js) and fallback translation (auto-translate.js).
• Set the base theme language using theme.language to establish a default locale before the switcher initializes.
• Structure navigation with language-prefixed paths (e.g., book-en/) and use scripts/build_site.sh to organize content into the build tree.
• Configure search tokenization for each language in the search plugin configuration to ensure accurate indexing of non-Latin scripts.
• Customize theme overrides in the overrides/ directory and generate translation catalogs with scripts/site_i18n.py.

Frequently Asked Questions

Does MkDocs support multi-language sites natively?

No, MkDocs does not include built-in multi-language support. The configuration described here extends the Material theme using custom JavaScript, structured navigation prefixes, and the extra.languages configuration block to achieve multi-language functionality as implemented in the bojieli/ai-agent-book repository.

How do I add a new language to an existing MkDocs multi-language setup?

Add the language identifier to the extra.languages section in mkdocs.yml with its label, prefix, and readmeSuffix. Create the corresponding folder structure (e.g., book-fr/), update the nav section to include paths with the new prefix, and add the language code to the search plugin's language list to enable proper tokenization.

What handles the URL switching when users click a language tab?

The extras/lang-switcher.js script manages URL rewriting and language switching at runtime. It reads the extra.languages configuration embedded in the generated site metadata and rewrites URLs to point to the corresponding language-prefixed paths when users interact with the header tabs.

How does the site handle content that hasn't been translated yet?

For languages without dedicated translations, the extras/auto-translate.js script loads the third-party translate.js library on demand. This provides machine-generated translations as a fallback while the official translation is in progress, ensuring all languages have accessible content even when specific chapters are not yet localized.

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