MkDocs static i18n plugin

1.3.1 · maintenance · verified Thu Apr 16

The `mkdocs-static-i18n` plugin allows you to support multiple languages for your documentation by adding static translation files to your existing documentation pages. It generates a default version of your website plus one version per configured language on its corresponding `/language/` path, and supports localized images, media, and assets. The current version is 1.3.1. While widely used, the project maintainer has stated it is "frozen as-is" due to upstream MkDocs maintenance uncertainty, suggesting a maintenance-only cadence without new feature development.

Common errors

```
Error: Plugin 'i18n' not found in config.plugins
```
cause The `mkdocs-static-i18n` package is either not installed in the environment or not correctly listed in the `plugins` section of `mkdocs.yml`.

fix First, ensure `pip install mkdocs-static-i18n` has been run. Then, verify your `mkdocs.yml` includes the plugin under the `plugins` key: `plugins: - i18n: ...`
```
404 Not Found after switching language on GitHub Pages.
```
cause Often related to incorrect `link` configurations in the `extra.alternate` section of `mkdocs.yml`, particularly when the site is hosted as a project page (e.g., `username.github.io/repo-name/`) rather than a user/organization page.

fix Adjust the `link` property for each language in `extra.alternate` to be relative to the site root, e.g., `link: fr` for a French sub-path, and test. Ensure the generated URLs match your hosting setup.
```
Navigation items are not translated, or entire navigation is missing for a language.
```
cause This can happen if `nav_translations` or `nav` options are not correctly configured under a specific language in `mkdocs.yml`, or if there's a mismatch between the default navigation structure and the translated files.

fix Review the 'Localizing navigation' section in the plugin's documentation. You can use `nav_translations` for specific title overrides or `nav` to provide an entirely separate navigation structure for a language. Ensure your localized files exist and follow the chosen `docs_structure`.

Warnings

breaking Version 1.0.0 introduced significant breaking changes to the plugin's configuration format. If upgrading from pre-1.0.0 versions, carefully review the migration guide.
Fix: Consult the official 'Upgrading to v1.0.0' guide in the plugin's documentation to adapt your `mkdocs.yml` configuration.
gotcha The `mkdocs-static-i18n` project is officially stated as 'frozen as-is' due to the upstream MkDocs project's maintenance status. While functional and widely used, this means active feature development is unlikely.
Fix: Be aware that future major features or rapid bug fixes might not be provided. Rely on existing functionality and community contributions for specific needs.
gotcha When deploying to GitHub Pages, especially with MkDocs Material's language switcher (`extra.alternate`), incorrect `link` paths can lead to 404 errors when switching languages.
Fix: Ensure the `link` parameter in your `extra.alternate` configuration correctly reflects the base path for each language. For example, use `link: fr` for French, not `/fr`.
gotcha New markdown files or assets added to the documentation structure might not appear immediately when running `mkdocs serve`.
Fix: If new files are not recognized, restart the `mkdocs serve` command to force a full re-scan and reload of the documentation structure.

Install

pip install mkdocs-static-i18n Install latest version

Imports

mkdocs-static-i18n
```
# This plugin is configured in mkdocs.yml, not directly imported in Python code.
```
Users configure this plugin within their `mkdocs.yml` file under the `plugins` section, rather than importing it into Python scripts.

Quickstart

To get started, first ensure `mkdocs-static-i18n` is installed. Then, configure the plugin in your `mkdocs.yml` file by defining your `default_language`, `docs_structure` (either `suffix` like `index.fr.md` or `folder` like `fr/index.md`), and the list of `languages` you wish to support.

mkdocs.yml:
plugins:
  - i18n:
      default_language: en
      docs_structure: suffix # or 'folder'
      languages:
        - locale: en
          name: English
        - locale: fr
          name: Français

# Example docs/ structure (suffix):
# docs/
# ├── index.en.md
# ├── index.fr.md
# └── about.en.md
# └── about.fr.md

# To serve the site locally:
# mkdocs serve

# To build the static site:
# mkdocs build

view raw JSON →