Guía de Traducción de la Documentación

Cómo mantener nuestro portal multi-idioma.

Authors:
Copyright:

CC-BY-SA 4.0 o >

Organization:

Fundación MxOS, A.C.

Descripción

Esta guía documenta el flujo de trabajo para traducir y mantener actualizados los documentos del portal de documentación de la Fundación MxOS.

¿Cómo funciona la traducción en MxOS?

El portal utiliza el sistema de internacionalización (i18n) nativo de Sphinx basado en gettext.

  • El idioma de origen de toda la documentación es el español de México (es-MX).

  • Las traducciones al inglés (en-US) y otros idiomas se realizan traduciendo catálogos de mensajes (archivos .po).

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

Proceso de Traducción Paso a Paso

Cuando creas o editas un documento en español, debes seguir estos pasos para actualizar y generar su traducción al inglés.

1. Extracción de Mensajes (POT)

Primero, debes extraer todas las cadenas de texto del portal en plantillas de traducción (archivos .pot). Ejecuta lo siguiente desde la raíz del portal:

make gettext

(O directamente usando sphinx-build: ``sphinx-build -M gettext content _build``)

2. Actualización de Catálogos (.po)

A continuación, sincroniza las nuevas cadenas con los catálogos del idioma destino (en este caso, inglés). Esto fusionará los cambios nuevos sin perder las traducciones que ya existen:

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

Esto creará o actualizará los archivos .po dentro de content/locale/en/LC_MESSAGES/.

3. Traducir Cadenas

Abre los archivos .po correspondientes con tu editor de texto preferido (o una herramienta como Poedit). Verás bloques como este:

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

Completa la traducción ingresando la traducción correspondiente en msgstr:

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

4. Compilación y Construcción

Para probar tus cambios, puedes compilar los catálogos y construir el sitio en inglés. El Makefile del portal hace esto automáticamente al compilar:

make clean && make

El compilador generará los archivos binarios .mo y construirá el sitio en inglés en _build/html/en-US/.

Reglas de Estilo para la Traducción

  • Mantener formato de marcado: No modifiques ni elimines los caracteres de formato RST como asteriscos (*, **), enlaces, roles personalizados (por ejemplo, :mark:`texto`) o bloques de código.

  • Conservar nombres de archivos y rutas: Las rutas a archivos, nombres de módulos y comandos de consola no deben traducirse, a menos que sean explicaciones dentro de un comentario o texto instructivo.

  • Tono del texto: Mantén el tono consistente con el documento original (cercano, amigable y profesional).