mkdocs-static-i18n

What it is and what it does

mkdocs-static-i18n is a plugin for MkDocs that enables multi-language documentation by letting you add language-specific markdown files alongside your default documentation. Instead of maintaining separate documentation builds per language, you organize localized content using file suffixes (like `page.fr.md` for French) or folder structures, and the plugin automatically generates language-specific site variants during the build.

The plugin also handles localized images, media, and other assets using the same suffix or folder approach. It's designed for documentation teams that want to support multiple languages without complex translation workflows or separate build pipelines—you add localized files to your existing documentation structure, configure the plugin in mkdocs.yml, and it handles the rest.

Use it for:

• Building multi-language documentation for open-source projects where contributors provide translations as markdown files
• Creating localized versions of technical documentation for software targeting international audiences
• Serving region-specific assets alongside language-specific content in a single MkDocs build
• Maintaining documentation in multiple languages without duplicating the entire site structure for each language variant
• Publishing API or product documentation that needs to reach users in different languages and regions

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A MkDocs plugin that adds static multi-language support to documentation sites by managing localized markdown files and assets with minimal configuration.

Yes, if you maintain MkDocs documentation and need multi-language support. The plugin is actively maintained, has no known vulnerabilities, installs with minimal friction, and uses a permissive MIT license. It's in use by hundreds of projects. The main caveat is that it requires Python 3.8 or later and assumes you're comfortable organizing localized content as static markdown files.

Install

mkdocs-static-i18n on PyPI

pip install mkdocs-static-i18n

uv add mkdocs-static-i18n

poetry add mkdocs-static-i18n

Installing mkdocs-static-i18n

Before you install

Low friction install as a pure Python wheel with a single runtime dependency on mkdocs. The project is actively maintained with a recent release and no known vulnerabilities.

License in practice

MIT license permits unrestricted use, modification, and distribution in both open-source and proprietary projects with minimal obligations.

Quickstart

pip install mkdocs-static-i18n

# In mkdocs.yml, add the plugin:
plugins:
  - i18n

# Add localized markdown files:
# docs/index.md (default)
# docs/index.fr.md (French)
# docs/index.es.md (Spanish)

Requires Python 3.8 or later and an existing MkDocs project.

Verify before relying

• Whether the plugin supports right-to-left language layouts or only left-to-right content
• Performance characteristics when managing documentation with many language variants
• Whether localized asset serving works for all file types or has restrictions

Package facts

Evidence: mkdocs_static_i18n-1.3.1-py3-none-any.whl

Tags

More Python Modules packages