Review

Author: StanFromIreland

.github/workflows/tests.yml

@@ -71,7 +71,7 @@ jobs:
           pip install -r requirements.txt
       - name: Remove locale file for testing
         shell: bash
-        run: rm -rf python_docs_theme/locales/pt_BR/
+        run: rm -rf python_docs_theme/locale/pt_BR/
       - run: python babel_runner.py extract
       - run: python babel_runner.py init -l pt_BR
       - run: python babel_runner.py update
@@ -80,7 +80,7 @@ jobs:
       - run: python babel_runner.py compile -l pt_BR
       - name: Print .pot file
         shell: bash
-        run: cat python_docs_theme/locales/messages.pot
+        run: cat python_docs_theme/locale/messages.pot
       - name: Print .po file
         shell: bash
-        run: cat python_docs_theme/locales/pt_BR/LC_MESSAGES/messages.po
+        run: cat python_docs_theme/locale/pt_BR/LC_MESSAGES/messages.po

babel_runner.py

@@ -1,5 +1,5 @@
-#!/usr/bin/env python3
 """Script for handling translations with Babel"""
+
 from __future__ import annotations
 
 import argparse
@@ -8,18 +8,18 @@
 import tomllib
 from pathlib import Path
 
-PROJECT_DIR = Path(__file__).resolve().parent
-PYPROJECT_TOML = PROJECT_DIR / "pyproject.toml"
-INIT_PY = PROJECT_DIR / "python_docs_theme" / "__init__.py"
-
 # Global variables used by pybabel below (paths relative to PROJECT_DIR)
-DOMAIN = "messages"
+DOMAIN = "python-docs-theme"
 COPYRIGHT_HOLDER = "Python Software Foundation"
 SOURCE_DIR = "python_docs_theme"
-LOCALES_DIR = f"{SOURCE_DIR}/locales"
-POT_FILE = Path(LOCALES_DIR, f"{DOMAIN}.pot")
 MAPPING_FILE = ".babel.cfg"
 
+PROJECT_DIR = Path(__file__).resolve().parent
+PYPROJECT_TOML = PROJECT_DIR / "pyproject.toml"
+INIT_PY = PROJECT_DIR / SOURCE_DIR / "__init__.py"
+LOCALES_DIR = f"{SOURCE_DIR}/locale"
+POT_FILE = Path(LOCALES_DIR, f"{DOMAIN}.pot")
+
 
 def get_project_info() -> dict:
     """Retrieve project's info to populate the message catalog template"""
@@ -75,21 +75,32 @@ def init_locale(locale: str) -> None:
     if pofile.exists():
         print(f"There is already a message catalog for locale {locale}, skipping.")
         return
-    cmd = ["pybabel", "init", "-i", POT_FILE, "-d", LOCALES_DIR, "-l", locale]
+    cmd = [
+        "pybabel",
+        "init",
+        "-i",
+        POT_FILE,
+        "-d",
+        LOCALES_DIR,
+        "-D",
+        DOMAIN,
+        "-l",
+        locale,
+    ]
     subprocess.run(cmd, cwd=PROJECT_DIR, check=True)
 
 
 def update_catalogs(locale: str) -> None:
     """Update translations from existing message catalogs"""
-    cmd = ["pybabel", "update", "-i", POT_FILE, "-d", LOCALES_DIR]
+    cmd = ["pybabel", "update", "-i", POT_FILE, "-d", LOCALES_DIR, "-D", DOMAIN]
     if locale:
         cmd.extend(["-l", locale])
     subprocess.run(cmd, cwd=PROJECT_DIR, check=True)
 
 
 def compile_catalogs(locale: str) -> None:
     """Compile existing message catalogs"""
-    cmd = ["pybabel", "compile", "-d", LOCALES_DIR]
+    cmd = ["pybabel", "compile", "-d", LOCALES_DIR, "-D", DOMAIN]
     if locale:
         cmd.extend(["-l", locale])
     subprocess.run(cmd, cwd=PROJECT_DIR, check=True)

python_docs_theme/__init__.py

@@ -1,36 +1,31 @@
 from __future__ import annotations
 
-import gettext
-import os
 from pathlib import Path
 
+from sphinx.locale import get_translation
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from sphinx.application import Sphinx
-    from sphinx.util.typing import ExtensionMetadata
+    from sphinx.application import Sphinx  # noqa: F401
+    from sphinx.util.typing import ExtensionMetadata  # noqa: F401
 
 __version__ = "2025.5"
 
 THEME_PATH = Path(__file__).resolve().parent
+LOCALE_DIR = THEME_PATH / "locale"
+MESSAGE_CATALOG_NAME = "python-docs-theme"
 
 
-def setup_translations(app):
-    translation = gettext.translation(
-        domain="messages",
-        localedir=os.fspath(THEME_PATH / "locales"),
-        languages=[app.config.language],
-        fallback=True,
-    )
-    app.builder.templates.environment.install_gettext_translations(
-        translation, newstyle=True
-    )
-
-
-def setup(app: Sphinx) -> ExtensionMetadata:
+def setup(app):
     app.require_sphinx("7.3")
-
-    app.connect("builder-inited", setup_translations)
     app.add_html_theme("python_docs_theme", str(THEME_PATH))
+    app.add_message_catalog(MESSAGE_CATALOG_NAME, LOCALE_DIR)
+
+    def add_translation_to_context(app, pagename, templatename, context, doctree):
+        _ = get_translation(MESSAGE_CATALOG_NAME)
+        context["_"] = context["gettext"] = context["ngettext"] = _
+
+    app.connect("html-page-context", add_translation_to_context)
 
     return {
         "version": __version__,