How to Add a Translation¶

This page explains how to add or improve a translation of the docs for any language.

The site uses MkDocs + Material + mkdocs-static-i18n. English is the reference (fallback). Any other language mirrors its folder structure. If a page is missing in a target language, the English version is shown automatically.

1. Overview¶

There are three typical scenarios:

1. Improve an existing translated page.
2. Translate an English page that currently has no localized version.
3. Add an entirely new language to the project.

Everything below covers all three.

2. Folder layout¶

/docs
  en/
    developer-guide/
    getting-started/
    user-guide/
  <locale>/
    (mirrors the structure you translate)

Examples of <locale>: pt, es, fr, de, it, ja, zh, ru. Use short IETF / BCP‑47 language tags (no country code unless needed, e.g. pt vs pt-BR only if a regional variant is required). Keep it consistent with mkdocs.yml.

Relative paths must match. Example:

English: docs/en/developer-guide/how-to-add-a-translation.md
Spanish: docs/es/developer-guide/how-to-add-a-translation.md
French:  docs/fr/developer-guide/how-to-add-a-translation.md

3. Quick start (improving or adding a translation)¶

1. Fork and clone your fork.
2. Create / activate a virtual environment.
3. Install docs extras:

   pip install -e ".[docs]"
   

4. Run the local server:

   mkdocs serve
   

5. Open the local URL and switch language with the selector.

Restart the server if new files do not show up (MkDocs sometimes needs a restart after new file additions).

4. Adding a new language (one-time setup)¶

If the language already exists (e.g. pt/), skip this section.

1. Pick a locale code (e.g. es).
2. Create the folder: docs/es/.
3. Copy the English index.md to docs/es/index.md and translate its visible text.
4. (Optional) Start by copying only a minimal subset (index + key getting-started pages) to keep the first PR reviewable.
5. Update mkdocs.yml i18n.languages section:

   - locale: es
     name: Español
     build: true
     site_description: <translated site tagline>
     theme:
       docs_dir: docs/es/
       custom_dir: docs/es/
       site_dir: site/es/
       logo: overrides/assets/img/logotype-sysidentpy.svg
   

6. Do not duplicate nav entries for the new language: the plugin maps them automatically based on folder structure.
7. Run mkdocs serve and confirm the new language appears in the selector.

If you need a regional variant (e.g. pt-BR), use that code consistently in both folder name and mkdocs.yml.

5. Adding a new English page (source language)¶

1. Create the file under docs/en/... in the right section.
2. Add front matter:

   ---
   template: overrides/main.html
   title: My Page Title
   ---
   

3. Add its path to the nav tree in mkdocs.yml (English only).
4. Verify the site builds.
5. (Optional) Add a translator note (HTML comment) for tricky concepts:

   <!-- Translator note: keep the term "NARMAX" in English. -->
   

6. Creating the translated file¶

1. Mirror the folder path: docs/<locale>/<same relative path>.md.

2. Copy the English file.

3. Translate only human-readable prose. Keep intact:

   • Code blocks (except inline comments if clarity improves)
   • Identifiers: function/class names, parameters, imports
   • File paths, config keys, URLs
   • Markdown link targets (unless they refer to a language-specific external resource)

4. Preserve heading hierarchy (#, ##, etc.) but translate heading text itself.

5. Keep admonition types (!!! note, !!! warning, etc.). You may translate the title string after the admonition type.

6. For unfinished parts, you can temporarily keep English or add:

   !!! note "Pending translation"
       This paragraph still needs translation.
   

7. Remove all "Pending" notes before final review if completed.

7. Internal links¶

Use relative links without language prefixes:

See the [Contribute guide](contribute.md).

Anchor links: if you translate a heading, Material generates a localized slug. Keep anchor usage consistent or adjust any (#anchor) references accordingly.

8. Images and media¶

If screenshots contain embedded language text:

• Option A: replicate and localize the image inside docs/<locale>/assets/ and keep the same filename (per-locale path isolates it).
• Option B: reuse the English image if text is minimal or language-agnostic.

SVG diagrams: prefer keeping labels English if they are code or model symbols; translate UI captions where helpful.

9. Formatting & style guidelines¶

Avoid machine‑translated chunks without revision. Prefer shorter, unambiguous sentences.

10. Translation glossary¶

Keep these terms consistent across languages. Add target language equivalents as needed:

For other languages, follow similar patterns. Prefer clarity over literal translation.

11. Review checklist (per translated file)¶

• Builds locally (mkdocs serve).
• File path mirrors English.
• Relative links work; no /en/ hardcoding.
• Code blocks untouched (except explanatory comments if needed).
• Terminology consistent with existing pages.
• No leftover placeholder notes (unless intentionally partial PR).
• Front matter present and title: localized.

12. Commit & Pull Request¶

Add both English and translated files if you introduce a page + its translation; otherwise just the translated file.

Example:

git add docs/en/developer-guide/new-topic.md docs/es/developer-guide/new-topic.md
git commit -m "docs: add Spanish translation for new-topic"

PR description template:

• Language: <locale> (e.g. es)
• Pages added/updated: list paths
• Sections intentionally left untranslated: (if any)
• Glossary additions: (if any)
• Notes for reviewer: context, tricky terms

Partial translations are acceptable—label them clearly so others can help.

13. Updating existing translations¶

When an English page changes:

1. Open the diff to see what changed.
2. Apply equivalent edits to the translated file.
3. If you cannot translate immediately, keep the English change and add a temporary "Pending translation" note.
4. Remove the note once updated.

Aim for incremental PRs rather than large rewrites.

14. Common issues¶

15. Automation (optional)¶

You may use external CAT / translation tools, but always manually review technical terms. Avoid committing raw machine output.

If you script copying English files to a new locale, exclude already translated ones to prevent overwriting.

16. Questions & support¶

If you are unsure about terminology, open an Issue or Discussion before translating large sections. Early feedback prevents rework.

Thanks for helping make the documentation accessible to more people.