Translating the Textbook
English is the authoritative source language for the textbook. Spanish is maintained in gettext PO catalogs so that both editions share the same structure, equations, figures, cross-references, and source files.
Terminology
Follow the English-Spanish technical translation guide for all technical terminology. Add new terms to that guide when translators agree on a preferred translation. Product names, equations, chemical formulas, and SI unit symbols should not be translated.
Updating the Spanish Catalogs
From the Textbook directory, extract the current English messages and
merge them into the Spanish catalogs:
python -m sphinx -b gettext . locale/pot
sphinx-intl update -p locale/pot -l es
Edit files under locale/es/LC_MESSAGES. Do not edit the generated POT
files to translate content. Changed English messages become fuzzy or
untranslated and are not displayed until they are translated and published by
the automated translation workflow.
Testing
Build both editions before submitting a pull request:
python -m sphinx -b html . _build/html
python -m sphinx -b html -D language=es . _build/html/es
Check that cross-references, equations, terminology, units, image captions, and the language switcher work in both editions. Pull requests automatically run both builds.
Review Policy
The Spanish edition is machine translated and clearly identified as such on every page. Azure translations that pass the structural checks may be published without prior human review. Corrections from Spanish-speaking subject-matter reviewers are encouraged, especially for specifications, operating instructions, safety information, and technical terminology.
RST authoring examples that demonstrate literal backtick and role syntax are intentionally retained in English. Their purpose is to show the exact source markup rather than provide textbook content to Spanish readers.
Weblate Integration
The repository is ready to connect to a Weblate project. Configure Weblate to
use the POT templates in Textbook/locale/pot and translations in
Textbook/locale/<language>/LC_MESSAGES. Enable Weblate’s Update PO files
to match POT (msgmerge) add-on for the project. Weblate should submit
translation changes through pull requests so that the bilingual Sphinx build
must pass before catalogs are merged.
The external Weblate project is not created automatically because its hosting, ownership, access, and reviewer permissions must be selected by an AguaClara Reach repository administrator.
Automated Translation with Azure
The repository includes scripts/translate_po_azure.py for preparing a
terminology-guided machine translation. Copy .azure-translator.env.example
to .azure-translator.env and enter the resource key, endpoint, and region.
The credentials file is ignored by Git and must never be committed.
Check the connection and preview the quota without modifying catalogs:
python scripts/translate_po_azure.py --connection-test
python scripts/translate_po_azure.py --include-fuzzy
Translate and publish a small sample for review:
python scripts/translate_po_azure.py --catalog AIDE/Specifications_PF.po --limit 20 --translate --publish
After reviewing the sample, translate and publish all remaining and fuzzy entries with:
python scripts/translate_po_azure.py --include-fuzzy --translate --publish
The tool protects Sphinx roles, links, substitutions, numbers, and placeholders;
applies multiword terminology from the technical translation guide; rate-limits
requests for the Azure F0 tier; and rejects entries that fail structural checks.
Details of rejected entries are written to
_build/azure-translation-report.json.