Use mdpo to translate documentation

[rffontenelle]

Let's us have another shot at documentation translation via Gettext

The first commit adds three new Python scripts in docs/po:

• generate_po.py: generate gameekey.pot; run without argument
• update_po.py: update PO file(s) from current POT file; takes one language code or 'all' for all PO files found
• build_md.py: generate the docs/basics/$LANG/index.md; takes one language code or 'all' for all PO files found

Note: Installing mdpo is required.

The second commit contributed removes docs/basics/es/index.md, so the changes after running build_md.py are visible.

The third commit updates CONTRIBUTING.md with the use of these scripts for updating documentation translation.

For reference, other discussions on this matter: #69 and #109

[tchx84]

@rffontenelle thanks, I review this carefully during the week.

Also, let me brain-dump something regarding the packaging and distribution issues... this is what I think we should do for now to get done with this in way we achieve our most important goals: gettextize this WHILE not making it harder for people to build this project.

1. Let's give up (for now) on the idea that everything should be generated at build time e.g., not requiring pandoc nor mdpo at build time and therefore generating nothing at build time.
2. Instead, let's just move these steps out of the build pipeline and make them manual (for now).
3. So, to achieve that we could just include the *.HTML file as a source.

The pros are:

• We don't need to worry about these packages not being available for arch X or Y. As people can install and run these in whatever way it's available to them since it would be manual.
• It simplifies the building process because it's just copying files at build time.

The cons are:

• Manual steps (of course :rofl: ) but, we can mitigate this if we tweak the process.
• A few Kilobytes extra in the repo, and yeah my inner perfectionist gets mad but, I honestly don't care if this makes it easier for people to use the tool which is a greater goal.

The process (e.g., say to update the docs) could be like this:

1. Someone updates something in docs/basics/en/index.md, a.k.a the source.
2. Same someone runs ninja gameeky-docs-update to update the template and translation files.
3. Same someone updates one or more the translations.
4. Someone runs ninja gameeky-docs-generate to first (re)generate the *.md file and then the *.HTML file.
5. Someone commits the updated *.HTML files and sends a PR.

So it's basically 2 steps, plus regular change/git stuff.

Notes:

• The process could even stop at step 2 and make a PR, if we ever move translation to weblate or something. Then, the regeneration of *.HTML files can be done by someone or something else.
• Eventually, we would automate back the steps 4 and 5 in a dist pipeline.

We would document this process in a docs/README.md.

The alternative to this would be to move to something completely different.

[rffontenelle]

We can set up a GitHub workflow that runs triggered by push event with a path filter of doc/po/*.po, that converts po -> markdown -> html. Finally, auto commit or open a pull requests.

The PO update process could also be an workflow that is run manually from rhe workflows page (Actions > select workflow > run manually). It could be used to run before a new release.

[tchx84]

We can set up a GitHub workflow that runs triggered by push event with a path filter of doc/po/*.po, that converts po -> markdown -> html. Finally, auto commit or open a pull requests.

The PO update process could also be an workflow that is run manually from rhe workflows page (Actions > select workflow > run manually). It could be used to run before a new release.

Correct, that's what I meant by dist pipeline, it can generate a tar with the generated HTML (so we don't need to include it as source anymore). Then people can build it from there, without the need of these tools.

EDIT: See meson's add_dist_script, so the HTML will be generated during meson dist and these HTML files will be included in final tarball (and not source)

[tchx84]

@rffontenelle finally found the time to work on this.. this is the "manual" version of what we discussed earlier (the version where we includes the final HTML, so that we don't need to generate it at build time and therefore simplify users installations)... This is still WIP though (still need to polish things)

[tchx84]

@rffontenelle I think this is ready for merging now... with a few caveats:

• I removed all meson / pipeline / automation related stuff for now. I will need more time to that properly, so I will put that back later.
• There's no documentation. Maybe you can help with that in a separate PR? I say we add proper README.md file under the ./docs directory with a more detailed version of the following:

$ python3 docs/tools/update_pot.py docs/basics/src/en/index.md docs/basics/po/gameeky.pot
$ python3 docs/tools/update_po.py docs/basics/po --language es
$ python3 docs/tools/update_md.py docs/basics/src/ docs/basics/po/ --language es
$ python3 docs/tools/update_html.py docs/basics/src/ docs/basics/data/headers.xml docs/basics/po docs/basics/html/ --language es