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.
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)
Extract the strings to translate:
pybabel extract . -o locale/theme.pot
Create a message catalog (changing the
--locale
option as desired):pybabel init --input-file=locale/theme.pot --domain=theme --output-dir=locale --locale=fr
Translate the message catalog by editing the file.
Compile the message catalog:
pybabel compile --directory=locale --domain=theme