Skip to main content
`Ctrl`+`K`
⚠️The latest release refactored our HTML, so double-check your custom CSS rules!⚠️

# 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.