Translation enablement

[paususe]

Description

This PR converts AsciiDoc to gettext and back (so that we can use WebLate, PoEdit or alike), and generates the translated docs with Antora.

Some details:

• One site is generated per language to avoid rendering the Lunr search useless by mixing languages in the results
• In order to make it easy/possible to switch languages, HTML pages are generated under "./build/$langcode" (e. g. "./build/en", "./build/es"). This means the URL is exactly the same for a page in all languages, minus the langcode (e. g. https://www.uyuni-project.org/uyuni-docs/*en*/uyuni/installation/uyuni-install-requirements.html vs https://www.uyuni-project.org/uyuni-docs/*es*/uyuni/installation/uyuni-install-requirements.html)
• PDFs are generated under ./build/pdf/$langcode (e. g. "./build/pdf/en" and "./build/pdf/es")
• It is possible (and expected) that several languages are built in the same build directory, one after the other, and the the result can be combined. This is in fact a must for the language picker in the HTML version to work
• The Makefile has been split in three
  • Makefile: lighter, only generic functions
  • Makefile.en: English books. Keeps the make antora-suma and make antora-uyuni targets.
  • Makefile.es: Spanish books. Introduces new make antora-suma-es and make antora-uyuni-es targets.
• A new suma-site.yml / uyuni-site.yml is generated in the temporary directory "./translations/$langcode" from the base (English) suma-site.yml / uyuni-site.yml. The site.url variable is NOT set to the language, otherwise the only way to find the base URL for all languages is to backtrack (i. e. use "en/../es/page.html").
• POT files are generated by make_pot.sh (can be run with make pot) in "./l10n/pot". This also updates the PO files for all languages. Finally, it also rsync's the images/screenshot.
• A "translated image" is an image/screenshot in the target language, which should be stored in "./l10n/po". When a "translated image" is available, rsync will not overwrite it
• PO files are converted to AsciiDoc by "use_po.sh" (can be run with make translations) during build and never checked into git. The temporary "./translations/$langcode" directory is created and artifacts (AsciiDoc, Antora, etc files) are generated there.
• Two new build-time dependencies are required to generate translations:
  • rsync
  • po4a (>0.54, which means the default version in openSUSE Leap 15.1 and 15.2 is NOT enough, you'll need to resort to some OBS repo or use Tumbleweed)
• To enable/disable a guide, just comment it out in the antora-suma-es/antora-uyuni-es and pdf-all-suma-es/pdf-all-uyuni-es

Here is a detailed explanation of how this works (it's a bit outdated: the part about changing output paths is already implemented in this PR)
https://gitlab.com/antora/antora/-/merge_requests/548#note_379442440

This is now ready for review and best reviewed by first looking a the "small" commit (the one that makes the changes to Makefile, suma-site.yml, uyuni-site.yml, antora.yml, introduced use_po.sh and make_pot.sh), and then as a curiosity looking at the huge commit adding a ton of POT files, PO files and images to be translated.

Known issues:

• make_pot.sh fails when run from the Makefile target ("make pot"). Run it manually.
• make_pot.sh is not automatically run on commit or alike, so translations must be updated manually.
• Both make_pot.sh and use_po.sh will regenerate all translations every time. This is not a problem so far because there is only one translation (Spanish) but it's a waste of time when there are several languages. This will be fixed in the future.
• There is a ton of duplication between Makefile.en and Makefiles.es. Even inside those files, and in Makefile, there is a ton of duplication. I was on the verge of rewriting everything in some generator (e. g. CMake) but refrained.

For testing, I translated 1.5 pages and the index of the Installation Guide to Spanish. This is how it looks:

Target branches

To what product version this document applies?

• Manager-3.2
• Manager-4.0
• Manager-4.1
• Uyuni

Links

Fixes https://github.com/SUSE/spacewalk/issues/11672

[paususe]

cc @mcalmer @jcayouette

[jcayouette]

cool looks good. How good is the translation? Are they high quality? Context ok?

[paususe]

cool looks good. How good is the translation? Are they high quality? Context ok?

What do you mean "high quality" and "context OK"?

Translations will be as good as the translators will do them. Spanish one will be very good, you can be sure :-)

About the context, if you are talking about gettext context (msgctxt) then the answer is the pot files generated by po4a have no context. It should not be difficult to add something to them (e. g. the guide, page and section name) by modifying make_pot.sh but that's low priority.

[jcayouette]

@paususe If you are happy with these changes then lets go ahead and merge. I see a few conflicts in the makefile and suma-site.yml? Will we stick with this considering the discussion over at antora?

[paususe]

@paususe If you are happy with these changes then lets go ahead and merge. I see a few conflicts in the makefile and suma-site.yml? Will we stick with this considering the discussion over at antora?

I think for now this is what we will need to use. In the future, if Antora implements translation enablement, I'll be happy to move to it.

I still need to do some changes to enable the language picker. I should be able to work on that mornings next week, before the kickoff. Rebasing my current changes to master requires manual conflict resolution, I'd rather squash all my changes and then conflict-resolve. Give me a few extra days.

[paususe]

@jcayouette This is now ready for review and merge