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 injsons/
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 injsons/
.
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.
Go to the smodin.io service
Select as many languages as you like.
Type in the phrase you’d like to translate.
Click
TRANSLATE
and thenDownload JSON
.This will download a JSON file with a bunch of
language-code: translated-phrase
mappings.Put this JSON in the
jsons/
folder, and rename it to be the phrase you’ve translated in English. So if the original phrase isMy phrase
, you should name the fileMy phrase.json
.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
Run
python src/sphinx_book_theme/_compile_translations.py
This will generate the locale files (
.mo
) that Sphinx uses in its translation machinery, and put them inlocales/<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.