Translation workflow#

This folder contains code and translations for supporting multiple languages with Sphinx. See the Sphinx internationalization documentation for more details.

Structure of translation files#

Translation source files#

The source files for our translations are hand-edited, and contain the raw mapping of words onto various languages. They are checked in to git history with this repository.

src/sphinx_book_theme/assets/translations/jsons contains a collection of JSON files that define the translation for various phrases in this repository. Each file is a different phrase, and its contents define language codes and translated phrases for each language we support. They were originally created with the smodin.io language translator (see below for how to update them).

Compiled translation files#

The translation source files are compiled at build time (when we run stb compile) automatically. This is executed by the Python script at python src/sphinx_book_theme/_compile_translations.py (more information on that below).

These compiled files are not checked into .git history, but they are bundled with the theme when it is distributed in a package. Here’s a brief explanation of each:

  • src/sphinx_book_theme/theme/sphinx_book_theme/static/locales contains Sphinx locale files that were auto-converted from the files in jsons/ by the helper script below.

  • src/sphinx_book_theme/_compile_translations.py is a helper script to auto-generate Sphinx locale files from the JSONs in jsons/.

Workflow of translations#

Here’s a short workflow of how to add a new translation, assuming that you are translating using the smodin.io service.

  1. Go to the smodin.io service

  2. Select as many languages as you like.

  3. Type in the phrase you’d like to translate.

  4. Click TRANSLATE and then Download JSON.

  5. This will download a JSON file with a bunch of language-code: translated-phrase mappings.

  6. Put this JSON in the jsons/ folder, and rename it to be the phrase you’ve translated in English. So if the original phrase is My phrase, you should name the file My phrase.json.

  7. Run the prettier formatter on this JSON to split it into multiple lines (this makes it easier to read and edit if translations should be updated)

    prettier sphinx_book_theme/translations/jsons/<message name>.json

  8. Run python src/sphinx_book_theme/_compile_translations.py

  9. This will generate the locale files (.mo) that Sphinx uses in its translation machinery, and put them in locales/<language-code>/LC_MESSAGES/<msg>.mo.

Sphinx should now know how to translate this message!

To update a translation#

To update a translation, you may go to the phase you’d like to modify in jsons/, then find the entry for the language you’d like to update, and change its value. Finally, run python src/sphinx_book_theme/_compile_translations.py and this will update the .mo files.