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.

[chloewlin]

Hi there, I am interested in maintaining documents in Traditional Chinese.

[tesseralis]

@smikitky Haha, true! Though I do think most of the english headings are short (e.g. # Examples), and it might be annoying to mandate an ID for those (# Examples {#examples}). Maybe as a compromise the hypothetical linter could show an error if the English slug would be longer than, say, 20 characters, and require a manual short url.

Either way, it doesn't seem like the manual ID syntax is supported right now, so I'll go and take a look at that so we can support it in both English and translations :)

[fjoshuajr]

Great! I'm interested in maintaining the Portuguese translations.

[cezaraugusto]

I've been translating stuff for a while in some projects (here on GH and with tools like MDN, Crowdin, Transifex, and others. Also maintain the YDKJS book series translation to PT-Br w/ other friends) and I'd go 100% with GitHub. Devs are much more motivated to work here with a tool that most use on a daily basis and the git familiarity helps a lot. I've tried motivating friends to help on other platforms and having to understand "how things work" have reduced their willingness to contribute most of the times.

I also believe there is little interest from developers in other platforms due to the lack of recognition of their work. People are proud of their contributions and want to show them (such as in the GH contribution graph or commit history) so GitHub also takes advantage over other platforms here.

So ya, the process described in #1605 (comment) to set up a "how-to" guide + graduating process sounds a great plan.

I'm interested in setting up/helping the PT-Br (Portuguese from Brazil) translations. Also, cc @gmsecrieru @wesmelo @glaucia86 who hugely helped translating some projects I contribute and might want to jump in as well. Local React community is super friendly, hopefully others will join too.

[another-guy]

If you have some experience maintaining open source translations.

Sigh. I do not have such experience but was hoping to get some (native Russian speaker).

[smikitky]

@tesseralis Introducing a new heading with an explicit ID in the English repo is a one-time job, and testing the consistency within # When to Use Refs {#when-to-use-refs} itself is easy if you worry about spelling errors. I understand it's visually displeasing to the eyes of English speakers, but it's not so for speakers of other languages. On the other hand, manually generating a slug for each heading in each page in each language is a repetitive task, and testing the consistency between the original repo and each fork can be trickier.

[taggon]

Awesome. I'm interested in maintaining the Korean translations. I've translated Node.js documentation for many years as a member of the official Node.js Korean localization team.

[lazarljubenovic]

I'm interested in writing and maintaining Serbian translation -- this would pretty much cover Croatian, Bosnian and Montenegrin as well since the languages are more of a dialect of each other and we can understand each other with no difficulty.

I have experience in translation (eg. the Pro Git book), and I love doing it as it helps me really read the entire documentation and understand it instead of skipping around.

However, I have no experience in the described setup, but I can't wait to try it out. Always love to experiment with automated utilities which take the boring and repetitive work off from developers' shoulders.

[HeinZawHtet]

Willing to help with Myanmar/Burmese docs. helped translating Laravel before.

[sheplu]

Awesome ! I'm interested in helping with the french translation.
I'm confident @setheal would love to help :)

[RaulTsc]

Willing to do the Romanian version.

[gmsecrieru]

Count me in! 😄 Like @cezaraugusto mentioned we have been doing a good job in cezaraugusto/You-Dont-Know-JS for a few years with Github.

[lex111]

I could help in translating the documentation into Russian. In fact, I have a repository with a partial translation, it's already very outdated, but in general it can be used as a starting point.
Repo - https://github.com/js-ru/react-ru
Link - https://ru.react.js.org/

[glaucia86]

I've been translating stuff for a while in some projects (here on GH and with tools like MDN, Crowdin, Transifex, and others. Also maintain the YDKJS book series translation to PT-Br w/ other friends) and I'd go 100% with GitHub. Devs are much more motivated to work here with a tool that most use on a daily basis and the git familiarity helps a lot. I've tried motivating friends to help on other platforms and having to understand "how things work" have reduced their willingness to contribute most of the times.

I also believe there is little interest from developers in other platforms due to the lack of recognition of their work. People are proud of their contributions and want to show them (such as in the GH contribution graph or commit history) so GitHub also takes advantage over other platforms here.

