BUG - Fix i18n files and compilation for distribution (#2042)

While investigating
#2040 I noticed that
our current release missed the updated `.mo` files.
This was a bug I introduced in
#1959 when reworking
the localisation workflows.

TLD;R—Since we use `stb` to build the theme, I did not realise that
compiling the i18n files had to be done within the `stb package` (I
removed it from the webpack file as this was causing the infinite reload
while working on our docs).

Since this was an easy miss, I added our build and inspect job to the
`pre-release` workflow that runs on a chron job to check our build
process periodically.

Once we merge this, we can make a small release to patch the current
issue.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: gabalafou <[email protected]>

Author: 3 people

.github/workflows/CI.yml

@@ -75,7 +75,7 @@ jobs:
           # if not we use the default version
           # example substitution: tox run -e compile-assets,i18n-compile,py39-tests
           else
-            python -Im tox run -e compile,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests
+            python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests
           fi
       - name: "Upload coverage data to GH artifacts 📤"
         if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev'

.github/workflows/prerelease.yml

@@ -40,6 +40,14 @@ jobs:
           python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests-no-cov
           echo "PYTEST_ERRORS=$?" >> $GITHUB_ENV
 
+      - name: "Build and inspect package 📦"
+        uses: hynek/build-and-inspect-python-package@v2
+        if: matrix.python-version == '3.9'
+        id: baipp
+
+      - run: echo Packages can be found at ${{ steps.baipp.outputs.dist }}
+        if: matrix.python-version == '3.9'
+
       # If either the docs build or the tests resulted in an error, create an issue to note it
       - name: "Create an issue if failure"
         uses: JasonEtco/create-an-issue@v2

docs/community/topics/i18n.rst

@@ -82,7 +82,7 @@ file, and visible to localizers. For example:
 
    {# L10n: Navigation button at the bottom of the page #}
    <button type="button">
-      {{- _("Next page") -}}
+      {{- _('Next page') -}}
    </button>
 
 .. _updating-localization-files:

src/pydata_sphinx_theme/locale/ca/LC_MESSAGES/sphinx.po

@@ -6,7 +6,6 @@
 # Translators:
 # Cristhian Rivera, 2024
 # Oriol Abril-Pla <[email protected]>, 2024
-#
 msgid ""
 msgstr ""
 
@@ -145,11 +144,10 @@ msgstr "Fosc"
 msgid "System Settings"
 msgstr "Configuració del sistema"
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:3
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:4
 #, python-format
 msgid ""
-"Built with the <a href=\"https://pydata-sphinx-"
-"theme.readthedocs.io/en/stable/index.html\">PyData Sphinx Theme</a> "
+"Built with the <a href=\"%(PST_url)s\">PyData Sphinx Theme</a> "
 "%(theme_version)s."
 msgstr ""
 "Construïda amb el <a href=\"https://pydata-sphinx-"

src/pydata_sphinx_theme/locale/cs/LC_MESSAGES/sphinx.po

@@ -141,11 +141,10 @@ msgstr "Tmavý"
 msgid "System Settings"
 msgstr ""
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:3
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:4
 #, python-format
 msgid ""
-"Built with the <a href=\"https://pydata-sphinx-"
-"theme.readthedocs.io/en/stable/index.html\">PyData Sphinx Theme</a> "
+"Built with the <a href=\"%(PST_url)s\">PyData Sphinx Theme</a> "
 "%(theme_version)s."
 msgstr ""
 "Vytvořeno pomocí <a href=\"https://pydata-sphinx-"

src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po

@@ -139,11 +139,10 @@ msgstr ""
 msgid "System Settings"
 msgstr ""
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:3
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:4
 #, python-format
 msgid ""
-"Built with the <a href=\"https://pydata-sphinx-"
-"theme.readthedocs.io/en/stable/index.html\">PyData Sphinx Theme</a> "
+"Built with the <a href=\"%(PST_url)s\">PyData Sphinx Theme</a> "
 "%(theme_version)s."
 msgstr ""
 
@@ -182,3 +181,9 @@ msgstr ""
 
 #~ msgid "light/dark"
 #~ msgstr ""
+
+#~ msgid ""
+#~ "Built with the <a href=\"https://pydata-"
+#~ "sphinx-theme.readthedocs.io/en/stable/index.html\">PyData "
+#~ "Sphinx Theme</a> %(theme_version)s."
+#~ msgstr ""

src/pydata_sphinx_theme/locale/es/LC_MESSAGES/sphinx.po

@@ -8,7 +8,6 @@
 # Cristhian Rivera, 2024
 # Felipe Moreno, 2024
 # Tania Allard, 2024
-#
 msgid ""
 msgstr ""
 
@@ -42,8 +41,7 @@ msgstr "Error"
 
 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/search.html:9
 msgid "Please activate JavaScript to enable the search functionality."
-msgstr ""
-"Por favor, active JavaScript para habilitar la funcionalidad de búsqueda."
+msgstr "Por favor, active JavaScript para habilitar la funcionalidad de búsqueda."
 
 #: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/breadcrumbs.html:6
 msgid "Breadcrumb"
@@ -148,11 +146,10 @@ msgstr "Oscuro"
 msgid "System Settings"
 msgstr "Sistema"
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:3
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:4
 #, python-format
 msgid ""
-"Built with the <a href=\"https://pydata-sphinx-"
-"theme.readthedocs.io/en/stable/index.html\">PyData Sphinx Theme</a> "
+"Built with the <a href=\"%(PST_url)s\">PyData Sphinx Theme</a> "
 "%(theme_version)s."
 msgstr ""
 "Construido con el <a href=\"https://pydata-sphinx-"

src/pydata_sphinx_theme/locale/fr/LC_MESSAGES/sphinx.po

@@ -6,7 +6,6 @@
 # Translators:
 # Rambaud Pierrick <[email protected]>, 2024
 # Denis Bitouzé <[email protected]>, 2024
-#
 msgid ""
 msgstr ""
 
@@ -145,11 +144,10 @@ msgstr "Sombre"
 msgid "System Settings"
 msgstr "Paramètres système"
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:3
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:4
 #, python-format
 msgid ""
-"Built with the <a href=\"https://pydata-sphinx-"
-"theme.readthedocs.io/en/stable/index.html\">PyData Sphinx Theme</a> "
+"Built with the <a href=\"%(PST_url)s\">PyData Sphinx Theme</a> "
 "%(theme_version)s."
 msgstr ""
 "Construit avec le <a href=\"https://pydata-sphinx-"

src/pydata_sphinx_theme/locale/it/LC_MESSAGES/sphinx.po

@@ -141,11 +141,10 @@ msgstr "Scuro"
 msgid "System Settings"
 msgstr ""
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:3
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:4
 #, python-format
 msgid ""
-"Built with the <a href=\"https://pydata-sphinx-"
-"theme.readthedocs.io/en/stable/index.html\">PyData Sphinx Theme</a> "
+"Built with the <a href=\"%(PST_url)s\">PyData Sphinx Theme</a> "
 "%(theme_version)s."
 msgstr ""
 "Prodotto con il tema <a href=\"https://pydata-sphinx-"

src/pydata_sphinx_theme/locale/ja/LC_MESSAGES/sphinx.po

@@ -143,11 +143,10 @@ msgstr "ダーク"
 msgid "System Settings"
 msgstr ""
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:3
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:4
 #, python-format
 msgid ""
-"Built with the <a href=\"https://pydata-sphinx-"
-"theme.readthedocs.io/en/stable/index.html\">PyData Sphinx Theme</a> "
+"Built with the <a href=\"%(PST_url)s\">PyData Sphinx Theme</a> "
 "%(theme_version)s."
 msgstr ""
 "<a href=\"https://pydata-sphinx-"

src/pydata_sphinx_theme/locale/ru/LC_MESSAGES/sphinx.po

@@ -141,11 +141,10 @@ msgstr "темная"
 msgid "System Settings"
 msgstr ""
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:3
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:4
 #, python-format
 msgid ""
-"Built with the <a href=\"https://pydata-sphinx-"
-"theme.readthedocs.io/en/stable/index.html\">PyData Sphinx Theme</a> "
+"Built with the <a href=\"%(PST_url)s\">PyData Sphinx Theme</a> "
 "%(theme_version)s."
 msgstr ""
 "Собрано с использованием темы <a href=\\\"https://pydata-sphinx-"

src/pydata_sphinx_theme/locale/sphinx.pot

@@ -4,11 +4,12 @@
 # project.
 # FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
 #
+#, fuzzy
 msgid ""
 msgstr ""
-"Project-Id-Version: pydata-sphinx-theme 0.16.0rc0\n"
+"Project-Id-Version: pydata-sphinx-theme 0.16.1.dev0\n"
 "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2024-09-30 17:53+0100\n"
+"POT-Creation-Date: 2024-11-18 12:43+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <[email protected]>\n"
@@ -150,11 +151,10 @@ msgstr ""
 msgid "System Settings"
 msgstr ""
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:3
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:4
 #, python-format
 msgid ""
-"Built with the <a href=\"https://pydata-sphinx-"
-"theme.readthedocs.io/en/stable/index.html\">PyData Sphinx Theme</a> "
+"Built with the <a href=\"%(PST_url)s\">PyData Sphinx Theme</a> "
 "%(theme_version)s."
 msgstr ""
 

src/pydata_sphinx_theme/locale/zh/LC_MESSAGES/sphinx.po

@@ -141,11 +141,10 @@ msgstr "暗色"
 msgid "System Settings"
 msgstr ""
 
-#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:3
+#: src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html:4
 #, python-format
 msgid ""
-"Built with the <a href=\"https://pydata-sphinx-"
-"theme.readthedocs.io/en/stable/index.html\">PyData Sphinx Theme</a> "
+"Built with the <a href=\"%(PST_url)s\">PyData Sphinx Theme</a> "
 "%(theme_version)s."
 msgstr ""
 "使用 <a href=\"https://pydata-sphinx-"

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/page-toc.html

@@ -5,7 +5,7 @@
   <div
     id="{{ page_navigation_heading_id }}"
     class="page-toc tocsection onthispage">
-    <i class="fa-solid fa-list"></i> {{ _("On this page") }}
+    <i class="fa-solid fa-list"></i> {{ _('On this page') }}
   </div>
   <nav class="bd-toc-nav page-toc" aria-labelledby="{{ page_navigation_heading_id }}">
     {{ page_toc }}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/theme-version.html

@@ -1,4 +1,7 @@
 {# Displays the version of pydata-sphinx-theme used to build the documentation. #}
 <p class="theme-version">
-  {% trans theme_version=theme_version|e %}Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> {{ theme_version }}.{% endtrans %}
+  <!-- # L10n: Setting the PST URL as an argument as this does not need to be localized -->
+  {% trans trimmed theme_version=theme_version|e, PST_url="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html" %}
+    Built with the <a href="{{ PST_url }}">PyData Sphinx Theme</a> {{ theme_version }}.
+  {% endtrans %}
 </p>

tox.ini

@@ -15,7 +15,7 @@ env_list =
 # helping contributors run common tasks without needing to call all the steps
 # For example to run the tests: tox run -m tests
 labels =
-    tests = compile-assets, i18n-compile, py312-tests
+    tests = compile-assets, i18n-compile,  py312-tests
     a11y = compile-assets, i18n-compile, py312-docs, a11y-tests
     i18n = i18n-extract, i18n-compile
     live-server = compile-assets, i18n-compile, docs-live
@@ -156,7 +156,8 @@ allowlist_externals = bash
 commands =
     # explicitly pass this as a bash command to set PST_VERSION
     bash -c "PST_VERSION=$(pip show pydata-sphinx-theme | grep Version | awk -F': ' '{print $2}') && \
-    pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/sphinx.pot --project=pydata-sphinx-theme --copyright-holder='PyData developers' --version=$PST_VERSION"
+    pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/sphinx.pot --keywords='_ __ l_ lazy_gettext' \
+    --project=pydata-sphinx-theme --copyright-holder='PyData developers' --version=$PST_VERSION"
     pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx {posargs}
 
 # add a new locale for translations based on the catalog template

webpack.config.js

@@ -16,13 +16,15 @@ const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");
 const TerserPlugin = require("terser-webpack-plugin");
 const dedent = require("dedent");
 const { Compilation } = require("webpack");
+const { exec } = require("child_process");
 
 /*******************************************************************************
  * Paths for various assets (sources and destinations)
  */
 
 const scriptPath = resolve(__dirname, "src/pydata_sphinx_theme/assets/scripts");
 const staticPath = resolve(__dirname, "src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static");
+const localePath = resolve(__dirname, "src/pydata_sphinx_theme/locale");
 
 /*******************************************************************************
  * functions to load the assets in the html head
@@ -96,8 +98,8 @@ const htmlWebpackPlugin = new HtmlWebpackPlugin({
   templateContent: macroTemplate,
 });
 
-module.exports = {
-  mode: "production",
+// webpack main configuration
+var config = {
   devtool: "source-map",
   entry: {
     "pydata-sphinx-theme": resolve(scriptPath, "pydata-sphinx-theme.js"),
@@ -170,3 +172,31 @@ module.exports = {
     topLevelAwait: true,
   },
 };
+
+module.exports = (env, argv) => {
+  // Sphinx Theme Builder creates a completely isolated working directory
+  // when packaging the theme. That means that we cannot follow a workflow
+  // like this:
+  //    1. run command to compile the translations
+  //    2. run command to package the theme (`stb package`)
+  // We must instead compile the translations **as part of** the command
+  // that builds the theme:
+  //    1. command to package theme
+  //        a. compile translations
+  // The theme builder calls `npm run-script build` (`webpack --mode=production` per our
+  // package.json) so we compile the translations here.
+  if (argv.mode === 'production') {
+    exec(`pybabel compile -d ${localePath} -D sphinx`, (error, stdout, stderr) => {
+      if (error) {
+        console.error(`Error: ${error.message}`);
+        return;
+      }
+      if (stderr) {
+        console.error(`stderr: ${stderr}`);
+        return;
+      }
+      console.log(`stdout: ${stdout}`);
+    });
+  }
+  return config;
+};