DOCS: Add internationalization instructions

docs/community/i18n.rst

@@ -0,0 +1,95 @@
+Internationalization
+====================
+
+.. warning::
+
+   This theme is still in the process of setting up internationalization.
+   Some of the text below may not yet be correct (for example, we do not yet have a ``locales/`` directory).
+   Follow these issues to track progress:
+
+   - https://github.com/pydata/pydata-sphinx-theme/issues/1162
+   - https://github.com/pydata/pydata-sphinx-theme/issues/257
+
+Internationalization (I18N) and localization (L10N) is performed using `Gettext <https://docs.python.org/3/library/gettext.html>`__.
+Gettext reads a program's source and extracts text that has been marked as translatable, known as "source strings.
+Gettext uses three types of files:
+
+PO file (``.po``)
+  A `Portable Object (PO) file <https://www.gnu.org/software/gettext/manual/gettext.html#PO-Files>`__ is made up of many entries.
+  Each entry holds the relation between a source string and its translation.
+  ``msgid`` contains the **source string**, and ``msgstr`` contains the **translation**.
+  In a given PO file, all translations are expressed in a single target language.
+  PO files are also known as "message catalogs".
+
+  Entries begin with comments, on lines starting with the character ``#``.
+  Comments are created and maintained by Gettext.
+  Comment lines starting with ``#:`` contain references to the program's source.
+  These references allow a human translator to find the source strings in their original context.
+  Comment lines starting with ``#,`` contain flags like ``python-format``, which indicates that the source string contains placeholders like ``%(copyright)s``.
+POT file (``.pot``)
+  A Portable Object Template (POT) file is the same as a PO file, except the translations are empty, so that it can be used as a template for new languages.
+MO file (``.mo``)
+  A Machine Object (MO) file is a binary version of a PO file. PO files are compiled to MO files, which are required by Gettext.
+
+.. _adding-natural-language-text:
+
+Adding natural language text
+----------------------------
+
+All natural language text must be marked as translatable, so that it can be extracted by Gettext and translated by humans.
+
+Jinja2 provides a ``trans`` block and a ``_()`` function to mark text as translatable.
+`Please refer to the Jinja2 documentation <https://jinja.palletsprojects.com/en/2.11.x/templates/#i18n>`__.
+Remember to `manually escape <https://jinja.palletsprojects.com/en/2.11.x/templates/#working-with-manual-escaping>`__ variables if needed.
+
+Then, complete the steps for :ref:`changing-natural-language-text`.
+
+.. _changing-natural-language-text:
+
+Changing natural language text
+------------------------------
+
+#. Edit the natural language text as desired.
+
+#. Update the message catalog template (POT file):
+
+   .. code-block:: bash
+
+      python setup.py extract_messages
+
+#. Update the message catalogs (PO files):
+
+   .. code-block:: bash
+
+      python setup.py update_catalog
+
+.. _translating-the-theme:
+
+Translating the theme
+---------------------
+
+These steps use the Spanish language as an example.
+To translate the theme to another language, replace ``es`` with the language's two-letter lowercase `ISO 639-1 code <https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>`__.
+
+#. If the language's code matches no sub-directory of the `pydata_sphinx_theme/locale <https://github.com/pydata/pydata-sphinx-theme/tree/main/pydata_sphinx_theme/locale>`__ directory, initialize the language's message catalog (PO file):
+
+   .. code-block:: bash
+
+      python setup.py init_catalog -l es
+
+#. Edit the language's message catalog at ``pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po``. For each source string introduced by the ``msgid`` keyword, add its translation after the ``msgstr`` keyword.
+
+#. Compile the message catalogs of every language. This creates or updates the MO files:
+
+.. code-block:: bash
+
+   python setup.py compile_catalog
+
+
+References
+----------
+
+I18N and L10N are deep topics. Here, we only cover the bare minimum needed to fulfill basics technical tasks. You might like:
+
+-  `Internationalis(z)ing Code <https://www.youtube.com/watch?v=0j74jcxSunY>`__ by Computerphile on YouTube
+-  `Falsehoods Programmers Believe About Language <http://garbled.benhamill.com/2017/04/18/falsehoods-programmers-believe-about-language>`__ by Ben Hamill

docs/community/index.md

@@ -16,6 +16,7 @@ setup
 structure
 topics
 manual
+i18n
 bootstrap
 ```
 

docs/user_guide/i18n.rst

@@ -0,0 +1,72 @@
+Internationalization
+====================
+
+This theme contains translatable strings.
+There are two kinds of strings contained in this theme, with slightly different steps to translate each.
+
+**Built-in strings** are hard-coded in the theme's templates, and will automatically be translated if the language is `supported <https://github.com/pydata/pydata-sphinx-theme/tree/master/pydata_sphinx_theme/locale>`__.
+To add another language, see :ref:`translating-the-theme`.
+
+**Configurable strings** are user-defined in ``html_theme_options`` (see other sections in :doc:`the user guide<index>` for examples).
+To translate these strings, see the section below.
+
+Translating configurable strings
+--------------------------------
+
+These are instructions for translating configurable strings (those that are customizable in ``html_theme_options``).
+The 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:
+
+   .. code-block:: python
+
+      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:
+
+   .. code-block:: bash
+
+      pybabel extract . -o locale/theme.pot
+
+#. Create a message catalog (changing the ``--locale`` option as desired):
+
+   .. code-block:: bash
+
+      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:
+
+   .. code-block:: bash
+
+      pybabel compile --directory=locale --domain=theme

docs/user_guide/index.md

@@ -47,6 +47,7 @@ announcements
 version-dropdown
 search
 keyboard-shortcuts
+i18n
 ```
 
 ```{toctree}