reactjs.org Localization Forks

tesseralis commented 5 years ago

🌐🚨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 (https://github.com/reactjs/reactjs.org/pull/873 and https://github.com/reactjs/reactjs.org/issues/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

[x] Pick a "partner team" (or two) of translators for a proof-of-concept.
- Simplified Chinese: https://github.com/reactjs/zh-hans.reactjs.org/issues/4
- Spanish: https://github.com/reactjs/es.reactjs.org/issues/4
- Japanese: https://github.com/reactjs/ja.reactjs.org/issues/4
- [x] Prepare reactjs.org for forking/translation
[x] 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).
[x] Add a translations page/dropdown to the site! 😊 - PR #1691
[x] Ensure that anchor names for headers, which are currently auto-generated, remain consistent across translations (thanks @smikitky)
- Issue: https://github.com/reactjs/reactjs.org/issues/1608
- [x] Create the bot and/or git hooks to create issues/cherry-picks when the original English React documentation changes.
- [x] Create a guide for starting a new translation project and integrating the bot.
- [x] Make a site to keep track of translation progress for various languages (https://github.com/reactjs/reactjs.org/issues/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: https://github.com/reactjs/reactjs.org/pull/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!

bvaughn commented 5 years ago

What's the plan to connect the translated languages to Netlify and setup subdomains for them?

tesseralis commented 5 years ago

@ericnakagawa is working on that right now

bvaughn commented 5 years ago

I think I probably need to be involved (to setup the subdomains at least) which is why I was asking here 😄

Bunlong commented 5 years ago

I am interested in maintaining documents in Cambodian (Khmer) language. If you need my contribution, please let me know. Thanks!

tesseralis commented 5 years ago

And we're live!

https://reactjs.org/languages https://reactjs.org/blog/2019/02/23/is-react-translated-yet.html

abumalick commented 5 years ago

Have you considered using gatsby themes ? You could avoid having source code in all the forked repositories. I think you would end up with the translations files, a gatsby-config.js and a package.json in the language forks.

tesseralis commented 5 years ago

@abumalick It's certainly an improvement I've thought of, but we haven't had time to implement it. Would that be something you'd be interested in?

GasimGasimzada commented 5 years ago

@abumalick This sounds like a great thing to do but if this is implemented, firstly, translatable strings need to be extracted from the components. I think since gatsby-config.js already holds strings that are translatable (title, RSS, “Try in CodePen”), maybe moving other translatable strings (e.g “Edit this page”) into gatsby config would make the transition easier.

@tesseralis this would be a cool thing to have because any changes to the theme itself will be just a package upgrade away.

tdd commented 5 years ago

It seems to me that code samples actually get some translation (string literals, comments etc) so keeping them per-locale would be better.

On Tue, Aug 20, 2019, at 02:35, Nat Alison wrote:

@abumalick https://github.com/abumalick It's certainly an improvement I've thought of, but we haven't had time to implement it. Would that be something you'd be interested in?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/reactjs/reactjs.org/issues/1605?email_source=notifications&email_token=AAAA5KB4ASWG27LI5RSJ7F3QFM35XA5CNFSM4GTFGNK2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD4UWA7Q#issuecomment-522805374, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAA5KHEWFT6N5X4RQZS2VTQFM35XANCNFSM4GTFGNKQ.

-- Christophe Porteneuve tdd@tddsworld.com

tesseralis commented 5 years ago

@GasimGasimzada it would be a fair amount of work. If we want to do this, we should probably do it in steps, for example extracting most of the strings in component to gatsby config. We also need to be able to support right-to-left natively, not to mention updating each translation as we go.

The problem is, the React team is too busy to work on this stuff (since they're working on, you know... React), and I'm doing my own stuff as well. But if anyone wants to put in the effort to get it done, I'd be happy to review PRs and provide feedback.

GasimGasimzada commented 5 years ago

@tesseralis Great! I will try to first handle the configuration part, then see how to convert it into a gatsby theme.

tesseralis commented 5 years ago

@GasimGasimzada Thanks for taking charge on this! ^_^

tesseralis commented 5 years ago

Could we move discussion of this to its own issue so it doesn't clutter up this (really long) thread?

GasimGasimzada commented 5 years ago

Yes, please do.

GasimGasimzada commented 5 years ago

@tesseralis https://github.com/reactjs/reactjs.org/pull/2270

abumalick commented 5 years ago

@abumalick It's certainly an improvement I've thought of, but we haven't had time to implement it. Would that be something you'd be interested in?

I missed the notification, it seems the task has been taken quickly 👍

@GasimGasimzada Tell me if you want some help

reactjs / react.dev