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 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 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": "<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