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.
• Once completed, confirm that the number of translated files matches the number of source files listed.

---

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.
  • 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…"
• 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.