So ya, the process described in #1605 (comment) to set up a "how-to" guide + graduating process sounds a great plan.

I'm interested in setting up/helping the PT-Br (Portuguese from Brazil) translations. Also, cc @gmsecrieru @wesmelo @glaucia86 who hugely helped translating some projects I contribute and might want to jump in as well. Local React community is super friendly, hopefully others will join too.

For sure my friends. All of you can count on me. I really enjoy to make many contributions to open source projects! So yes! Please, I would love to help translating to PT-BR and another projects too.

thanks @cezaraugusto for mention me here! :)

[glaucia86]

Olá a todos! Meu nome é Nat e estou pegando o trabalho que Brian ( @bvaughn ) e Eric ( @ericnakagawa ) têm feito para internacionalizar o site da documentação do React ( # 873 e # 82 ). Para esse fim, Dan ( @gaearon ) e eu estávamos discutindo propostas alternativas para nossa abordagem atual usando Crowdin quando nos deparamos com a localização da documentação da equipe Vue ( https://vuejs.org ), e achamos que pode ser uma tarefa mais simples. e melhor abordagem para traduzir os documentos do React.

A abordagem

Para o vuejs.org, cada tradução é gerenciada em uma bifurcação separada do repositório principal por uma equipe dedicada (por exemplo, https://jp.vue.org ) que é sincronizada para manter a linha com o repositório principal. Em particular, a tradução em japonês usa um bot ( https://github.com/vuejs-jp-bot ) que executa as seguintes funções:

• Assista ao feed RSS do repositório original para mudanças e veja o diff

• Se não houver conflito:

  • Envie um PR que selecione automaticamente as alterações na bifurcação

• Se houver um conflito (por exemplo, por causa do texto que precisa ser traduzido)

  • Crie um problema

Com efeito, o bot atualizará automaticamente qualquer alteração de código puro no site e criará um problema a qualquer momento em que o texto for alterado, indicando a necessidade de nova tradução.

Dan e eu gostamos dessa abordagem e achamos que seria uma boa opção para os esforços de tradução da React. Ele descarregaria muito do trabalho da equipe principal do React e o colocaria nas mãos de tradutores dedicados. Além do que, além do mais:

• Ele inspira a propriedade sobre os ramos de idiomas individuais e leva a traduções de maior qualidade do que a Crowdin ofereceu até agora.
• Seria mais fácil evitar as traduções obsoletas, pois os problemas seriam gerados para manter o controle de qual cópia precisa ser alterada.
• As traduções seriam versionadas em sincronia com os documentos principais do React.

Além disso, @ potato4d , um dos mantenedores do Japanese Vue fork, mencionou que, em comparação com soluções SaaS como Crowdin, as pessoas estavam mais motivadas a fornecer traduções quando podiam contribuir diretamente para a organização do Github e que as estratégias de resolução de conflitos eram melhores do que terceiros.

Abaixo, listarei as etapas necessárias para que isso aconteça, as preocupações que temos, as alternativas que consideramos e o que precisamos de ajuda da comunidade internacional React.

Passos

• Escolha uma "equipe de parceiros" (ou dois) de tradutores para uma prova de conceito.

  • O chinês é o nosso melhor candidato atual, já que eles já têm uma bifurcação atualizada em https://github.com/discountry/react
  • Qualquer coisa com uma conclusão significativa no Crowdin (japonês, indonésio, turco) também é uma opção possível.

• Prepare reactjs.org para forking / translation

  • Certifique-se de que o site funcione sob um subdomínio diferente e que não haja URLs absolutos (não há links para reactjs.org em jp.reactjs.org).
  • Assegure-se de que os nomes de âncora para os cabeçalhos, que são atualmente gerados automaticamente, permaneçam consistentes nas traduções (obrigado @smikitky )
  • Adicione uma página de traduções ao site! 😊

• Crie os ganchos bot e / ou git para criar problemas / picks de cereja quando a documentação original do English React mudar.

• Crie um guia para iniciar um novo projeto de tradução e integrar o bot.

Perguntas e preocupações abertas

Trabalho existente no CrowdIn

Eric mencionou que muito trabalho já foi colocado nas traduções do CrowdIn, e há um medo de deixar que o trabalho da comunidade seja desperdiçado. No entanto, esse trabalho não será necessariamente jogado fora - os tradutores podem usar a tradução Crowdin como base ao construir a nova bifurcação (embora tenhamos que ter cuidado para não guardarmos nenhum conteúdo obsoleto).

Arquivos alterados freqüentemente

Brian mencionou que às vezes os arquivos são muito editados em um curto período de tempo (por exemplo, a proposta de Hooks). Isso significa que muitos problemas são criados em um curto período de tempo, especialmente se forem gerados automaticamente por um bot. Em casos como esse, a equipe do The React pode coordenar com grupos de tradução para garantir que estejam preparados. Além disso, enquanto o bot pode criar problemas, cabe aos mantenedores do fork decidir como lidar com isso. Por exemplo, eles poderiam decidir apenas traduzir a proposta inicial de Ganchos e esperar até que a API seja finalizada antes de fazer alterações para evitar fazer edições copiosas.

Manutenção

Manter uma bifurcação significa que os mantenedores de idiomas devem conhecer as partes internas do site da empresa. No entanto, isso pode realmente ser uma vantagem dessa abordagem: se você está mantendo uma tradução para a documentação do React, é melhor saber como usar o React!

Além disso, exigir traduções em um subdomínio dificulta o início de novas traduções em um novo idioma. Para atenuar isso, planejamos a criação de um guia de instruções para facilitar a configuração das pessoas em seus próprios repositórios e traduções. Também podemos iniciar um processo de "graduação" de traduções: uma vez que a tradução passe de um determinado benchmark (por exemplo, Home page + tutorial + conceitos principais + API), mova a propriedade para a principal organização do ReactJS Github para marcá-la como uma tradução "oficial" esforço e adicioná-lo à lista oficial de traduções.

Uma questão em aberto é como o licenciamento e a hospedagem funcionariam. Dan está chegando às pessoas para descobrir isso.

Alternativas

Crowdin

O plano inicial era integrar e servir páginas traduzidas com Crowdin, como demonstrado pelo PR de Brian: # 873 . Nós temos alguns problemas com o Crowdin:

• É complicado, requer uma quantidade significativa de integração de código para decolar.
• Atualizações do site exigem um processo de sincronização muito complicado e possivelmente destrutivo
• A qualidade da tradução varia. Por exemplo, na tradução indonésia, "function" em um bloco de código foi traduzido como "funksi". Embora uma versão em língua indonésia de JS seja incrível, não acredito que seja o caso atualmente.

Traduções em um repositório

Uma abordagem alternativa adotada pelo Nuxt.js é colocar todas as traduções no mesmo repositório e usar uma biblioteca i18n tradicional para alternar entre elas. Mas, como Dan apontou, reactjs.org já tem centenas de solicitações de pull e PRs, e qualquer alteração na cópia aumentaria o número de problemas, especialmente se eles fossem gerados automaticamente.

O que precisamos de ajuda com

Se você tem alguma experiência em manter traduções de código aberto e gostaria de manter uma tradução oficial do React docs em seu idioma, deixe um comentário e poderemos falar sobre outras etapas.

I've been contributing in Nodejs.org translation to PT-br. So if you want to count on me I would love to help. Once I really enjoy to help open source projects.

[carburo]

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

[alejandronanez]

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]

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]

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.

[bvaughn]

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

[tesseralis]

@ericnakagawa is working on that right now

[bvaughn]

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

[Bunlong]

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

[tesseralis]

And we're live!

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

[abumalick]

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]

@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]

@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]

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 <#1605>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAA5KHEWFT6N5X4RQZS2VTQFM35XANCNFSM4GTFGNKQ>.

-- Christophe Porteneuve tdd@tddsworld.com

[tesseralis]

@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]

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

[tesseralis]

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

[tesseralis]

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

[GasimGasimzada]

Yes, please do.

[GasimGasimzada]

@tesseralis #2270

[abumalick]

@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