Skip to main content
`Ctrl`+`K`

# Internationalization

This theme contains localizable (translatable) strings. There are two kinds of strings in this theme, with different steps to translate each:

- Built-in strings are hard-coded in the theme’s templates. They will be translated by volunteers if the language is supported. To add another language, refer to the Localizing the theme and Adding a new language sections in the documentation.

- Configurable strings are user-defined with the `html_theme_options` variable in your `conf.py` file (see other sections in the user guide for examples of these configurable strings). To translate these strings, see the Translating configurable strings section in this page.

## Translating configurable strings

These instructions are for translating configurable strings (those that are customizable in `html_theme_options` within the `conf.py` file).

These instructions assume that you store your translations in a `locale` directory under your documentation directory and that you want to use `messages` as the name of the message catalog for these strings (you can change this name if needed).

Note you will also need to install pybabel to handle your documentation translations.

1. In your `conf.py` file:

       import os.path
       from sphinx.locale import get_translation

       catalog = "messages"
       _ = get_translation(catalog)

       html_theme_options = {
           "search_bar_text": _("Search the docs..."),

           # You only need to translate the following if you use these features.
           "icon_links_label": _("Quick Links"),
           "icon_links": [
               {
                   "name": _("GitHub"),
                   "url": "https://github.com/<your-org>/<your-repo>",
                   "icon": "fab fa-github-square",
               },
           ],
           "external_links": [
               {
                   "name": _("link-one-name"),
                   "url": "https://<link-one>",
               },
           ],
       }

       def setup(app):
           locale_dir = os.path.join(os.path.abspath(os.path.dirname(__file__)), "locale")

           app.add_message_catalog(catalog, locale_dir)

2. Extract the strings to localize:

       pybabel extract . -o locale/messages.pot

3. Create a message catalog by specifying the ISO 639-1 code for the new language (using the `--locale` flag):

       # for example, to add French (ISO 639-1 code: fr)
       pybabel init --input-file=locale/messages.pot --domain=messages --output-dir=locale --locale=fr

4. Translate the message catalog by editing the file.

5. Compile the message catalog:

       pybabel compile --directory=locale --domain=messages

Done! Your configurable strings are now localized.