Translations for Rust

tools and infrastructure
1

Hey all!

Rust has been growing and growing over the past few years. As we continue to welcome new Rustaceans into the community, we want to continue to extend a friendly welcome. Part of that friendliness is not expecting that everyone speaks English. We've been hesitant to move forward with internationalization/localization efforts for a variety of reasons, but we shouldn't be putting them off much longer.

This is going to be a huge effort, and we want to do it right. I wanted to work up a proposal for how we can get there, but it's really important that we get input from those of you who are interested in working on translations. Ultimately, I'm only an expert in English; it wouldn't be fair for me to declare how you all do your work.

As such, I'd like to propose that we do this in phases:

  1. www.rust-lang.org
  2. The Book
  3. API Docs
  4. The compiler

These are roughly listed in order of difficulty and size. Nice when things line up like that. Let's go with each in order:

The Website

This should be the easiest, so I'd like to tackle it first. It should also be the easiest, with only a little bit of work being neccesary. What I'd like to propose is that we take the same approach that Ruby does for www.ruby-lang.org. It is also hosted on GitHub Pages, and seems to work pretty well. Here's the basics:

The homepage detects your language and redirects you to an appropriate sub-URL: www.ruby-lang.org/index.html at master · ruby/www.ruby-lang.org · GitHub

For example, I get redirected to Ruby Programming Language Note that if you don't have JavaScript enabled, you get sent to the English version, so this should be the same as today for that crowd.

Next, for various layouts, all of the information is represented through keys. For example, the Ruby logo says "A programmer's best friend" underneath it. But in the source, it looks like this: www.ruby-lang.org/_layouts/default.html at master · ruby/www.ruby-lang.org · GitHub

These keys are then configured in a YAML flie: www.ruby-lang.org/_config.yml at master · ruby/www.ruby-lang.org · GitHub

So, step one would be to re-do the English stuff to work with this. From there, we can open up PRs to add more languages.

Thoughts?

The Book

My work on the second edition of the book is still ongoing, and so it's not really ready to be translated yet. However, that's good, because I'm using mdBook for it, and there's still ongoing discussion about how to properly do this:

https://github.com/azerupi/mdBook/issues/5

We also had another thread about it:

I think that these threads are probably the most productive way to discuss how things should move forward there.

API Docs

This is difficult, first because I haven't even finished working on a rough draft of all of these yet, and second because we currently have no way to switch these out based on language. Lots of thought, discussion, and tooling work needs to happen before we can even consider this.

The Compiler

Finally, the compiler is even more complex. There's no real infrastructure here, and we're even farther away from being good enough at English errors yet to consider porting them. We had an RFC for this i10n by GuillaumeGomez · Pull Request #1292 · rust-lang/rfcs · GitHub

So! Thoughts?

4 Likes
2

Count me in as a translator/reviewer for Spanish :)!

1 Like
3

I think there is one thing missing before we can really start to add official translations: a good workflow for tracking changes in the original version. Having up to date translations would be very very hard without knowing what parts have changed in the English version since the last update.

For the website:

In the discussion for multi-lang support for mdBook a couple of people have pointed out that translations will always be lagging behind a little. It’s a fair point and I don’t know how relevant this would be for the website, but with the method you propose, changes like @brson did recently wouldn’t be as simple because you would need to update all translations before you can deploy.

4

@Azerupi

I’d suggest we keep a list of point-people for each translation, who we can expect to make quick edits.

Simple changes that don’t require translation can be done for all languages by the original PR author. For the rest I think we can do it on a best-effort basis, and translations may lag.

For example, I expect the contribution pages are the hardest to translate now, so translations may initially just say something like “This page has not been translated. Please see the english language version.”.

As content lands that needs translation I’d suggest we ping the translation team with a window of a few days to submit a counter-PR with translations. Those that don’t make it in time can submit translations later, and if not it’ll just have to bitrot.

The big exceptions to the best-effort policy I think are the front page and the downloads page. I’ll be responsible for updating all the downloads pages each release, and making sure any changes to the front page get translated.

5

Since the home page and download pages have such custom layout I wonder if they should be turned into layouts themselves and all the text inserted as keys, so we don’t have to keep a bunch of markup in sync.

6

Seems reasonable to me, I just wanted to point out that if we are working with “keys” we might end up with translations containing both paragraphs in the original language and in English on the same page (or worse empty strings if the implementation does not fallback to English). Which is less than desirable :wink:

It will be important to wait for all translations of a certain key before deploying to avoid that kind of problems.

7

Hello there!

I am really interested in Rust and I can contribute with the translations for Brazilian Portuguese.

I already worked in several efforts like this (InfoQ, Why’s poignant guide to Ruby, etc…).

Cheers.

8

I’d like to participate to the French translation. But there is a common problem with translations of documentations : keep them updated. I usually read English documentation even if a French one is available, since translated docs are usually outdated.

IMO to make the system viable :

  • When a change occurs on the original page, the translators should be warned.
  • The visitor of a outdated page should be warned too and provided a link to the original page
  • There should be a way to easily find all the changes that occurred to the original page since it was translated.
4 Likes
9

For translating content of web sites, Pontoon is the popular choice for Mozilla web properties these days. You can learn more about how it works at MDN.

2 Likes
10

Please count me in if u want any helps in translating into Chinese.

11

Hi guys, I’d like to be part of the Brazilian Portuguese (native) and Spanish translation too.

I think, as @steveklabnik said, we should start with the simplest one that is the Rust language site.

As that uses jekyll, there is few simple ways to do that (I’m not aware the way ruby lang is doing it). I’m, right now, doing it in my own blog which I plan to write in portuguese, spanish and english.

I’m following the simple approach from this post, and was also discussed in Jekyll forums.

I think the website will be easier to translate and keep it updated because it is just few pages.

For the book translations I agree that will have same delays between the original update and the translations but that is acceptable, and happens in other languages too.

About translating the API Docs and the compiler, I see it as maximum one “nice to have”, because even other already popular languages like Ruby and Python they don’t have API Docs translated, because generally programmers have at least a basic level of english to read the api docs.

12

Hi all,

I’m super late to the party, but I’m very interested in doing translation to Indonesia. How can I start to help? We are starting with the website right?

13

@lunchboxav The website translation PR is stalled, but there aren’t any blockers I think. Somebody just needs to push it forward. If you wanted to rebase that patch it would be a good starting point.

14

Yup, as the author of it, it’s just that I have not had the time.

I would recommend re-doing the work rather than literally rebasing; we’ve since added pages to the website, even…

15

Thanks for replying @brson and @steveklabnik

OK, just to clarify (I’m afraid to break things), what I need to do is clone the existing rust-www repo, make a new branch, do the translation and then submit a PR?

16

Don’t worry, you can’t break anything :smile:

You have the process exactly right.

17

Alright, cool. Will do it then :smiley: Any convention for the branch name then?

18

We don’t have any official conventions.

19

It’s been a while, but we just merged initial work on the infrastructure needed to translate the website: https://github.com/rust-lang/rust-www/pull/296#issuecomment-231400676

See it live at https://www.rust-lang.org/ which should redirect you to https://www.rust-lang.org/en-US/ !

20

Hello, I’d like to localize docs in French. I am contributing to MDN for JS and other docs. In order for “API-like” pages not to stale too much, we use doc status pages for l10n and for English. I don’t know if this could work here but it’s a really helpful tool for maintenance (as pointed by @Uther).

(agreed with what has been said for both site and book, no idea for compiler though :/) Looking forward contributing to this :smiley:

1 Like