mkdocs-translations

Overview

A GitHub Copilot skill that automates translation of MkDocs documentation stacks into any target language. It translates all markdown files from source directories while preserving folder structure, formatting, and include path references, then updates the MkDocs configuration with the new locale entries, navigation translations, and admonition translations.

Key Features

• Complete documentation translation: Translates every file in docs/docs/en and docs/docs/includes/en directories one by one, maintaining the exact folder and file structure in the target language directory.
• Fully autonomous workflow: After the user specifies the target language and locale code, the skill proceeds automatically through all files without pausing for confirmation, resuming from where it left off if interrupted, and verifying file count matches upon completion.
• Markdown preservation: Preserves all markdown formatting including headings, code blocks, metadata, links, and include references while updating paths to reflect the new locale (e.g., includes/en/ to includes/es/).
• MkDocs configuration updates: Automatically modifies mkdocs.yml to add new locale entries under the i18n plugin, including navigation translations (nav_translations) and admonition translations.
• Git branch management: Creates a new git branch (docs-translation-<language>) before generating any files, keeping translation work isolated from the main branch.

Who is this for?

This skill is designed for technical writers and documentation teams using MkDocs who need to create multilingual versions of their documentation. It is especially useful for open source projects and enterprise teams that want to make their docs accessible in multiple languages without manual file-by-file translation, while maintaining proper MkDocs i18n plugin configuration.