Mkdocs-Translations

# 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