[Beta] Translating New React Docs

[gaearon]

We've recently published a Beta of the new React documentation:

• https://github.com/reactjs/reactjs.org/issues/3308
• https://beta.reactjs.org/

We think it's a good time to kick off the translation effort for some of the pages.

Who is this issue for?

This issue is for existing translation repo maintainers.

What is ok to translate now?

The new docs aren't fully written yet, and some parts will definitely change. However, a lot of the pages are already "stable". We suggest to use this checklist for the beginning. ✅ means "ok to translate", 🔴 means "don't translate yet".

(Updated on Feb 12: more pages ok to translate.)

• [ ] ✅ Installation (note: a lot of content here is similar to old website)
  • [ ] ✅ Start a New React Project
  • [ ] ✅ Add React to a Website
  • [ ] ✅ Editor Setup
  • [ ] ✅ React Developer Tools
• [ ] ✅ Quick Start
  • [ ] ✅ Thinking in React
• [ ] ✅ Describing the UI
  • [ ] ✅ Your First Component
  • [ ] ✅ Importing and Exporting Components
  • [ ] ✅ Writing Markup with JSX
  • [ ] ✅ JavaScript in JSX with Curly Braces
  • [ ] ✅ Passing Props to a Component
  • [ ] ✅ Conditional Rendering
  • [ ] ✅ Rendering Lists
  • [ ] ✅ Keeping Components Pure
• [ ] ✅ Adding Interactivity
  • [ ] ✅ Responding to Events
  • [ ] ✅ State: A Component's Memory
  • [ ] ✅ Render and Commit
  • [ ] ✅ State as a Snapshot
  • [ ] ✅ Queueing a Series of State Updates
  • [ ] ✅ Updating Objects in State
  • [ ] ✅ Updating Arrays in State
• [ ] ✅ Managing State
  • [ ] ✅ Reacting to Input with State
  • [ ] ✅ Choosing the State Structure
  • [ ] ✅ Sharing State Between Components
  • [ ] ✅ Preserving and Resetting State
  • [ ] ✅ Extracting State Logic into a Reducer
  • [ ] ✅ Passing Data Deeply with Context
  • [ ] ✅ Scaling Up with Reducer and Context
• [ ] 🔴 Escape Hatches (not written yet)
  • [ ] ✅ Referencing Values with Refs
  • [ ] ✅ Manipulating the DOM with Refs
• API
  • [ ] ✅ React APIs (ok to translate, but incomplete)
    • [ ] ✅ useState
  • [ ] ✅ React DOM APIs (ok to translate, but incomplete)
    • [ ] ✅ render

We suggest to not translate the Home or section yet because it's too unstable.

Feel free to copy-paste the checklist above into your repo issue and use it to track the translation progress. Here it is in the raw Markdown format.

How to translate?

Currently the beta website is in the beta folder. So all existing translation repos should have it synced (if the sync script is working). So you can follow the existing process. If something doesn't work, please comment here.

Currently, the beta sites don't get deployed for other domains. If your localization fork has translated at least three new pages, comment here and we'll set up a deployment for you. It's a bit of manual work to set up the two websites for each domain so ideally we'd do it for the forks that are actively translating.

Something unclear?

Please comment here with concerns or suggestions. Originally we wanted to suggest translating when more of the content is written. However, some translators have expressed interest in starting earlier so that's why we made this issue.

[arshadkazmi42]

Hi @gaearon

Does that mean, we should stop the translation of the current website, which in progress? And start focusing on this?

[gaearon]

I think that would make the most sense. (Sorry if you spent a bunch of effort on this.)

[arshadkazmi42]

I think that would make the most sense. (Sorry if you spent a bunch of effort on this.)

Thank you for confirmation. Will start working towards that.

[jakubdrozdek]

@gaearon Hey, I just started working on the Polish docs, but unfortunately my first PR's CI checks fail on Analyze bundle job. https://github.com/reactjs/pl.reactjs.org/runs/4360534093?check_suite_focus=true Do you know what's the problem? Is it required to pass?

And second question: where can we preview our translated website and what's the URL for the live Polish beta? The link in PR for Vercel app links to the old React docs: https://plreactjsorg-7luo3ndx9-fbopensource.vercel.app/

[smikitky]

@jakubdrozdek That happened on our fork (Japanese), too. That dawidd6/action-download-artifact@v2 GitHub action tries to download "external" files (artifact) that had been generated by a workflow executed on the main branch. You got that error because no relevant workflow has been previously merged into the main. If I understand correctly, you can ignore that error and just merge the PR for now. Everything should be fine from the next PR.

[gaearon]

Do you know what's the problem? Is it required to pass?

Like @smikitky said, try without it passing and see if that resolves next time. I wouldn't worry about it for now.

And second question: where can we preview our translated website and what's the URL for the live Polish beta?

If you write a few pages I'll set up a project. Unfortunately it's manual so write here and we'll do it.

[smikitky]

The current pre-commit hook has the following two lines:

https://github.com/reactjs/reactjs.org/blob/4022f9774b8dd93d863fd6bca6447b1f03ae3979/beta/.husky/pre-commit#L5-L6

This may make sense on the main repo but makes no sense on translation forks. Every time I commit, I see many useless notices saying the explicit IDs are different from auto-generated ones.

