Repository navigation
reactjs.org Localization Forks #1605
Description
Activity
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.
Reacted by Be MOre Bot, mame-col, Chak Shun Yu, Shirshak, Luiz Felipe Frazão, Takuma HANATANI and FillEspañol would be cool 😎
Reacted by David Morales, Zava, S., Anthony Ascencio and Miguel Alejandro Bolivar PortillaTo 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.
Reacted by Nat Alison, Takuma HANATANI, Rainer Martinez, Anesh Parvatha, Alejandro Ñáñez Ortiz, Daiki Ihara, Ernesto García, Brett Beutell, Agastya Darma, Fill and 2 moreI am interested in maintaining documents in Japanese.
If you need my contribution, please let me help you.Reacted by Nat Alison, Rainer Martinez, Anesh Parvatha and Lazar LjubenovićI am interested in getting involved. I could contribute maintaining Spanish translations.
Reacted by Nat Alison, Alejandro Ñáñez Ortiz, Takuma HANATANI, S. and Miguel Alejandro Bolivar PortillaI’m in the same boat as @carburo. Willing to help with spanish docs. 👍🏼
Reacted by Rainer Martinez, Nat Alison, Takuma HANATANI and Miguel Alejandro Bolivar PortillaWilling to team up with @carburo and @alejandronanez to maintain spanish docs 😁
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 :)
Reacted by Carl-Erik Kopseng and seungha-kimReacted by seungha-kimReacted by Takuma HANATANI and seungha-kim@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.
@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 :)
Reacted by Soichiro Miki and Carl-Erik KopsengPlease feel free to ask, we want to cooperate you. :)
Reacted by Takuma HANATANI@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.
@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-apisin this case). Either way, I agree that a test to detect broken links and inconsistent anchors is always desirable.Hi there, I am interested in maintaining documents in Traditional Chinese.
Reacted by taitung and JuanitoReacted by JuanitoReacted by Nat Alison, Haimeng Zhang, Chak Shun Yu, taitung and JuanitoReacted by Juanito@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 :)
90 remaining items
I think I probably need to be involved (to setup the subdomains at least) which is why I was asking here 😄
Reacted by Nat AlisonReacted by chloeReacted by Miguel Alejandro Bolivar PortillaI am interested in maintaining documents in Cambodian (Khmer) language. If you need my contribution, please let me know. Thanks!
- Reacted by Bunlong VAN, Takuma HANATANI, Soichiro Miki and Felix Tan
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.jsand apackage.jsonin the language forks.@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?
@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.jsalready 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.
- 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
@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.
@tesseralis Great! I will try to first handle the configuration part, then see how to convert it into a gatsby theme.
Reacted by Abdullah Hilson@GasimGasimzada Thanks for taking charge on this! ^_^
Reacted by Gasim GasimzadaCould we move discussion of this to its own issue so it doesn't clutter up this (really long) thread?
Yes, please do.
@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
🌐🚨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:
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: #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!