See also: Translating the compiler
Organized translation efforts for Rust are now starting up. The website is in the process of being translated (Turkish and Simplified Chinese are ready).
This thread is in a similar vein as Translating the compiler, as an attempt to figure out how best to structure translation efforts for the stdlib docs. The goal here is to settle on an implementable plan for producing and maintaining translated versions of the stdlib docs at https://doc.rust-lang.org/std/.
My plan here is similar to what I hope to do for the error index. These docs are all blocks of text, there’s no interpolation involved. With that in mind, we actually should be picking a simpler localization format. For example, Fluent is great but it has a syntax to it, and that syntax will conflict with Rust code (for example, Fluent will pick up anything between curly braces).
What’s important here is that the format – whatever we pick – is supported by Pontoon and won’t have any syntax that conflicts with Rust code. These files will never be manually written so it’s not that big a deal what the format precisely is. We may end up diffing things, though.
I’m leaning towards picking the JSON format used by WebExtensions, since the only syntax it supports is
$foo$, which is unlikely to crop up. We can also create our own format and make it work with Pontoon.
I currently think we should design translation support as follows:
- Teach Rustdoc to dump every rendered doc block from a given crate into a json file, potentially split up by module. We’d have some way of converting a given path into a valid json identifier.
- Teach rustdoc to consume a folder full of such files and replace all doc comments based on this file
- Create a separate repo for translations. Periodically update the en-US folder in that from the JSON dumped from a rustdoc run on master. It needs to be a separate repo since Pontoon will be committing directly to it.
- Hook this repo up to Rust’s Pontoon
- Perhaps make this repo a periodically-bumped submodule in rustc so that stable/beta docs can still be built.
- Every official doc build, build the localized docs for each supported language by pulling in this repo. It may be worth making this a nightly-only task triggered after publication of the main nightlies
- Hook this up into whatever distribution system we use for compiler language packs so that
rustup component install rust-docscan work with this.
- Do we have the bandwidth to implement this?
- The relationship between the translated docs repo and rustc is somewhat cyclic, submodules may not be the right answer here.
- How exactly should the deploy process work? (cc @pietroalbini)
There are also questions about how best to coordinate this work (there are some challenges the website doesn’t have), however those are common for all