Documentation Translation Guide

How to maintain our multi-language portal.

Authors:
Copyright:

CC-BY-SA 4.0 or >

Organization:

Fundación MxOS, A.C.

Description

This guide documents the workflow to translate and keep updated the documents of the Fundación MxOS documentation portal.

How does translation work in MxOS?

The portal uses the native internationalization (i18n) system of Sphinx based on gettext.

  • The source language of all documentation is Mexican Spanish (es-MX).

  • Translations to English (en-US) and other languages are done by translating message catalogs (.po files).

  • Los archivos de traducción se encuentran en el repositorio del portal en la ruta content/locale/<idioma>/LC_MESSAGES/.

Step-by-Step Translation Process

When you create or edit a document in Spanish, you must follow these steps to update and generate its translation into English.

1. Message Extraction (POT)

First, you must extract all text strings from the portal into translation templates (.pot files). Run the following from the portal root:

make gettext

(Or directly using sphinx-build: ``sphinx-build -M gettext content _build``)

2. Catalog Update (.po)

Next, synchronize the new strings with the catalogs of the target language (in this case, English). This will merge the new changes without losing existing translations:

sphinx-intl update -p _build/gettext -l en

This will create or update the .po files under content/locale/en/LC_MESSAGES/.

3. Translate Strings

Open the corresponding .po files with your preferred text editor (or a tool like Poedit). You will see blocks like this:

#: ../../content/documentación/guias/traducción.rst:14
msgid "Descripción"
msgstr ""

Complete the translation by entering the corresponding translation in msgstr:

#: ../../content/documentación/guias/traducción.rst:14
msgid "Descripción"
msgstr "Description"

4. Compilation and Build

To test your changes, you can compile the catalogs and build the English site. The portal’s Makefile does this automatically when compiling:

make clean && make

The compiler will generate the binary .mo files and build the English site under _build/html/en-US/.

Style Rules for Translation

  • Maintain markup formatting: Do not modify or remove RST formatting characters such as asterisks (*, **), links, custom roles (for example, :mark:`text`), or code blocks.

  • Preserve file names and paths: File paths, module names, and console commands should not be translated, unless they are explanations inside a comment or instructional text.

  • Tone of the text: Keep the tone consistent with the original document (close, friendly, and professional).