Translation infrastructure for this theme

[choldgraf]

Currently we have several missing translation elements that only exist in English (see this issue for tracking that effort: #257). One challenge with this is that the standard translation infrastructure that Sphinx uses is a bit hard to learn, and not a common workflow.

In the Sphinx Book Theme, we have a little semi-automated translation workflow to try and make translating things easier. I think it could be helpful if we ported this to this theme as well. It involves editing translations in a JSON file rather than dealing with .po and .mo files directly, which I find much easier to wrap your head around.

Overview of the book theme workflow

Essentially it works like this:

• We store translations for each phrase in a dedicated JSON file. For example, the phrase "My phrase" exists in a My phrase.json file. These are the things that we manually update with new translations. https://github.com/executablebooks/sphinx-book-theme/tree/master/src/sphinx_book_theme/assets/translations/jsons
• At build time, we have a script that compiles these JSON files into the .po and .mo files that are used by Sphinx in its actual infrastructure. https://github.com/executablebooks/sphinx-book-theme/blob/master/src/sphinx_book_theme/_compile_translations.py
• We then define our own message catalog and add it to the Sphinx build's translations: https://github.com/executablebooks/sphinx-book-theme/blob/0b62420c5651f304bb9999990acb115cd9c02886/src/sphinx_book_theme/__init__.py#L58-L60

Here's the README for that translation workflow.

[12rambau]

I'm managing translation for 3-4 FAO projects in different formats. IMO, .po files are super easy to manage with an automated translator (crowdin, transifex etx...), and know how to deal with many common translation issues (plural, right-to-left, feminine-masculine (hello french words that change gender when plural) and others that I never faced).

I'm quite unsatisfied with how sphinx-intl and sphinx itself are dealing with generating these files. I'm currently working on a pre-commit implementation and I would be happy to include it once it's ready.

Note also that as we are supporting a very small number of words, we will be able to use any of the up mentioned software in their free-plan.

I also think that #399 would need a revival in this context. happy to work on it when I found the time (that's a bigger one than the usual css edge cases)

[choldgraf]

Sounds good - if you have a better system I am all for it! I have just found that "confusion over how to handle translations" often causes projects (like us 😅) to avoid doing the translation work over time. IMO, it needs to be super easy and straightforward for maintainers to manage or it is likely not going to get done :-/

[12rambau]

I'm closing this issue as #399 is now included in the framework and we added the transifex translation manager. Please feel free to reopen if you think something is missing.