Add translation support

[dalance]

This PR adds translation support based on https://github.com/google/mdbook-i18n-helpers.

Translation support by mdbook-i18n-helpers is already used at rust-by-example, and translation build support on rust-lang/rust was merged at rust-lang/rust#124731, so I think this framework became ready for introducing into this book.

Refs: #464

[mgeisler]

"RBE" is probably referring to "Rust by Example"? It should be updated here 😄

[dalance]

Thanks! I've fixed it.

[mgeisler]

If adding a copy of the theme is seen as too cumbersome, an alternative approach would be to use a bit of JavaScript to inject the language picker. That might be nicer for long-term maintenance.

[dalance]

The alternative approach seems to be better.
Is there an actual example?

[mgeisler]

No, I haven't used this approach myself since I wanted to modify the theme file anyway and so it was easier to hard-code the language picker there.

[mgeisler]

Thanks @dalance for creating this PR! I would be very happy to see the translation system used here too!

[dalance]

@chriskrycho
How do you think about this PR? This may not be perfect solution, but it works fine at many projects including Rust By Example.
If translation databases for each language are stored in this repository, migrating another solution is probably easy in future.
Is there any concern which blocks this PR?

[chriskrycho]

@dalance in all honesty I have not yet had a chance to dig into it—but I will do so this morning, and @carols10cents and I are chatting later today, so we’ll talk about the maintainability tradeoffs as well. It’s a significant change for how we have managed translations for this in the past (read: we haven’t; we have just linked to the community-maintained translations) and maintenance on the book repo is sporadic to say the least, so we’ll want to consider it carefully. That’s by no means a “no”, just flagging up what the status is!

[dalance]

Thank you for your interesting!
I agree concern about maintainability. For reference, in Rust By Example, translators of each language community are responsible for the translation and the original author of English version doesn't involve the contents of translations.

[carols10cents]

Thank you for your interesting!
I agree concern about maintainability. For reference, in Rust By Example, translators of each language community are responsible for the translation and the original author of English version doesn't involve the contents of translations.

Do the translators have push permission on the main RBE repository or do the translations live in other repositories? I'm not sure I want to give lots of people permissions to this repo.

[dalance]

Translators don't have push permission. Instead of it, the maintainer of RBE approves a PR updating translation database in spite of the content.

[carols10cents]

Translators don't have push permission. Instead of it, the maintainer of RBE approves a PR updating translation database in spite of the content.

So each change to each translation means there's a PR that I or @chriskrycho has to approve? That's a lot of work that I don't have time to keep up with. I would rather it worked like it does now, where each translation sends one PR adding a link to the repo where the translation is managed independently (and I even have trouble keeping up with those PRs!)

[dalance]

Actually, each translators create an organization of the language (e.g. rust-lang-ja), and coordinate the translations and review them. After it, a PR is sent to RBE repository.
If you don't have enough time to approve them, I think a rule like "A PR of each language should be sent up to once a year" can be determined.

[carols10cents]

Could you perhaps add a new commit to this PR (that we can then remove) showing how to point to a translation?

[dalance]

I added a commit to add Japanese translation resource.
The translation resource is po/ja.po. As a sample, I translated the title and the first statement of the front page.

By the way, I have another idea to reduce cost to approve translation PR by using auto-merging mechanism of GitHub.

1. Regist language entry and owner
   At the first, translators create an organization for translation, add a language entry like below, and send a PR to this repository.
   This PR requires review and approvement by the maintainer.

[{
    "lang": "ja",
    "file": "po/ja.po",
    "owner": "rust-lang-ja"
}]

2. Add/Modify language resource
   After it, the organization sends a PR to add or modify the language resource po/ja.po.
   By GitHub Actions, the PR is checked whether it contains language resource only and is sent from the language owner.
   If the chech is passed, GitHub Actions merge the PR automatically.

By this approach, the maintainer pay approving cost only once for each language, and the language owners can modify the translation frequently without approving cost.

[dalance]

I'm thinking another solution which introduces translation sub-repository to rust-lang/rust.
If you are interesting in it, please refer https://internals.rust-lang.org/t/pre-rfc-translation-sub-repository-for-rust-docs/21666 .

[mgeisler]

I would rather it worked like it does now, where each translation sends one PR adding a link to the repo where the translation is managed independently (and I even have trouble keeping up with those PRs!)

Hi 👋 I wrote the i18n infrastructure being proposed here.

The question of being centralized or not is actually orthogonal to the use of mdbook-i18n-helpers — even if translators maintain their own independent repositories like today, they can still benefit from the tooling. The benefit: it makes it practical for them to update the English source text since the translation is kept next to the source text.

For Comprehensive Rust, we've given write access to about 50 translators by now. Yes, it's a bit scary, but I have only seen good things come or this until now 🙂

A compromise, as suggested by @dalance, would be to have someone trusted (perhaps a bot) approve PRs from well-known translation repositories. The person or bot only needs to check that the PR only touches a single xx.po file.

I have not yet written such a bot, but it would be a fun project.

[dalance]

I created a PR to add translation submodule to rust-lang/rust.
If this PR is accepted, translation can be added without merging cost of the original maintainers.

rust-lang/rust#133562