Figure out a consistent story for translating theme content

[pradyunsg]

This would basically be something that helps theme authors provide + maintain translations for their theme.

It will be a combination of documentation and some build-time logic for managing + validating the translations, as part of generating the distributions.

[choldgraf]

Just a note that we are currently being bitten by this in the PyData Sphinx Theme.

We've added a folder with locale information, and have just the .po files checked into git history. However because of the way pybabel works it is not trivial to put the compiled .mo files into a different directory than their sister .po file. This means that we keep the .mo files in the same folder (as pybabel does by default).

However, this means that we can't use stb serve because the .mo files are compiled at build time, and don't live in compiled_assets (ref: #18) and so it detects them changing each time. I also don't think stb serve has the ability to ignore extra folders the users provides (which would be useful).

[pradyunsg]

Do you have links for me to look at, to understand how pydata-sphinx-theme manages translations?

[choldgraf]

Yep - links below:

• Here's our locales folder: https://github.com/pydata/pydata-sphinx-theme/tree/main/src/pydata_sphinx_theme/locale

• Here's the lines in our webpack config where we compile translations at build time

  https://github.com/pydata/pydata-sphinx-theme/blob/157c9ab2c93e755141e48d13b5f193c6169d9dd8/webpack.config.js#L21-L26

• Here's all our docs on translations: https://pydata-sphinx-theme.readthedocs.io/en/latest/community/topics/i18n.html

[pradyunsg]

If stb compile also ran the translation logic, instead of webpack, would that work for y’all?

[choldgraf]

Yeah I'd much rather rely on a stb functionality for this rather than hand-rolling webpack commands. Especially if it followed recommend practices for pybabel do I didn't have to figure out if I'm doing it right out of the box haha. It'd also be great if we could have the .po files in assets/locale and the .mo files in static/locale but i couldn't figure out a non hacky way to do this.

I'm not an expert but AFAICT we are just doing standard pybabel commands largely based on the docs default recommendations

[pradyunsg]

Neato! Depending on how my recovery from a medical procedure I had today goes... I might take a stab at this today. Otherwise, please poke me on some other channel about this coz as it'll definitely leave the front of my mind in a day or two. 🙈

[trallard]

Finally, I'm circling back here! I recently spent much time refactoring our translation workflows and then patching the packaging in PST, which is good because it helped me think about how to include this in stb.

💡 Ideas and notes:

1. We have had resources to call the translation compilation from within Webpack due to how stb package currently works and how generated artefacts are found and added to the distribution files (everything is expected to be in src/theme/<my-awesome-theme>/static/ and adding any extras to the pyproject.toml but still within the src/theme/<my-awesome-theme>/static/ directory)
2. The above has proved tricky for development and maintenance since:

• It creates an infinite loop for us when trying to work on the theme and docs as we end up compiling JS artefacts, processing HTML templates, compiling po files (even using the re-ignore flag 🤔, though it should not, I believe).
• It also obscures some of the translation maintenance tasks; since the po files are compiled through webpack maintainers/contributors often forget to update the catalogue pot files, leading to outdated/incorrect translation files (it would be great to include some check here too to identify when these files are out of date and send a warning or the likes)
• It would be better for maintainers to be able to extract, update, and compile the translation files from within stb and specify the location of the po/pot files as well as the target location of the compiled mo files independently from the JS/scss/css assets (this would be quite helpful for development and we can provide a good default of static/locale like Chris suggests before, while allowing users also to customise if needed, and integrate this into the stb package to ensure localisation/translation files are correctly updated and included for distribution)

3. There should be an individual stb command to process the translation files (and as mentioned above, later called by stb package to streamline the packaging/distribution workflow), but that is not necessarily tied to stb compile directly or as a hack like we currently do in PST due to the lack of a better alternative.

I can work on a prototype for this now that I better understand the involved pieces and the requirements from a maintenance POV WDYT @pradyunsg?
If so, I would consider adding a stb translate/internationalize command and take it from there.