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.