Add support for translations

[avivace]

Closes #25

Based on the i18n support implemented in https://github.com/google/comprehensive-rust

• Credit https://github.com/google/comprehensive-rust for the translation system add headers+license in i18n related code
• Add TRANSLATING file explaining how to contribute to translations and add new ones
• Add a sample translation to start with (e.g. one page in Italian from Italian translation #32
• Mention the translation guidelines in the README and in the book
• Adapt the current build pipeline to go through the gettext preprocessor
• Add a submenu linking to available translated versions of the book
• Update CI to build translated versions of the book
• If all of this is done, rebase it in two commits: one for adding the i18n code and the other for the italian po

[ISSOtm]

Thank you very much for your help setting this up! I only have suggestions about some details; the overall process is very good!

[ISSOtm]

That's step 1 done :)

[mgeisler]

Hi folks! Thanks for trying out the i18-helpers, I hope they're useful?

I just wanted to let you know that I've released them as a stand-alone crate now: https://crates.io/crates/mdbook-i18n-helpers. That should let you clean up the code here a bit 🙂

I noticed you use cargo run directly. With a downloaded crate, you should be able to replace that with cargo install --root tmp mdbook-i18n-helpers and then refer to tmp/bin/mdbook-xgettext and tmp/bin/mdbook-gettext in your book.toml.

Please open issues in the repository for any problems you run into. Thanks!

[avivace]

Hi folks! Thanks for trying out the i18-helpers, I hope they're useful?

I just wanted to let you know that I've released them as a stand-alone crate now: crates.io/crates/mdbook-i18n-helpers. That should let you clean up the code here a bit slightly_smiling_face

I noticed you use cargo run directly. With a downloaded crate, you should be able to replace that with cargo install --root tmp mdbook-i18n-helpers and then refer to tmp/bin/mdbook-xgettext and tmp/bin/mdbook-gettext in your book.toml.

Please open issues in the repository for any problems you run into. Thanks!

Wow, thanks a lot @mgeisler ! I'll open another issue with the points you mentioned so we can take a look at this later. Thanks again for the amazing translation system, it's working very nice for us!

[mgeisler]

Thanks again for the amazing translation system, it's working very nice for us!

Thanks for the feedback, I'm very happy it works for you!

[mgeisler]

Hey @avivace, I wanted to let you know about google/mdbook-i18n-helpers#46.

The current main branch of mdbook-i18n-helpers has a new text extraction system: it will turn # Some heading in the Markdown file into just "Some heading" in the PO file. Paragraphs are un-wrapped when extracted. Lists are now extracted on a per-item basis and tables are extracted on a cell-by-cell basis. This removes most of the Markdown syntax and makes the job easier for translators. It also allows you to freely reformat the Markdown files without invalidating the existing translations.

For this to work smoothly with existing translations, I've written a conversion tool: google/mdbook-i18n-helpers#46. When that is merged, I will make a new release. I hope you will be able to migrate to it as well.

Eventually, I want to release a GitHub action for all this: google/mdbook-i18n-helpers#48. That should make your life easier since you can export the complexity back to the mdbook-i18n-helpers repository 😄

[mgeisler]

I added a link to this projects in the mdbook-i18n-helpers README: google/mdbook-i18n-helpers#49. I hope you don't mind?

[avivace]

I added a link to this projects in the mdbook-i18n-helpers README: google/mdbook-i18n-helpers#49. I hope you don't mind?

Sure, go ahead and thanks for the mention @mgeisler !

The current main branch of mdbook-i18n-helpers has a new text extraction system: it will turn # Some heading in the Markdown file into just "Some heading" in the PO file. Paragraphs are un-wrapped when extracted. Lists are now extracted on a per-item basis and tables are extracted on a cell-by-cell basis. This removes most of the Markdown syntax and makes the job easier for translators. It also allows you to freely reformat the Markdown files without invalidating the existing translations.

For this to work smoothly with existing translations, I've written a conversion tool: google/mdbook-i18n-helpers#46. When that is merged, I will make a new release. I hope you will be able to migrate to it as well.

This sounds very interesting and cleaning up the strings from formatting is definitely appreciated. Feel free to ping me when the migration tool is ready!

Eventually, I want to release a GitHub action for all this: google/mdbook-i18n-helpers#48. That should make your life easier since you can export the complexity back to the mdbook-i18n-helpers repository 😄

This is also interesting, maybe it can help automate our current workflow, which requires uploading the base po to crowdin..

[mgeisler]

This sounds very interesting and cleaning up the strings from formatting is definitely appreciated. Feel free to ping me when the migration tool is ready!

The converter tool is part of the new 0.2 release which I made last week.

I've created PRs for Comprehensive Rust today to update the translations. As an example, the Brazilian Portuguese page on scalar types is using the new system — the table you see there is translated cell-by-cell. If we change one of them in the English original, the others will remain translated.