search

reactjs / react.dev

The React documentation website
https://react.dev/
Creative Commons Attribution 4.0 International
10.95k stars 7.47k 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!

gaearon commented 5 years ago

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 commented 5 years ago

Español would be cool 😎

gaearon commented 5 years ago

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 commented 5 years ago

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

carburo commented 5 years ago

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

alejandronanez commented 5 years ago

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

dmoralesm commented 5 years ago

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

smikitky commented 5 years ago

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

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 commented 5 years ago

@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 commented 5 years ago

@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 commented 5 years ago

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

tesseralis commented 5 years ago

@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 commented 5 years ago

@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 commented 5 years ago

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

tesseralis commented 5 years ago

@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 commented 5 years ago

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

cezaraugusto commented 5 years ago

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 https://github.com/reactjs/reactjs.org/issues/1605#issue-404567798 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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

sheplu commented 5 years ago

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

RaulTsc commented 5 years ago

Willing to do the Romanian version.

gmsecrieru commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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.

tdd commented 5 years ago

Hey team @gaearon @tesseralis — we have deep React expertise and a strong React reputation on the French market, coupled with extensive experience in translating content, tech and nontech, from English to French (Node, Jest, Dan's Overreacted blog and lots, lots more) and we'd love to help with the French docs!

There's only 6% translation in Crowdin right now, which doesn't even cover any of the critical pages, it seems, but we can use that as a springboard and build from there.

D1no commented 5 years ago

I’m bilingual to English/German and some Russian; and I’m a software architect familiar with the whole react ecosystem — happy to help!

Why no Machine Translation?

Having an AI translate content by default seems to make more sense; humans down the chain can correct/clarify/patch sections for clarity.

If the content is labeled accordingly (machine translated), it’s easy for any reader coming by to make quick win suggestions of improvements instead of starting at 0.

_Anybody who has tried chrome / google translatation APIs recently, might have seen that it became incredible good at doing this kind of stuff. I.e. I use some Russian tech and work with chrome translate all the time._

rickbeerendonk commented 5 years ago

I can help with Dutch.

haimengzhang commented 5 years ago

Hi, I'm interested in maintaining Chinese translations, in either simplified or traditional. @chloewlin we can team up if you want!

Keraito commented 5 years ago

Hi there, I would definitely like to help out and maintain a Dutch translation. Maybe @rickbeerendonk we can also team up!

thib92 commented 5 years ago

Hi 👋🏼 I’d be glad to help with French translations! I don’t have experience in translating technical documentations, but I’ve been working on several projects with French-only teams and contributed documenting the code-base in French.

jcserracampos commented 5 years ago

I want to help with Portuguese translations. I have experience translating Ruby's documentation.

davidcsejtei commented 5 years ago

Sounds great! I'd like to help with the Hungarian translation! :)

pepjo commented 5 years ago

I would enjoy teaming up with @seraco to maintain a catalan version of the docs :)

I have previous experience with translations on Facebook and other proprietary software.

tesseralis commented 5 years ago

@D1no Chrome and other browsers have the option of translating a page automatically, so people can just read the English docs machine translated there.

Also maintainers are more than welcome to use machine translation as a base for their efforts, and we can in the future think of ways to make that process easier. We don't want to dump raw machine translated text to official translations the same reason we don't like Crowdin: we want to maintain translation quality for official documentation, and having dedicated human reviewers and maintainers is still the best way to do that.

shawnkoon commented 5 years ago

I am willing to help out with Korean translation! I have some experience contributing to other open source docs, so this will be a great opportunity 👍

eduardomoroni commented 5 years ago

If there's a Brazilian Portuguese's team needing help let me know :)

Naturalclar commented 5 years ago

I'd like to help out with maintaining and translating documents in Japanese! 🤗

techandmedia commented 5 years ago
  • 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.

Hi Nat, I am Andri and I am from Indonesia. I agree with you on this; it's bothering me that some translator from my country still using this "Google translator" with no effort on their side!

  1. Copy pasting to a machine translator is not an effort
  2. Not reading your translation then submit the result is not an effort.

If you have some experience maintaining open source translations and would like to maintain an official React docs translation into your language, please leave a comment, and we can talk about further steps.

I don't have any experience in maintaining open source translations but I would like to learn. So if you already have Indonesian group as a translator and needs an editor, let me know and I'll be glad to help.

hg-pyun commented 5 years ago

Looks good to me!, I interested in Korean language translation and maintaining :D, I have been experience translating some react document. Like this.

icarlossz commented 5 years ago

I can help you with the spanish translation, I'm a native Spanish speaker and have already helped translate other projects.

tesseralis commented 5 years ago

Hi folks!

We've decided to go with the following three languages to start off with:

Japanese: https://github.com/reactjs/ja.reactjs.org Chinese: https://github.com/reactjs/cn.reactjs.org Spanish: https://github.com/reactjs/es.reactjs.org

If you would like to help with any of those translation efforts, check their wiki for further instructions!

If you want to help with any of the other languages, feel free to continue to contribute to the Crowdin to use as a base (although you might want to wait until tomorrow -- we just reuploaded the translations and need to sync them). Please DO NOT create additional forks -- we would like to work with a small subset of teams at first in order to iron out any issues with this process.

QC-L commented 5 years ago

@tesseralis Chinese：https://github.com/reactjs/cn.reactjs.org Not ch. The same error occurred in the wiki.

tesseralis commented 5 years ago

@QC-L thanks XD

re-fort commented 5 years ago

@tesseralis When merging the PR with merge commits, the bot creates an extra issue because the commits on master branch include all commits on source branch. For this reason, I recommend change the setting to allow only squash merge on this repo if possible :)

gaearon commented 5 years ago

To be clear — if everything goes well we don’t plan to hold off other languages for long. The first pilot period will likely be something like a week and then we’ll add more.

chloewlin commented 5 years ago

Hi @haimengzhang and anyone who wants to work on either simplified or traditional Chinese, we can open another discussion thread elsewhere to discuss how to work together and the possibility of creating another fork for traditional Chinese, such as https://github.com/reactjs/tw.reactjs.org. You can also find me on twitter at @chloewlin and message me there. :)