Gettextize documentation

[rffontenelle]

Translating in a PO file is easier than directly in docs/basics/LANG/index.md. po4a is able to extract from source Markdown documents to PO/POT files and to convert it back.

I managed to copy the Spanish translation from the current Spanish doc into the PO file and looks like it was generated without issue (I advise a review).

Some example of commands (from po-docs docs/po dir):

• po4a --no-translations po4a.cfg - Extract from source docs to POT file and PO files
• po4a --no-update po4a.cfg - Builds the translated docs in docs/basics/LANG/index.md
• po4a po4a.cfg - Extract to POT/PO and build translated docs

Things to improve in this suggestion:

• Set up a meson.build to update and build files on meson compile time
• Document the translation process somewhere?

Anyway, this works, but needs more integration with the project build process. Suggestions or adding commits to this PR are welcome.

EDIT in 19/02/2024: updated the docs PO file's path.

[tchx84]

Hey @rffontenelle ! This looks really good, thanks! I will check it out today.

[tchx84]

I can handle the flatpak and meson stuff, but I have suggestions and questions:

1. Rebase to the main branch.
2. Move po-docs to docs/po, it will make it easier to find and simpler for meson stuff.
3. Remove docs/basics/es/index.md, since this file will be generated anyway.
4. Rename gamegeeky-docs.pot to gameeky.pot
5. Is it possible to make po4a preserve lines as they are in the source md file? I noticed the translations are broken into multiple lines.

[rffontenelle]

@tchx84 May I suggest moving docs/basics/en/index.md down to docs/basics/index.md, leaving docs/basics/$lang/ to other languages?

Also, should I remove translated html too?

[tchx84]

@tchx84 May I suggest moving docs/basics/en/index.md down to docs/basics/index.md, leaving docs/basics/$lang/ to other languages?

It would complicate one thing on meson side (when installing those files, one file, en, would be a special case) but if you feel strongly about it, sure!

Also, should I remove translated html too?

[rffontenelle]

Fixed the requested changes, but I'm still trying to figure out:

5. Is it possible to make po4a preserve lines as they are in the source md file? I noticed the translations are broken into multiple lines.

So far I found a -o neverwrap option that 1) adds a no-wrap Gettext flag for all strings, 2) add a new-line character \n to all strings, 3) but seems to generate the translated docs with unwrapped lines. I'm in contact with po4a to find another solution because having to add \n on every string might be annoying for the translators.

[tchx84]

@rffontenelle Note that I pushed the "basic" integration bits to your branch, e.g. flatpak packaging and meson build steps... regarding instructions for managing this maybe you can add some notes here

[tchx84]

This won't make it to the next release, but I wanted to share a concern with po4a dependencies.

I am currently trying to make Gameeky easier to run on MacOS and Windows and, since It wasn't trivial to make package po4a for Flatpak, I worry that it could make things a bit more complicated that needs to be for other platforms. I wonder if the alternatives are good enough, e.g., https://github.com/mondeja/mdpo.

[rffontenelle]

No problem, I'll try mdpo and get back to you.

Sorry for taking long for landing the requested changes. One thing that I was wondering is whether we can make things easier in the documentation. For UI, it is to run ninja gameeky-update-po. Is it possible to add a ninja target for Docs translation as well? Alternatively, may I add a simple shell script to do the same as "gameeky-update-po", but for docs ?

[tchx84]

No problem, I'll try mdpo and get back to you.
Sorry for taking long for landing the requested changes

No worries, we do what we can, and eventually we will land this.

One thing that I was wondering is whether we can make things easier in the documentation. For UI, it is to run ninja gameeky-update-po. Is it possible to add a ninja target for Docs translation as well? Alternatively, may I add a simple shell script to do the same as "gameeky-update-po", but for docs ?

Yes, I can figure that out after I am done with this new release.

[rffontenelle]

Is there an better way to get the project's version than grep -P '^\s+version:' meson.build | cut -d\' -f2 (which would return 0.6.0 now)?

[tchx84]

Is there an better way to get the project's version than grep -P '^\s+version:' meson.build | cut -d\' -f2 (which would return 0.6.0 now)?

yes, parse the data/dev.blah.blah.metainfo.xml file

[rffontenelle]

Let's go for another shot, now using mdpo. TL;DR: I liked it.

The PO generation command (md2po) ignores code blocks by default (which are just code, no translation is done actually), it treats warning blocks correctly (no no-wrap flag, no \n in the end). Downside is that it doesn't show the actual line of the source string in the source file, it just mention blocks -- we can live with it.

The Markdown file generation from PO (po2md) has option to generate without line-wrap (exactly what you asked, as are the Markdowns today).

Both have --quiet option, but we could remove it for more verbosity in GitHub Actions, for instance.

docs/po/update-translations.sh is an idea for do all in one command: generate POT file, update PO files and generate translated Markdown files. I guess it is not currently well suited for being used with Meson (e.g. I set the LANGs enabled again), but let me know how it is going and I'll adjust it.

[rffontenelle]

I'd like to note that if/when you choose to use Weblate as a translation platform, you'll probably not want to update the PO files. Instead, you'll want to update only the POT file and leave for Weblate to update PO files via the "Update PO files to match POT (msgmerge)" add-on. Updating PO files locally could cause annoying merge conflicts.

[tchx84]

@rffontenelle awesome, I will check this out ASAP.. Many thanks

[tchx84]

@rffontenelle let me know when you're done with this, because I will need to do some "surgery" in this branch to get it ready :)

[rffontenelle]

@tchx84 The only detail that I think we should define is the target languages. I implemented POT regeneration and update of all PO, but this causes to hardcode enabled language codes in the script. However they are also set in docs/meson.build to generate html file.

One idea I had now is to implement an argument specifically for regenerating POT and otherwise reading language codes from stdin so that you can run meson.build passing only the enabled languages.

Feedback is appreciated

[tchx84]

@tchx84 The only detail that I think we should define is the target languages. I implemented POT regeneration and update of all PO, but this causes to hardcode enabled language codes in the script. However they are also set in docs/meson.build to generate html file.

I think is this OK, the costs of ignoring regenerated files is less than making the building process more complex by having to specify parameters somewhere else. Don't worry too much about these details, I will figure out how to integrate this into meson.

All I need to know is if your're done with the structure / translation pieces, so I can start refactoring the code on this branch to be able to merge it :)

One idea I had now is to implement an argument specifically for regenerating POT and otherwise reading language codes from stdin so that you can run meson.build passing only the enabled languages.

Feedback is appreciated

[rffontenelle]

Yeah, I'm good. Feel free to make your changes.