search

reactjs / react.dev

The React documentation website
https://react.dev/
Creative Commons Attribution 4.0 International
11.04k stars 7.54k forks source link

reactjs.org Localization Forks #1605

Closed tesseralis closed 5 years ago

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:

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:

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

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:

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!

tesseralis commented 5 years ago

@chloewlin I added you and others to the group! We're working on Simplified Chinese right now (sorry, I'll specify it in the documents) and we actually have an issue on how we're going to name simplified vs traditional chinese here: https://github.com/reactjs/cn.reactjs.org/issues/1

QC-L commented 5 years ago

@tesseralis
Please check this join us discussion.

tesseralis commented 5 years ago

@QC-L already sent you an invite 🙂

lcxfs1991 commented 5 years ago

I have make some suggestions in this issue. Please check.

https://github.com/discountry/react/issues/334

@tesseralis

robertying commented 5 years ago

@tesseralis I would like to help with Simplified Chinese translations

dkozickis commented 5 years ago

I'd like to help with Russian when you start the second round. Keep it up!

jvelezpo commented 5 years ago

Ok there are others interested in helping with Spanish.... I am one more willing to help with Spanish translation s too :)

goto1 commented 5 years ago

Would like to help with translations to Polish.

telmogoncalves commented 5 years ago

I'm happy to help with translations to Portuguese 🇵🇹

shaodahong commented 5 years ago

@tesseralis I'd like to help with the Chinese Translation

shaodahong commented 5 years ago

like https://github.com/webpack-bot create issues

bartlomiejzuber commented 5 years ago

I will be happy to help you with Polish translations. 🇵🇱 @goto1

anthony2025 commented 5 years ago

Would be a pleasure to help maintain the Spanish repo 🇪🇦! I'm a native speaker and once gave a hand in a similar approach with the styled-components docs site.

tesseralis commented 5 years ago

Hi everyone!

We've added issues to keep track of the Spanish, Japanese, and Simplified Chinese translations:

Please look at those pages if you would like to contribute.

hg-pyun commented 5 years ago

Where is Korean Language? T.T

ghost commented 5 years ago

Subscribing; could help with the 🇫🇷 French version as well! 🖖

Heegiiny commented 5 years ago

I can help with Russian translation.

ltmylinh commented 5 years ago

I can help to translate into Vietnamese.

suyalcinkaya commented 5 years ago

I'd be happy to help you with the Turkish translations. 🇹🇷Helped @gaearon with the overreacted.io before :)

GasimGasimzada commented 5 years ago

Me and my team would like help with translating the docs to Azerbaijani 🇦🇿

CatVas commented 5 years ago

Hey, let's make a Ukrainian version too! I am interested to help.

gedeagas commented 5 years ago

Finally, we stoped working on the translation on crowdin because there is no clear goal or plan from the facebook team regarding integrating crowdin translation into the main repo.

Now that there is a clear goal about it what do we need to do to make a repo for the indonesian translation ? @tesseralis @gaearon

cc @regalius, @zainfathoni who helped the indonesian translation for react in crowdin before.

regalius commented 5 years ago

Yes, I'd be glad to help with the Indonesian translation again and gather other contributors that had the same vision! I do agree that with the version-controlled internationalization we can have better quality compared to our Crowdin effort, because in Crowdin everyone can edit the translation and there's no review process or whatsoever

gedeagas commented 5 years ago

@regalius last time that i talk to @ericnakagawa at f8, the crowdin translation will have someone that can "verify" aka proofread the translation. so only translation that passed can got into master.

anyway, facebook Indonesia translation team is coming to Malang, and i would like to ask them tips and tricks translating technical documentation from english to Indonesia. because they also work on facebook for developer sites.

will keep you updated.

tesseralis commented 5 years ago

@regalius @gedeagas hmm... According to @smikitky it seems that the Japanese translation was pretty decent quality. I don't know how the Indonesian one got so bad 🤷‍♀️

But that's also one advantage of github... it's more likely that developers know how to use it.

smikitky commented 5 years ago

As far as reviewing is concerned, GitHub is working much better at least in the Japanese fork. As this comment pointed out, learning a new system can be a blocker itself. I personally have never understood how reviewing works on Crowdin, and there were not enough people to cast votes, anyway :)

smikitky commented 5 years ago

