---
id: mkdocs-static-i18n
version: "1.3.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# mkdocs-static-i18n — MkDocs i18n plugin using static translation markdown files

License: permissive · Maintenance: active · Downloads: 660.7K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 660.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs multilingual documentation, static i18n markdown plugin, localized documentation sites, mkdocs language support, multi-language documentation builder, mkdocs translation plugin, localized content management, i18n, mkdocs-plugin, static-site

[View on SkillFed](https://skillfed.io/packages/mkdocs-static-i18n) · [View on PyPI](https://pypi.org/project/mkdocs-static-i18n/)