Enable theme translation

.github/workflows/pypi-package.yml

@@ -22,6 +22,13 @@ jobs:
 
     steps:
       - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+
+      - name: Compile translations
+        run: |
+          pip install --upgrade pip
+          pip install -r requirements.txt
+          python babel_runner.py compile
 
       - uses: hynek/build-and-inspect-python-package@v2
 

.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 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,10 +80,7 @@ jobs:
       - run: python babel_runner.py compile -l pt_BR
       - name: Print .pot file
         shell: bash
-        run: cat locales/messages.pot
+        run: cat python_docs_theme/locale/python-docs-theme.pot
       - name: Print .po file
         shell: bash
-        run: cat locales/pt_BR/LC_MESSAGES/messages.po
-      - name: list files in locales dir
-        shell: bash
-        run: ls -R locales/
+        run: cat python_docs_theme/locale/pt_BR/LC_MESSAGES/python-docs-theme.po

babel_runner.py

@@ -1,5 +1,5 @@
-#!/usr/bin/venv 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"
-LOCALES_DIR = "locales"
-POT_FILE = Path(LOCALES_DIR, f"{DOMAIN}.pot")
 SOURCE_DIR = "python_docs_theme"
 MAPPING_FILE = ".babel.cfg"
 
+PROJECT_DIR = Path(__file__).resolve().parent
+PYPROJECT_TOML = Path(PROJECT_DIR, "pyproject.toml")
+INIT_PY = PROJECT_DIR / SOURCE_DIR / "__init__.py"
+LOCALES_DIR = Path(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

@@ -2,6 +2,8 @@
 
 from pathlib import Path
 
+from sphinx.locale import get_translation
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -10,12 +12,21 @@
 __version__ = "2025.5"
 
 THEME_PATH = Path(__file__).resolve().parent
+LOCALE_DIR = THEME_PATH / "locale"
+MESSAGE_CATALOG_NAME = "python-docs-theme"
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
     app.require_sphinx("7.3")
 
     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__,

python_docs_theme/locale/pl/LC_MESSAGES/python-docs-theme.po

@@ -0,0 +1,127 @@
+# Polish (Poland) translations for python-docs-theme.
+# Copyright (C) 2025 Python Software Foundation
+# This file is distributed under the same license as the python-docs-theme
+# project.
+# Stan Ulbrych, 2025.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: python-docs-theme 2025.5\n"
+"Report-Msgid-Bugs-To: https://github.com/python/python-docs-theme/issues\n"
+"POT-Creation-Date: 2025-08-07 19:09+0200\n"
+"PO-Revision-Date: 2025-08-07 15:11+0200\n"
+"Last-Translator: Stan Ulbrych \n"
+"Language: pl\n"
+"Language-Team: pl <[email protected]>\n"
+"Plural-Forms: nplurals=3; plural=(n==1 ? 0 : n%10>=2 && n%10<=4 && "
+"(n%100<10 || n%100>=20) ? 1 : 2);\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.16.0\n"
+
+#: python_docs_theme/footerdonate.html:1
+msgid "The Python Software Foundation is a non-profit corporation."
+msgstr "Python Software Foundation jest organizacją non-profit."
+
+#: python_docs_theme/footerdonate.html:2
+msgid "Please donate."
+msgstr "Prosimy o wsparcie."
+
+#: python_docs_theme/layout.html:6
+msgid "Navigation"
+msgstr "Nawigacja"
+
+#: python_docs_theme/layout.html:51 python_docs_theme/layout.html:111
+msgid "Quick search"
+msgstr "Szybkie wyszukiwanie"
+
+#: python_docs_theme/layout.html:52 python_docs_theme/layout.html:112
+msgid "Go"
+msgstr "Szukaj"
+
+#: python_docs_theme/layout.html:60
+msgid "Theme"
+msgstr "Motyw"
+
+#: python_docs_theme/layout.html:62
+msgid "Auto"
+msgstr "auto"
+
+#: python_docs_theme/layout.html:63
+msgid "Light"
+msgstr "jasny"
+
+#: python_docs_theme/layout.html:64
+msgid "Dark"
+msgstr "ciemny"
+
+#: python_docs_theme/layout.html:96
+msgid "Menu"
+msgstr "Menu"
+
+#: python_docs_theme/layout.html:142
+msgid "Copyright"
+msgstr "Prawa autorskie"
+
+#: python_docs_theme/layout.html:147
+msgid ""
+"This page is licensed under the Python Software Foundation License "
+"Version 2."
+msgstr ""
+"Ta strona jest objęta licencją Python Software "
+"Foundation w wersji 2."
+
+#: python_docs_theme/layout.html:149
+msgid ""
+"Examples, recipes, and other code in the documentation are additionally "
+"licensed under the Zero Clause BSD License."
+msgstr ""
+"Przykłady, przepisy i inny kod w dokumentacji są dodatkowo objęte "
+"licencją Zero Clause BSD."
+
+#: python_docs_theme/layout.html:152
+#, python-format
+msgid ""
+"See <a href=\"%(license_file)s\">History and License</a> for more "
+"information."
+msgstr ""
+"Zobacz <a href=\"%(license_file)s\">Historię i licencję</a> aby uzyskać "
+"więcej informacji."
+
+#: python_docs_theme/layout.html:155
+#, python-format
+msgid "Hosted on %(hosted_on)s."
+msgstr "Hostowane na %(hosted_on)s."
+
+#: python_docs_theme/layout.html:163
+#, python-format
+msgid "Last updated on %(last_updated)s."
+msgstr "Ostatnia aktualizacja %(last_updated)s."
+
+#: python_docs_theme/layout.html:166
+#, python-format
+msgid "<a href=\"%(theme_issues_url)s\">Found a bug</a>?"
+msgstr "<a href=\"%(theme_issues_url)s\">Znalazłeś(-aś) błąd</a>?"
+
+#: python_docs_theme/layout.html:170
+#, python-format
+msgid ""
+"Created using <a href=\"https://www.sphinx-doc.org/\">Sphinx</a> "
+"%(sphinx_version)s."
+msgstr ""
+"Stworzone za pomocą <a href=\"https://www.sphinx-doc.org/\">Sphinx</a> "
+"%(sphinx_version)s."
+
+#: python_docs_theme/static/copybutton.js:30
+#: python_docs_theme/static/copybutton.js:55
+msgid "Copy"
+msgstr "Kopiuj"
+
+#: python_docs_theme/static/copybutton.js:31
+msgid "Copy to clipboard"
+msgstr "Skopiuj do schowka"
+
+#: python_docs_theme/static/copybutton.js:53
+msgid "Copied!"
+msgstr "Skopiowano!"