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

> Learn to configure MkDocs for multi-language support. This guide details setting up language mappings, internationalization assets, and navigation for your multilingual documentation.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: how-to-guide
- Published: 2026-08-22

---

**To configure MkDocs for multi-language support, define language mappings in the `extra.languages` section of [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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:

```yaml

# 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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml):

```yaml
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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/extras/auto-translate.js) loads the [`translate.js`](https://github.com/bojieli/ai-agent-book/blob/main/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:

```yaml
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`](https://github.com/bojieli/ai-agent-book/blob/main/mkdocs.yml) references these language-specific directories:

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

```

The [`scripts/build_site.sh`](https://github.com/bojieli/ai-agent-book/blob/main/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:

```yaml
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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/extras/site-i18n.generated.js). This generated file provides the mapping data required by [`lang-switcher.js`](https://github.com/bojieli/ai-agent-book/blob/main/lang-switcher.js) to display correct labels for each language.

## Summary

- **Define language mappings** in [`mkdocs.yml`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/lang-switcher.js)) and fallback translation ([`auto-translate.js`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/extras/auto-translate.js) script loads the third-party [`translate.js`](https://github.com/bojieli/ai-agent-book/blob/main/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.