There is one thing Crowdin is probably better at; it tracks translations based on sentences (rather than lines), and it can automatically find existing translations from identical/similar sentences. This can be useful when a similar sentence appears in many articles, or when someone moved a sentence to another page in the original repository. In simple cases this is not hard to manage with Git at all, but if a huge refactoring should happen in the original, Crowdin might do a little better job. (Fortunately, @gaearon confirmed there won't be a big rewrite soon regarding 16.8.0)

regalius commented 5 years ago

@tesseralis Last time I checked when I was still actively contributing, some ppl that worked on the Indonesian translation are just too excited to contribute, but they're not really that good at English so they just copy-pasted words from Google Translate. Was trying to fix some of those translation errors but since it looks like the plan to integrate the translation are somewhat half-abandoned I choose to halt my contribution to the project. But now, since the effort are moved to GitHub, I think we can facilitate their enthusiasm with proper review and contribution process so we can strive more for the quality of the translations itself.

@gedeagas That's great, looking forward to it mas 👍

Agreed with @smikitky TBH, I also never understood the vote system in Crowdin.

gedeagas commented 5 years ago

@regalius That's exactly the problem, they just copy-pasted words from Google Translate and didn't understand the context.

I have my meeting with them Thursday this week, will ask them about the glossary translation for Indonesian and will ping you via messenger to discuss this more deeply.

@smikitky i also never understood the vote system in Crowdin hahaha.

arfianadam commented 5 years ago

@gedeagas @regalius I saw some of those translated-to-Indonesian pages and gosh they are terrible 😅 I'd be more than glad to help you with the project. Do we already have the fork/repo for the Indonesian translation?

tesseralis commented 5 years ago

@arfianadam not yet, but expect one to come very soon :)

sJJdGG commented 5 years ago

Would be glad to maintain the farsi/persian translations.

SastraNababan commented 5 years ago

@regalius @gedeagas @arfianadam I'd be happy to help you guys with the indonesia translations.

Nab69 commented 5 years ago

I'm interested in helping with the french translation (fr-fr) ;)

tdd commented 5 years ago

@Nab69 awesome, that's 5–6 of us. We'll get in touch and coordinate once the FR fork repo is up and invites are done.

bugtender commented 5 years ago

@chloewlin @haimengzhang I'd like to help with the Traditional Chinese version. 👍

tesseralis commented 5 years ago

We're now accepting maintainers for new languages! The instructions are here:

https://github.com/reactjs/reactjs.org-translation#starting-a-new-translation

Submit a PR to the reactjs.org-translation repo if you want to be a maintainer!

gedeagas commented 5 years ago

@tesseralis thank you

@regalius @arfianadam @SastraNababan Let's do it guys

ENvironmentSet commented 5 years ago

@hg-pyun @taggon hi, I want to translate react document into korean, too. can I join?

cadenzah commented 5 years ago

@hg-pyun @taggon I would like to participate in translating in Korean! May I join in?

taggon commented 5 years ago

In case you missed it, the Korean translation repository is already created. Please visit there for further discussion. @ENvironmentSet @cadenzah

ENvironmentSet commented 5 years ago

@taggon

thank you for notifying, I've joined that repository also react korea slack :))

Darking360 commented 5 years ago

Greetings! I've been collaborating wih the spanish translation, and it's been a great experience so far 🚀

I was wondering if you need more maintainers in the Spanish repo, since I have some free time lately, I'd love to join this team 😅

@tesseralis

tesseralis commented 5 years ago

@Darking360 It's up to the current maintainers! @carburo @alejandronanez would you like an additional maintainer?

jochenboesmans commented 5 years ago

Hey @rickbeerendonk, @Keraito, would you guys like to team up for a Dutch translation?

Keraito commented 5 years ago

I'm down @jochenboesmans! Gonna make the PR immediately! 😃

carburo commented 5 years ago

@Darking360 I'll check with @alejandronanez. We haven't discussed yet which criteria to use for adding a new maintainer.

alejandronanez commented 5 years ago

Hey @carburo, let’s talk about this tomorrow or Monday the latest. I got a pretty tight schedule today and maybe tomorrow too. Which channel should we use for this kind of conversations? Maybe Spectrum?

Let me know!

tesseralis commented 5 years ago

It's up to the current maintainers to choose whether they want to add folks. Are you fine handling things on your own or do you find yourselves being stretched thin? Do you have processes among your group that you would need to onboard people to? Has the person offering contributed to the translations or has any other experience? That said, it's not that much of a burden to add someone that ends up not participating much in the maintenance.

carburo commented 5 years ago

Yes @alejandronanez, Spectrum is fine. I agree with @tesseralis, I am not super busy right now but sometimes I will, so an extra pair of hands is always welcome. It is just a decision we have to make as a team.