Install & Compatibility
Where this runs
tested against v1.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 33.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.1s · import 0.000s · 34MB
32MB installed
● package 32MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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
Debug
Known issues
breakingVersion 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.fixConsult the official 'Upgrading to v1.0.0' guide in the plugin's documentation to adapt your `mkdocs.yml` configuration.
affects: <1.0.0 to 1.0.0+
gotchaThe `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.fixBe aware that future major features or rapid bug fixes might not be provided. Rely on existing functionality and community contributions for specific needs.
affects: 1.0.0+
gotchaWhen deploying to GitHub Pages, especially with MkDocs Material's language switcher (`extra.alternate`), incorrect `link` paths can lead to 404 errors when switching languages.fixEnsure 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`.
affects: All versions using GitHub Pages and Material theme's language switcher
gotchaNew markdown files or assets added to the documentation structure might not appear immediately when running `mkdocs serve`.fixIf new files are not recognized, restart the `mkdocs serve` command to force a full re-scan and reload of the documentation structure.
affects: All versions
Upgrade
Version history
1.3.1latest on PyPI · released Feb 20, 2026
Audit
Dependencies
mkdocsrequiredThis is an MkDocs plugin and requires MkDocs to function. The plugin is compatible with Python >=3.8, aligning with recent MkDocs versions.