Mkdocs Translations

MkDocs translations

Translate every English MkDocs source file into a target locale, mirror the folder structure, update include paths and mkdocs.yml, and continue automatically until source and translated file counts match.

When to invoke

• "Run the mkdocs ai translator for Spanish."
• "Translate our MkDocs docs to pt-BR."
• "Add a French locale to this documentation site."
• "Localize docs/docs/en and includes/en."
• "Update mkdocs.yml for a new translated locale."

Inputs

Use the target translation language and locale code, such as Spanish es, French fr, Brazilian Portuguese pt-BR, or Korean ko. If the user did not provide both a language and a locale code, ask for them before proceeding. Use the locale code consistently in folder names, translated include paths, and MkDocs configuration.

Source and output layout

Create a branch before writing files:

git checkout -b docs-translation-<language>

Translation procedure

1. Confirm the target language and locale code.
2. Create docs-translation-<language> with git checkout -b docs-translation-<language> before creating any new files.
3. List all files and subdirectories under docs/docs/en.
4. List all files and subdirectories under docs/docs/includes/en.
5. Translate every file one by one in the listed order; do not skip, reorder, or stop after a fixed number of files.
6. Mirror the exact folder and filename structure under docs/docs/<locale>/ and docs/docs/includes/<locale>/.
7. Preserve Markdown formatting, headings, code blocks, metadata, and links.
8. Update include references from includes/en/... to includes/<locale>/....
9. Append *Translated using GitHub Copilot and GPT-4o.* at the end of every translated file.
10. Update mkdocs.yml with the new i18n locale entry, nav_translations, and admonition_translations.
11. Count source files and translated files. If any file remains unprocessed, resume from the missing file and continue automatically.

Translation rules

MkDocs configuration rules

Update only the localization-related configuration required for the new locale:

• Add a locale entry under the i18n plugin using the target locale code.
• Add appropriate nav_translations.
• Add appropriate admonition_translations.
• Keep existing locales and unrelated MkDocs settings intact.

Gotchas

• Do not start writing before branching: git checkout -b docs-translation-<language> is required first.
• Do not stop after a sample: every file under both English source trees must be translated.
• Do not lint the docs: preserve formatting and avoid unrelated Markdown cleanup.
• Do not translate include paths partially: every includes/en/ reference must use the target locale.

For Spanish examples, includes/es/introduction-event.md is the concrete rewritten include path.

Output template

## MkDocs translation result

**Status:** complete | blocked
**Language:** `<language>`
**Locale:** `<locale>`
**Branch:** `docs-translation-<language>`

### File counts
| Source tree | Source files | Translated files | Status |
| --- | --- | --- | --- |
| `docs/docs/en` | `<count>` | `<count>` | `matched | missing` |
| `docs/docs/includes/en` | `<count>` | `<count>` | `matched | missing` |

### Configuration
- `mkdocs.yml` locale entry: `<added/updated>`
- `nav_translations`: `<added/updated>`
- `admonition_translations`: `<added/updated>`

Quality gate

• Target language and locale code were confirmed before translation.
• git checkout -b docs-translation-<language> ran before creating files.
• Every file under docs/docs/en was translated in listed order.
• Every file under docs/docs/includes/en was translated in listed order.
• Target folders mirror the source structure exactly.
• Markdown formatting, metadata, links, code blocks, paths, and filenames were preserved.
• Each translated file ends with *Translated using GitHub Copilot and GPT-4o.*.
• mkdocs.yml includes the locale entry, nav_translations, and admonition_translations.
• Source and translated file counts match.