====================================== Guía de Traducción de la Documentación ====================================== -------------------------------------------- Cómo mantener nuestro portal multi-idioma. -------------------------------------------- :Authors: - Gemini AI :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//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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: po #: ../../content/documentación/guias/traducción.rst:14 msgid "Descripción" msgstr "" Completa la traducción ingresando la traducción correspondiente en ``msgstr``: .. code-block:: po #: ../../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: .. code-block:: bash 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).