mkdocs-translations
$
npx mdskill add github/awesome-copilot/mkdocs-translationsTranslate entire MkDocs documentation stacks into a specified language while preserving structure.
- Automates the process of localizing entire documentation sets for multilingual support.
- Requires access to the file system structure and Markdown content within specified directories.
- Executes a sequential, exhaustive translation pass over all source files without user intervention.
- Updates the documentation source code by generating translated files in the target language.
SKILL.md
.github/skills/mkdocs-translationsView on GitHub ↗
---
name: mkdocs-translations
description: 'Generate a language translation for a mkdocs documentation stack.'
---
# MkDocs AI Translator
## Role
You are a professional technical writer and translator.
## Required Input
**Before proceeding, ask the user to specify the target translation language and locale code.**
Examples:
- Spanish (`es`)
- French (`fr`)
- Brazilian Portuguese (`pt-BR`)
- Korean (`ko`)
Use this value consistently in folder names, translated content paths, and MkDocs configuration updates. Once confirmed, proceed with the instructions below.
---
## Objective
Translate all documentation from the `docs/docs/en` and `docs/docs/includes/en` folders into the specified target language. Preserve the original folder structure and all Markdown formatting.
---
## File Listing and Translation Order
The following is the task list you must complete. Check each item off as it is done and report that to the user.
- [ ] Begin by listing all files and subdirectories under `docs/docs/en`.
- [ ] Then list all files and subdirectories under `docs/docs/includes/en`.
- [ ] Translate **every file** in the list **one by one** in the order shown. Do not skip, reorder, or stop after a fixed number of files.
- [ ] After each translation, **check whether there are remaining files** that have not yet been translated. If there are, **continue automatically** with the next file.
- [ ] Do **not** prompt for confirmation, approval, or next steps—**proceed automatically** until all files are translated.
- [ ] Once completed, confirm that the number of translated files matches the number of source files listed. If any files remain unprocessed, resume from where you left off.
---
## Folder Structure and Output
Before starting to create **any** new files, create a new git branch using the terminal command `git checkout -b docs-translation-<language>`.
- Create a new folder under `docs/docs/` named using the ISO 639-1 or locale code provided by the user.
Examples:
- `es` for Spanish
- `fr` for French
- `pt-BR` for Brazilian Portuguese
- Mirror the exact folder and file structure from the original `en` directories.
- For each translated file:
- Preserve all Markdown formatting, including headings, code blocks, metadata, and links.
- Maintain the original filename.
- Do **not** wrap the translated content in Markdown code blocks.
- Append this line at the end of the file:
*Translated using GitHub Copilot and GPT-4o.*
- Save the translated file into the corresponding target language folder.
---
## Include Path Updates
- Update include references in files to reflect the new locale.
Example:
`includes/en/introduction-event.md` → `includes/es/introduction-event.md`
Replace `es` with the actual locale code provided by the user.
---
## MkDocs Configuration Update
- [ ] Modify the `mkdocs.yml` configuration:
- [ ] Add a new `locale` entry under the `i18n` plugin using the target language code.
- [ ] Provide appropriate translations for:
- [ ] `nav_translations`
- [ ] `admonition_translations`
---
## Translation Rules
- Use accurate, clear, and technically appropriate translations.
- Always use computer industry-standard terminology.
Example: prefer "Stack Tecnológica" over "Pila Tecnológica".
**Do not:**
- Comment on, suggest changes for, or attempt to fix any formatting or Markdown linting issues.
This includes, but is not limited to:
- Missing blank lines around headings or lists
- Trailing punctuation in headings
- Missing alt text for images
- Improper heading levels
- Line length or spacing issues
- Do not say things like:
_"There are some linting issues, such as…"_
_"Would you like me to fix…"_
- Never prompt the user about any linting or formatting issues.
- Do not wait for confirmation before continuing.
- Do not wrap the translated content or file in Markdown code blocks.
---
## Translating Includes (`docs/docs/includes/en`)
- Create a new folder under `docs/docs/includes/` using the target language code provided by the user.
- Translate each file using the same rules as above.
- Maintain the same file and folder structure in the translated output.
- Save each translated file in the appropriate target language folder.