Language selection#

If your documentation is translated into multiple languages, Clarity Theme for Sphinx provides a locale dropdown for quick switching.

../../_images/language-select.gif

Enable language selection

The selector is disabled by default. Define available locales and a pattern for locale URLs to enable it.

  1. Define available translations with html_theme_options’s language_select option. Translations are a dict of <language-code>: <language-name>. For example, in conf.py:

    html_theme_options = {
   "language_select": {
      "en": "English",
      "cs": "čeština",
      "ua": "Українська",
   }
}

  2. Define a URL pattern with html_theme_options’s language_url option. Each language version must live at distinct URL address. For example:

    • /docs/en/latest/quickstart.html

    • /docs/cs/latest/quickstart.html

    • /docs/ua/latest/quickstart.html

    URL pattern can use placeholders:

    • {language} → <language-code> from language_select

    • {page} → current page path

    For the example above: /docs/{language}/latest/{page}.

    html_theme_options = {
   "language_select": {
      "en": "English",
      "cs": "čeština",
      "ua": "Українська",
   },
   "language_url": "/docs/{language}/latest/{page}",
}