Use mdbook-i18n-helpers to support translations

[mgeisler]

This PR expands the publishing step to also publish a (very partial) Danish translation of the book. The result of this can be seen here: https://mgeisler.github.io/rust-embedded-book/da/intro/index.html.

The infrastructure uses the GNU Gettext tools, as well as a mdbook plugin:

sudo apt install gettext
cargo install mdbook-i18n-helpers

The translation lives in po/da.po, which was created with

MDBOOK_OUTPUT='{"xgettext": {"pot-file": "messages.pot"}}' mdbook build -d po
msginit -l da -i po/messages.pot -o po/da.po

After creating the da.po file, the translation can be served locally with:

MDBOOK_BOOK__LANGUAGE=da mdbook serve

The publication flow on GitHub has been expanded to publish translations into subdirectories named after the two-letter ISO_639-1 language codes. The English source text stays the same.

Links to the new translations are added manually in the index.hbs theme file. I imported the one from mdbook and added a very simple language picker in the top right corner. If someone knows how to extend the existing file without copying it, then I would love to hear about it 😄

The whole setup tries to be very pragmatic: publishing a language is decoupled from accepting the PO file into the repository, and linking to a translation is decoupled from publishing it.

I replaced the GitHub pages publish step with one that uses a GitHub action instead of a branch — this is not essential, it just matches what I did for my own repository. Feel free to ignore this as you like. Similarly for how the new dependencies are installed and cached: this is just a cargo install mdbook-i18n-helpers behind the scenes.

Fixes #326.

[therealprof]

Thanks for the PR. This looks like a great step into the right direction as it is similar to a lot of other projects which have taken the gettext route.

I think we'll need to gauge the interest in the community to help with the translation though since simply having the mechanism to provide all translations from the same repo and maintaining it together is not providing a lot of benefit on it's own and actually increases the maintenance effort required.

Experience from past projects which have taken the exact same route (From English only version over full external translations to gettextized approach) like https://docs.gimp.org/ show that the setup requires a lot of initial work (partially done by this PR), often a restructuring of the existing text to better suit the paraphwise translation mechanism better and a lot of heavy lifting to get a signifcant chunk of translation going before becoming a community driven effort.

Also having the translations in this repo means that now the WG is required to judge the conformance of the offered translations to the community guidelines which might be close to impossible for some languages...

[mgeisler]

Hi @therealprof,

Thanks for the PR. This looks like a great step into the right direction as it is similar to a lot of other projects which have taken the gettext route.

I'm glad you know the system! The infrastructure here is actually the same as what I wrote ~10 years ago for the Mercurial project 😄 As you say, it's a well-known system for software (less so for books).

I think we'll need to gauge the interest in the community to help with the translation though since simply having the mechanism to provide all translations from the same repo and maintaining it together is not providing a lot of benefit on it's own and actually increases the maintenance effort required.

Experience from past projects which have taken the exact same route (From English only version over full external translations to gettextized approach) like https://docs.gimp.org/ show that the setup requires a lot of initial work (partially done by this PR), often a restructuring of the existing text to better suit the paraphwise translation mechanism better and a lot of heavy lifting to get a signifcant chunk of translation going before becoming a community driven effort.

I agree, having the infrastructure is only the first step. Actually, people often show up with translations even without having a system in place, as show by all the issues here: https://github.com/rust-lang/book/labels/Translations. For Comprehensive Rust, we had the first translation appear out of the blue about two weeks after we published the course — which prompted me to prioritize the plans for writing a i18n infrastructure.

One step (which I haven't yet done for the Rust course) is to guide people to an online platform for the translations. I'll probably set that up eventually since I hope it will lower the barrier to entry for people.

Also having the translations in this repo means that now the WG is required to judge the conformance of the offered translations to the community guidelines which might be close to impossible for some languages...

Yes, that's very true! For my Rust course, I have the advantage of being able to draw on a vast network of other Googlers, so I can find someone who speaks almost any language 🙂 For other projects, I would apply a simpler standard: let the first person who show up speaking language X be the maintainer of that language. They can then work with other contributors to determine a consistent way to translate the technical terms. Where possible, I've suggested to the translators that they should mimic the translations of the Rust book, but it's not something I'm able to actually check or enforce.

In any case, I hope people can give it a try. If someone (such as @DownyBehind from #350 and @Jzow from #326) wants to play with a Gettext-based translation, then they're free to open PRs against https://github.com/mgeisler/rust-embedded-book. That repository can be a temporary "translation playground" so that you don't have to deal with anything in this repository.