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/localescontains Sphinx locale files that were auto-converted from the files in
jsons/by the helper script below.
src/sphinx_book_theme/_compile_translations.pyis a helper script to auto-generate Sphinx locale files from the JSONs in
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.
This will download a JSON file with a bunch of
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
prettierformatter 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
This will generate the locale files (
.mo) that Sphinx uses in its translation machinery, and put them in
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.
python src/sphinx_book_theme/_compile_translations.py and this will update the