Traduciendo el libro de texto
El inglés es el idioma fuente autorizado para el libro de texto. El español se mantiene en los catálogos de gettext PO para que ambas ediciones compartan la misma estructura, ecuaciones, cifras, referencias cruzadas y archivos fuente.
Terminología
Sigue la guía técnica de traducción inglés-español para toda la terminología técnica. Añade nuevos términos a esa guía cuando los traductores acuerden una traducción preferida. No se deben traducir nombres de productos, ecuaciones, fórmulas químicas ni símbolos de unidades SI.
Actualización de los catálogos españoles
Del directorio Textbook , extrae los mensajes actuales en inglés y intégralos en los catálogos en español:
python -m sphinx -b gettext . locale/pot
sphinx-intl update -p locale/pot -l es
Editar archivos bajo locale/es/LC_MESSAGES. No editar los archivos POT generados para traducir contenido. Los mensajes en inglés cambiados se vuelven borrosos o sin traducir y no se muestran hasta que son traducidos y publicados por el flujo de trabajo automatizado de traducción.
Pruebas
Compila ambas ediciones antes de enviar una solicitud de tirada:
python -m sphinx -b html . _build/html
python -m sphinx -b html -D language=es . _build/html/es
Comprueba que las referencias cruzadas, ecuaciones, terminología, unidades, leyendas de imagen y el cambiador de idioma funcionen en ambas ediciones. Las pull requests ejecutan automáticamente ambas versiones.
Política de revisión
La edición en español está traducida automáticamente y claramente identificada como tal en cada página. Las traducciones de Azure que superen las comprobaciones estructurales pueden publicarse sin revisión humana previa. Se fomentan correcciones de revisores de la materia de habla hispana, especialmente en cuanto a especificaciones, instrucciones de funcionamiento, información de seguridad y terminología técnica.
Los ejemplos de redacción de RST que demuestran la sintaxis literal de backtick y roles se mantienen intencionadamente en inglés. Su propósito es mostrar el marcado exacto de la fuente en lugar de proporcionar contenido de libro de texto a los lectores españoles.
Integración Weblate
El repositorio está listo para conectarse a un proyecto Weblate. Configura Weblate para usar las plantillas POT en Textbook/locale/pot y traducciones en Textbook/locale/<language>/LC_MESSAGES. Activa el complemento Update PO files de Weblate para que coincida con POT (msgmerge) para el proyecto. Weblate debe enviar cambios de traducción mediante pull requests para que la compilación bilingüe de Sphinx pase antes de que los catálogos se fusionen.
El proyecto externo Weblate no se crea automáticamente porque sus permisos de alojamiento, propiedad, acceso y revisor deben ser seleccionados por un administrador del repositorio AguaClara Reach.
Traducción automática con Azure
El repositorio incluye scripts/translate_po_azure.py for preparing a terminology-guided machine translation. Copy .azure-translator.env.example to .azure-translator.env e introduce la clave de recurso, el punto final y la región. El archivo de credenciales es ignorado por Git y nunca debe ser confirmado.
Revisa la conexión y previsualiza la cuota sin modificar los catálogos:
python scripts/translate_po_azure.py --connection-test
python scripts/translate_po_azure.py --include-fuzzy
Traduce y publica una pequeña muestra para su revisión:
python scripts/translate_po_azure.py --catalog AIDE/Specifications_PF.po --limit 20 --translate --publish
Después de revisar la muestra, traduce y publica todas las entradas restantes y difusas con:
python scripts/translate_po_azure.py --include-fuzzy --translate --publish
La herramienta protege los roles, enlaces, sustituciones, números y marcadores de posición de Sphinx; aplica terminología de múltiples palabras de la guía técnica de traducción; limita las solicitudes de velocidad para el nivel Azure F0; y rechaza entradas que no superan comprobaciones estructurales. Los detalles de las entradas rechazadas se escriben para _build/azure-translation-report.json.