reactjs.org Localization Forks

[tesseralis]

🌐🚨See here if you'd like to be a language fork maintainer! 🚨🌐

Hi everyone! My name is Nat and I'm picking up on the work Brian (@bvaughn) and Eric (@ericnakagawa) have been doing to internationalize the React documentation website (#873 and #82). To this end, Dan (@gaearon) and I were discussing alternate proposals to our current approach using Crowdin when we came across how the Vue team localizes their documentation (https://vuejs.org), and we think it may be a simpler and better approach for translating the React docs.

The Approach

For vuejs.org, each translation is managed in a separate fork of the main repo by a dedicated team (e.g. https://jp.vue.org) that is synced to keep in line with the main repo. In particular, the Japanese translation uses a bot (https://github.com/vuejs-jp-bot) that performs the following functions:

• Watch the RSS feed of the original repo for changes and look at the diff
• If there is no conflict:
  • Submit a PR that automatically cherry pick those changes onto the fork
• If there is a conflict (e.g. because of text that needs to be translated)
  • Create an issue

In effect, the bot will automatically update any pure code changes to the site, and create an issue anytime the text changes, indicating new translation needs to occur.

Dan and I like this approach and think it would be a good fit for React's translation efforts. It would unload a lot of the work from the React core team and put it into the hands of dedicated translators. In addition:

• It inspires ownership over the individual language branches and lead to higher quality translations than Crowdin has offered so far.
• It would be easier to prevent stale translations since issues would be generated to keep track of what copy needs to be changed.
• Translations would be versioned in lockstep with the main React docs.

In addition, @potato4d, one of the maintainers of the Japanese Vue fork, mentioned that compared to SaaS solutions like Crowdin, people were more motivated to provide translations when they could contribute directly to the Github org, and that git's conflict resolution strategies were better than third party ones.

Below I will list the steps needed to make this happen, concerns we have, alternatives we have considered, and what we need help with from the international React community.

Steps

• Pick a "partner team" (or two) of translators for a proof-of-concept.
  • Simplified Chinese: OLD CLAIMS zh-hans.react.dev#4
  • Spanish: [OLD] Legacy Spanish Translation Progress es.react.dev#4
  • Japanese: Japanese Translation Progress ja.react.dev#4
• Prepare reactjs.org for forking/translation
  • Make sure that the site works under a different subdomain and that there are no absolute URLs (no links to reactjs.org from jp.reactjs.org).
  • Add a translations page/dropdown to the site! 😊 - PR Add "Languages" page #1691
  • Ensure that anchor names for headers, which are currently auto-generated, remain consistent across translations (thanks @smikitky)
    • Issue: Support explicit heading IDs #1608
• Create the bot and/or git hooks to create issues/cherry-picks when the original English React documentation changes.
• Create a guide for starting a new translation project and integrating the bot.
• Make a site to keep track of translation progress for various languages ("Is React Translated Yet?" #1619)
  • https://www.isreacttranslatedyet.com

Open Questions and Concerns

Existing work on CrowdIn

Eric brought up that a lot of work has already been put in the CrowdIn translations, and there is a fear of letting that community work go to waste. However that work won't necessarily be thrown away -- translators can use the Crowdin translation as a base when building the new fork (though we have to be careful that we don't keep any stale content).

Frequently changed files

Brian brought up that sometimes files are heavily edited in a short period of time (e.g. the Hooks proposal). This would mean that lots of issues get created under a short period of time, especially if they are auto-generated by a bot. In cases like this, The React team can coordinate with translation groups to make sure they're prepared. Additionally, while the bot can create issues, it is ultimately up to the fork maintainers to decide how to handle this. For example, they could decide to only translate the initial Hooks proposal and wait until the API is finalized before making changes to avoid having to make copious edits.

Maintenance

Maintaining a fork means that language maintainers must know the internals of the react website. However, that might actually be an advantage of this approach: if you're maintaining a translation for the React documentation, you better know how to use React!

Additionally, requiring translations be under a subdomain makes it harder to start up a new translations in a new language. To mitigate this, we plan on setting up a How-to guide to ease people setting up their own repositories and translations. We can also start a process of "graduating" translations: once the translation moves past a certain benchmark (e.g. Home page + tutorial + main concepts + API), move ownership to the main ReactJS Github org to mark it as an "official" translation effort and add it to the official list of translations.

One open question is how licensing and hosting would work. Dan is reaching out to folks to figure that out.

Alternatives

Crowdin

The initial plan was to integrate and serve translated pages with Crowdin, as demonstrated by Brian's PR: #873. We have some issues with Crowdin:

• It's complicated, it requires a significant amount of code integration to get off the ground.
• Updates to the site require a very awkward and possibly destructive syncing process
• Translation quality varies. For example, in the Indonesian translation, "function" in a code block was translated as "funksi". While an Indonesian language version of JS would be amazing, I don't believe that is currently the case.

Translations in one repository

An alternative approach taken by Nuxt.js is to put all translations in the same repo and use a traditional i18n library to switch between them. But, as Dan pointed out, reactjs.org already has hundreds of pull requests and PRs, and any copy change would bloat up the number of issues, especially if they are automatically generated.

What we need help with

If you have some experience maintaining open source translations and would like to maintain an official React docs translation into your language, submit a PR to this repo to add your language!

[gaearon]

Some notes from an email exchange with @gbezyuk:

As for the percentage of translated material before publushing, I believe the only hard rule is never to publish partly-translated sections. It's okay if only small part of sections are translated, but if a particular section is a mess of different languages and not proof-read properly, it looks really ugly.

Another important thing to keep in mind is the glossary consistency. Probably, a consistency between Vue and React docs won't hurt, too.

These are both very good points IMO.

[thehme]

Español would be cool 😎

[gaearon]

To be clear: at this point we’re looking for comments from people who are actually interested in getting involved and maintaining the translations.

We appreciate the enthusiasm but let’s keep the conversation focused on next steps rather than language requests.

[potato4d]

I am interested in maintaining documents in Japanese.
If you need my contribution, please let me help you.

[carburo]

I am interested in getting involved. I could contribute maintaining Spanish translations.

[alejandronanez]

I’m in the same boat as @carburo. Willing to help with spanish docs. 👍🏼

[dmoralesm]

Willing to team up with @carburo and @alejandronanez to maintain spanish docs 😁

[smikitky]

I basically prefer this approach, and I'm also interested in maintaining the Japanese fork.

• Picking up existing translations from Crowdin will require some manual labor, but I'm fine with that. As an existing translator, I vaguely knew this should happen sooner or later :) But @ericnakagawa , please make the content downloadable so that we can use our favorite text editors 🙏
• Before forks happen, I think we should stop auto-generating anchor names from the heading text (e.g. #next-steps, #only-call-hooks-at-the-top-level). Autolink does more harm than good because: 1) translating one heading would mean having to search in the entire docs and change multiple files simultaneously, 2) urlencoded CJK anchor names are ugly and unreadable, and 3) anchors are part of URLs and thus should not be translated anyway, just as file names should not be translated. We can insert something like <a id="next-steps"></a> before each heading (using a simple script), but there may be a markdown-friendly syntax.
• A typical issue generated by vuejs-jp-bot is simple like this. It's already usable, but I think it could be smarter. Showing the list of existing open issues (untranslated commits) for the same file will definitely help.

By the way, I already have a markdown-based Japanese translation of the Hooks doc, hosted here: https://react-doc-jp-temp.netlify.com/ It's not a full fork because I was anticipating this would happen officially :)

[tesseralis]

@smikitky thank you so much for replying! Yes, we should make the Crowdin translations downloadable, but I also have access to the compiled translations if that will unblock you.

As for anchor names, that's a really good point! I'll put in a task to do that :)

I think we'll definitely work off the vuejs-jp-bot to get it working and start off simple, but those are good suggestions for improvements.

[tesseralis]

@smikitky also there is a markdown syntax for heading ids: https://www.markdownguide.org/extended-syntax/#heading-ids

We just need to make sure they're supported :)

[kazupon]

Please feel free to ask, we want to cooperate you. :)

[tesseralis]

@smikitky another approach I'm thinking: keep the auto-generated ids in the original english repo, and add a lint rule / test in the translations that raw titles need to have the original English ID (e.g. #始める前に {#before-we-start-the-tutorial}).

The advantage of the autogenerated ids is that they're consistent. If we enforce that every heading needs an ID it's possible for new English documentation writers to misspell or create inconsistent conventions.

[smikitky]

@tesseralis That means each translator would need to type something like {#what-do-hooks-mean-for-popular-apis-like-redux-connect-and-react-router} (or create a plugin/script to automate this), which I feel is a little painful. If there are 10 languages, 10 different people have to repeat this for each heading. Removing autolink can be beneficial also for future English doc writers because they can choose an arbitrary short name (e.g. #other-apis in this case). Either way, I agree that a test to detect broken links and inconsistent anchors is always desirable.