Internationalization

This theme contains 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 automatically be translated if the language is supported. To add another language, see Add translations to translateable text.

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). To translate these strings, see the section below.

Translating configurable strings

These instructions are for translating configurable strings (those that are customizable in html_theme_options).

These instructions assume that you store your translations in a locale directory under your documentation directory, and that you want to use theme as the name of the message catalog for these strings.

1. In your conf.py file:

   import os.path
   from sphinx.locale import get_translation
   
   catalog = "theme"
   _ = 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 translate:

   pybabel extract . -o locale/theme.pot
   

3. Create a message catalog (changing the --locale option as desired):

   pybabel init --input-file=locale/theme.pot --domain=theme --output-dir=locale --locale=fr
   

4. Translate the message catalog by editing the file.

5. Compile the message catalog:

   pybabel compile --directory=locale --domain=theme