{"id":7414,"library":"mkdocs-static-i18n","title":"MkDocs static i18n plugin","description":"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.","status":"maintenance","version":"1.3.1","language":"en","source_language":"en","source_url":"https://github.com/ultrabug/mkdocs-static-i18n","tags":["mkdocs","i18n","l10n","documentation","static-site-generator","internationalization","localization","markdown"],"install":[{"cmd":"pip install mkdocs-static-i18n","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is an MkDocs plugin and requires MkDocs to function. The plugin is compatible with Python >=3.8, aligning with recent MkDocs versions.","package":"mkdocs"}],"imports":[{"note":"Users configure this plugin within their `mkdocs.yml` file under the `plugins` section, rather than importing it into Python scripts.","symbol":"mkdocs-static-i18n","correct":"# This plugin is configured in mkdocs.yml, not directly imported in Python code."}],"quickstart":{"code":"mkdocs.yml:\nplugins:\n  - i18n:\n      default_language: en\n      docs_structure: suffix # or 'folder'\n      languages:\n        - locale: en\n          name: English\n        - locale: fr\n          name: Français\n\n# Example docs/ structure (suffix):\n# docs/\n# ├── index.en.md\n# ├── index.fr.md\n# └── about.en.md\n# └── about.fr.md\n\n# To serve the site locally:\n# mkdocs serve\n\n# To build the static site:\n# mkdocs build\n","lang":"yaml","description":"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."},"warnings":[{"fix":"Consult the official 'Upgrading to v1.0.0' guide in the plugin's documentation to adapt your `mkdocs.yml` configuration.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 to 1.0.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"1.0.0+"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions using GitHub Pages and Material theme's language switcher"},{"fix":"If new files are not recognized, restart the `mkdocs serve` command to force a full re-scan and reload of the documentation structure.","message":"New markdown files or assets added to the documentation structure might not appear immediately when running `mkdocs serve`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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: ...`","cause":"The `mkdocs-static-i18n` package is either not installed in the environment or not correctly listed in the `plugins` section of `mkdocs.yml`.","error":"Error: Plugin 'i18n' not found in config.plugins"},{"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.","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.","error":"404 Not Found after switching language on GitHub Pages."},{"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`.","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.","error":"Navigation items are not translated, or entire navigation is missing for a language."}]}