https://github.com/reactjs/reactjs.org/blob/4022f9774b8dd93d863fd6bca6447b1f03ae3979/beta/scripts/generateHeadingIDs.js#L55-L57

What's worse, because of the unconditional git add -u, I accidentally committed and pushed a draft translation without knowing it. I think this process could be smarter and less confusing to new translators.

[gaearon]

@smikitky yeah this sounds confusing! do you have a fix in mind? how did this work before?

[hg-pyun]

@gaearon Is there a schedule for the official release of new documents? It would be nice to share roughly.

[smikitky]

@gaearon In the future, it would be nice to run pre-commit generate-ids only on the main repo. When it finds a heading without an explicit ID, it should reject the commit instead of unconditionally fixing it and committing it. Alternatively, it could auto-fix only the files to be committed, not all the files in the src directory.

But in the meantime, I think this pre-commit hook could be simply removed.

[harish-sethuraman]

When it finds a heading without an explicit ID, it should reject the commit instead of unconditionally fixing it and committing it.

We might have to write a custom hook for that will look into that.

But in the meantime, I think this pre-commit hook could be simply removed

Will remove it

[jakubdrozdek]

@gaearon Hey, I just finished translating the whole first chapter, and going on. Do you think it's enough to deploy the Polish beta docs now? 😉 https://github.com/reactjs/pl.reactjs.org/issues/287

[smikitky]

@gaearon Please set up the Japanese beta docs, too. Translations for several pages and MDX tags were merged into main.

[gaearon]

I actually just went on a vacation but I asked @rickhanlonii to find someone from the team to help with this. Ping me in twitter DM if there’s no progress in a week and I’ll double check.

[yepes]

I'd like to help with the Spanish translation. How can I get enrolled?

[rickhanlonii]

Just a heads up: we're going to be a bit delayed during React Conf this week. Thanks for your patience!

[dev-tom-0108]

Thanks so much

[rickhanlonii]

Sorry for the delay, Polish and Japanese docs are deployed here:

• https://pl-beta-reactjs-org.vercel.app/
• https://ja-beta-reactjs-org.vercel.app/

We're working to get the domains registered as well, will update when that's available.

[jakubdrozdek]

Sorry for the delay, Polish and Japanese docs are deployed here:

* https://pl-beta-reactjs-org.vercel.app/

* https://ja-beta-reactjs-org.vercel.app/

We're working to get the domains registered as well, will update when that's available.

Awesome! Thank you, that helps a lot :)

[rickhanlonii]

Heads up, the domains are now available:

• https://beta.pl.reactjs.org
• https://beta.ja.reactjs.org

[smikitky]

@gaearon Analyze bundle job still fails for every new PR made in translation forks. Looks like the cause is this (Line 57):

https://github.com/reactjs/reactjs.org/blob/c005fa4d7a2a0a602d6d538526699d7073ae3109/.github/workflows/analyze.yml#L53-L60

Line 57 refers to bundle_analysis_upload.yml, but this workflow file no longer exists (removed by 25ac9d0). Perhaps the CI is currently using some stale artifact that remains only in the main repository as the "base"?

EDIT: @jakubdrozdek "Analyze Bundle" keeps failing, so I investigated and found this problem. I believe there is a CI setup bug that doesn't surface on the main repository because an old artifact happens to exist and is used as a base.

EDIT: I confirmed recent actions for PRs on this repository were downloading the same artifact (RunID: 1429732265, Artifact: 111304536) even though the main branch has been changing frequently.

[smikitky]

I made a PR to fix the problem above: #4192

[arshadkazmi42]

hi @gaearon

For Hindi translation we have completed two pages, is it enough to get the hindi docs domain also setup?

https://github.com/reactjs/hi.reactjs.org/issues/168

[neighborhood999]

Hi @gaearon & @rickhanlonii , the zh-hant already finished three pages translation (check here), please help us to set up the beta page, Thanks!

Have a nice day!

[habarahonaa]

I'd like to help with the Spanish translation. How can I get enrolled?

I second this! Would love to be part of it though I'm not currently a translation repo maintainer. Have a nice day everyone and thanks :)

[gaearon]

I've added more pages to the list of things that are good to start translating. See updated list above.

[rickhanlonii]

Hey all, sorry for the delay! These are now up:

• beta.hi.reactjs.org
• beta.zh-hant.reactjs.org

[arshadkazmi42]

Hey all, sorry for the delay! These are now up:

• beta.hi.reactjs.org
• beta.zh-hant.reactjs.org

Thank you for setting this up @rickhanlonii :smile:

[arshadkazmi42]

@gaearon @rickhanlonii

Many test runs are failing for hindi translation repository on all PRs. Is there anything needs to be done there?

Here is a sample PR https://github.com/reactjs/hi.reactjs.org/pull/186#pullrequestreview-886811263

[gaearon]

@arshadkazmi42 Please don't merge code changes like https://github.com/reactjs/hi.reactjs.org/pull/186. Only do translation changes on your repo. All code changes should be done on the main repo. Otherwise you'll get out of sync.

[arshadkazmi42]

@gaearon Got it. will take care of that. Is this why the builds are failing? I have been merging these Bump PRs.