TEMP: setup theme translation

.gitignore

@@ -5,3 +5,7 @@ dist
 
 # Node
 node_modules
+
+# Translations
+.doctrees
+*.mo

Makefile

@@ -0,0 +1,30 @@
+# VARIABLE      = value
+MESSAGE_CATALOG_NAME = iati-sphinx-theme
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  extract       to extract translatable strings into POT files"
+
+.PHONY: extract
+extract:
+	@echo "Extracting messages from theme templates"
+	pybabel extract -o iati_sphinx_theme/locale/$(MESSAGE_CATALOG_NAME).pot -F babel.cfg iati_sphinx_theme
+	@echo "Extracting messages from docs/conf.py"
+	pybabel extract -o docs/locale/${MESSAGE_CATALOG_NAME}.pot -F babel.cfg docs/conf.py
+	@echo "Extracting messages from RST files"
+	sphinx-build -b gettext docs docs/locale
+
+.PHONY: init
+init:
+	pybabel init -i iati_sphinx_theme/locale/$(MESSAGE_CATALOG_NAME).pot -d iati_sphinx_theme/locale --domain=$(MESSAGE_CATALOG_NAME) -l ${lang}
+	sphinx-intl update -p docs/locale -d docs/locale -l ${lang}
+
+.PHONY: update
+update:
+	pybabel update -i iati_sphinx_theme/locale/$(MESSAGE_CATALOG_NAME).pot -d iati_sphinx_theme/locale --domain=${MESSAGE_CATALOG_NAME}
+	sphinx-intl update -p docs/locale -d docs/locale
+
+.PHONE: compile
+compile:
+	pybabel compile --directory=iati_sphinx_theme/locale --domain=${MESSAGE_CATALOG_NAME}

README.md

@@ -73,3 +73,31 @@ To run a local version of the theme with another project, e.g. `my-docs`, take t
    pip install sphinx-autobuild
    sphinx-autobuild docs docs/_build/html
    ```
+
+### Translation
+
+1. Extract `.pot` file
+
+   ```
+   make extract
+   ```
+
+2. Update existing `.po` files based on `.pot` file
+
+   ```
+   make update
+   ```
+
+3. Optionally, initialise a `.po` file for a new language
+
+   ```
+   make init lang=es
+   ```
+
+4. Add translations to the `.po` files
+
+5. Compile to `.mo` files
+
+   ```
+   make compile
+   ```

babel.cfg

@@ -0,0 +1,6 @@
+# See https://github.com/python-babel/babel/blob/2a1709a7768f6f07c3d2dbfdb03d3c8a6bd80aef/docs/messages.rst#extraction-method-mapping-and-configuration
+[python: **.py]
+[jinja2: **.html]
+encoding = utf-8
+ignore_tags = script,style
+include_attrs = alt title summary placeholder

docs/conf.py

@@ -3,12 +3,21 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+from os import path
+
+import sphinx.application
+from sphinx.locale import get_translation
+
+catalog = "iati-sphinx-theme"
+_ = get_translation(catalog)
+
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "IATI Sphinx Theme"
-copyright = "2024 IATI Secretariat"
 author = "IATI Secretariat"
+language = "en"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -26,4 +35,16 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "iati_sphinx_theme"
+html_theme_options = {
+    "header_title_text": _("Title"),
+}
+
 todo_include_todos = True
+
+
+locale_dirs = ["locale/"]
+
+
+def setup(app: sphinx.application.Sphinx) -> None:
+    locale_path = path.join(path.abspath(path.dirname(__file__)), "locale")
+    app.add_message_catalog("iati-sphinx-theme", locale_path)

docs/locale/es/LC_MESSAGES/iati-sphinx-theme.po

@@ -0,0 +1,28 @@
+# Spanish translations for PROJECT.
+# Copyright (C) 2024 ORGANIZATION
+# This file is distributed under the same license as the PROJECT project.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PROJECT VERSION\n"
+"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
+"POT-Creation-Date: 2024-10-03 15:28+0300\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: es\n"
+"Language-Team: es <[email protected]>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.14.0\n"
+
+#: docs/conf.py:39
+msgid "Title 2"
+msgstr ""
+
+#~ msgid "Title"
+#~ msgstr ""
+

docs/locale/es/LC_MESSAGES/index.po

@@ -0,0 +1,68 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C)
+# This file is distributed under the same license as the IATI Sphinx Theme
+# package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: IATI Sphinx Theme \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2024-10-03 15:18+0300\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: es\n"
+"Language-Team: es <[email protected]>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.14.0\n"
+
+#: ../index.rst:5
+msgid "Home"
+msgstr ""
+
+#: ../index.rst:10
+msgid "Development"
+msgstr ""
+
+#: ../index.rst:3
+msgid "IATI Sphinx Theme"
+msgstr ""
+
+#: ../index.rst:19
+msgid "Installation"
+msgstr ""
+
+#: ../index.rst:22
+msgid "Install the theme in your Sphinx project."
+msgstr ""
+
+#: ../index.rst:29
+msgid "In your project's :code:`conf.py` set the :code:`html_theme`."
+msgstr ""
+
+#: ../index.rst:36
+msgid "Configuration"
+msgstr ""
+
+#: ../index.rst:39
+msgid "Plausible Analytics"
+msgstr ""
+
+#: ../index.rst:41
+msgid ""
+"To integrate with Plausible Analytics, add the :code:`plausible_domain` "
+"option in your project's :code:`conf.py` file."
+msgstr ""
+
+#: ../index.rst:43
+msgid ""
+"If your docs site is a subdomain for the site it is documenting, use the "
+"top level domain for cross-subdomain tracking. For example, for the "
+"Sphinx site :code:`docs.example.com`, use :code:`example.com` as your "
+":code:`plausible_domain`."
+msgstr ""
+