diff --git a/docs/index.rst b/docs/index.rst index e9c094e..ce02574 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -64,3 +64,53 @@ For example, for the Sphinx site :code:`docs.example.com`, use :code:`example.co html_theme_options = { "plausible_domain": "example.com" } + +Translation +=========== + +The IATI Sphinx Theme is translatable. + +Strings built into the theme will be translated automatically into supported languages. +The following languages are currently supported: + +- English (:code:`en`) + +User-defined strings must be translated by the user of the theme. +These are configured in your :code:`conf.py` file under :code:`html_theme_options`. +In order to translate these, complete the following steps in the same location as the `conf.py` file: + +1. Mark strings as translatable using :code:`sphinx.locale.get_translation`, usually renamed to :code:`_()`. + +.. code-block:: python + + import os + from sphinx.locale import get_translation + + MESSAGE_CATALOG_NAME = "iati-sphinx-theme" + _ = get_translation(MESSAGE_CATALOG_NAME) + + html_theme_options = { + "header_title_text": _("Title"), + } + + def setup(app): + locale_path = os.path.join(os.path.abspath(os.path.dirname(__file__)), "locale") + app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_path) + +2. Extract translatable strings to :code:`locale/iati-sphinx-theme.pot`. + +.. code-block:: + + pybabel extract conf.py -o locale/iati-sphinx-theme.pot + +3. Create or update :code:`.po` files for desired languages. + +.. code-block:: + + # To add a new language + pybabel init -i locale/iati-sphinx-theme.pot -d locale --domain=iati-sphinx-theme -l es + + # To update an existing language + pybabel update -i locale/iati-sphinx-theme.pot -d locale --domain=iati-sphinx-theme -l es + +4. Continue with your project's usual translation workflow.