docs: add documentation for consumers to translate the theme

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.