.. _user-guide-i18n:

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 <https://github.com/pydata/pydata-sphinx-theme/tree/main/src/pydata_sphinx_theme/locale>`__.
  To add another language, refer to the :ref:`localizing-the-theme` and :ref:`adding-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 :doc:`the user guide <index>` for examples of these configurable strings).
  To translate these strings, see the :ref:`translating-configurable-strings` section in this page.

.. _translating-configurable-strings:

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 <https://babel.pocoo.org/en/latest/installation.html>`__ to handle your
documentation translations.

#. In your ``conf.py`` file:

   .. code-block:: python

      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)

#. Extract the strings to localize:

   .. code-block:: bash

      pybabel extract . -o locale/messages.pot

#. Create a message catalog by specifying the `ISO 639-1 code <https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>`__ for the new language (using the ``--locale`` flag):

   .. code-block:: bash

      # for example, to add French (ISO 639-1 code: fr)
      pybabel init --input-file=locale/messages.pot --domain=messages --output-dir=locale --locale=fr


#. Translate the message catalog by editing the file.

#. Compile the message catalog:

   .. code-block:: bash

      pybabel compile --directory=locale --domain=messages

Done! Your configurable strings are now localized.