Help us translate the Docusaurus website

slorber commented 4 years ago

Last updated: 05/10/2023

Help us translate the Docusaurus 2 website

The Docusaurus 2 i18n support is ready, and it's time for Docusaurus 2 website to be translated

This issue is here to organize the translation effort.

Translation process

Get familiar with the Docusaurus i18n support
Make sure the theme default translations exist for your language.
Sign-up on Crowdin and join the Docusaurus-v2 project
Get familiar with the Crowdin translation UI, as you will need to use it to translate JSON and Markdown files
Ask for your locale to be enabled on Crowdin
Translate the content

Theme default translations

The classic theme ships with some default translation bundles for theme labels, like "next" / "previous" pagination buttons...

Please help us provide/complete/double-check the default theme label translations for your own language: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations/locales

Existing language

If your language already exists in the folder above, please edit the files with completed or more accurate translations.

New language

If your language does not exist, you will need to create it from scratch.

You have 2 options:

Automated: run CLI: yarn workspace @docusaurus/theme-translations update <newLanguage> (more info here)
Manual: just copy the base/**.json file as <newLanguage>/**.json, and remove the ___DESCRIPTION attributes.

In most cases, use a simple language code like fr or es for <newLanguage>, and use locales such as pt-BR and pt-PT when the difference between the 2 variants is strong enough.

Use appropriate pluralization

Note: some languages have complex plural rules. Make sure the pluralized labels (containing a |) contain as many variants as your locale has plural rules (number of cardinal categories).

English, 2 plural forms: "One post|{count} posts"
Slavic languages, 4 plural forms: "One post|Few posts|Many posts|{count} posts"

Run this code in your browser to obtain the plural forms of any locale/language:

function getLocalePluralForms(locale) {
  const AllPluralForms = ['zero','one','two','few','many','other']
  const pluralCategories = new Intl.PluralRules(locale).resolvedOptions().pluralCategories;
  pluralCategories.sort((c1,c2) => AllPluralForms.indexOf(c1) > AllPluralForms.indexOf(c2) ? 1 : -1);
  return pluralCategories;
}

const myLocale = "fr"; // Change this variable!
console.log("Plural forms for this locale are =>>> ",getLocalePluralForms(myLocale));

Note: the order of plural forms in the translation string matters.

Files to translate on Crowdin

Please translate in priority:

The website/i18n/en files (layout/homepage JSON files)
The website/community md files
The website/docs md files
The Intro / Getting Started / Guides is more important compared to Advanced Guides / Migration / API

Please be careful for:

Admonitions: :::tip (and other admonition keys) should not be translated, but :::tip myTitle should be translated as :::tip myTranslatedTitle

Please do not translate for now:

Versioned docs
Frontmatter such as id, slug, URLs...
Code blocks
JSX syntax in MDX docs

Preview your translation work

Unfortunately, it is not possible for you to test the translated site locally (the Crowdin auth system is not very flexible)

If you are actively working on a locale, please ask to add that locale to our i18n staging deployment:

Preview: https://docusaurus-i18n-staging.netlify.app/
Netlify build status:
Netlify build logs: https://app.netlify.com/sites/docusaurus-i18n-staging/deploys
Trigger a build: curl -X POST -d {} https://api.netlify.com/build_hooks/602511032ce0923d1b6cd220 (manually for now)

Please translate at least 10% before asking for enabling your locale in this staging deployment.

Production

We ask for a minimal amount of translations to be reached:

website/i18n/en > 90%
website/community > 40%
website/docs > 20%

Once a locale has enough translations, and the preview looks good on the i18n staging environment, we'll add it to our production site.

Thanks for your help 😃

leeyspaul commented 3 years ago

I'm interested in helping out with the translation efforts for i18n! Would you be able to put more information here on what that would look like for interested folks?

slorber commented 3 years ago

Thanks @leeyspaul. In which language are you able to translate?

Basically, the work would be to use Crowdin and translate:

a file of layout key/value pairs
whole markdown documents

Very similar to v1 translation process. To get familiar with it, you can join the v1 translation project here: https://crowdin.com/project/docusaurus and submit a few translation proposals.

leeyspaul commented 3 years ago

@slorber I'd be able to contribute in Spanish and maybe in Korean in the future. But for now I'd like to start with Spanish. I'll check out the links and ask any questions through the discord channel. Would it be helpful for perhaps new folks looking to contribute to have a page on the localization process? Perhaps a new issue could be opened up on that.

ArtFlag commented 3 years ago

I could help with French, if needed.

slorber commented 3 years ago

Thanks. I'm French so would be able to translate it in French but still help is welcome 👍

@leeyspaul the localization process does not exist yet. We'll actually write it from practical experience traducting the Docusaurus site. There are multiple things to figure out, including Crowdin recommended settings etc...

leeyspaul commented 3 years ago

Totally! Happy to help brainstorm with a proposal of sorts if you're looking to do that. @slorber

limkinZero commented 3 years ago

I could help with spanish. This feature is a must

iamrubayet commented 3 years ago

I can help you with Bengali

shaonkabir8 commented 3 years ago

Hi @slorber, I'm highly interested in translating Docusaurus 2 website in Bengali :raising_hand_man: and super excited to be assigned as a :bangladesh: Bengali translator. :heart:

Thanks

ayonious commented 3 years ago

@slorber Im happy to help with German translations. Already signed up in Crowdin. I dont see any German folder to start from.

Thanks

slorber commented 3 years ago

Thanks everyone,

I've just enabled German, Spanish and Bengali on Crowdin.

@shaonkabir8 @iamrubayet I've enabled Bengali too, but there are 2 options so let me know if I didn't select the best one:

f0rb1d commented 3 years ago

Can help with Simplified Chinese (zh-cn) translation here.

slorber commented 3 years ago

Thanks @f0rb1d , just enabled it: https://crowdin.com/project/docusaurus-v2/zh-CN

mrcsvg commented 3 years ago

Hello! Greetings from Brazil!

Portuguese (pt-br) is not in the list but I would be really happy to help translating it!

"How much can you translate (in % of the whole documentation)."

That will depend, but for sure I can get more people for help and have it in 100%.

slorber commented 3 years ago

Thanks, enabled :) https://crowdin.com/project/docusaurus-v2/pt-BR

murleo commented 3 years ago

@slorber I am happy to help with Ukrainian translation. Thanks.

slorber commented 3 years ago

Thanks :)

https://crowdin.com/project/docusaurus-v2/uk

f0rb1d commented 3 years ago

@slorber Hi there. Lots of content have been translated since I commented. I want to see preview and adjust translations based it. Could you please also enable the language on the website? Thank you in advance.

slorber commented 3 years ago

Hi @f0rb1d

Unfortunately, I don't see much content that has been translated so far. https://crowdin.com/project/docusaurus-v2

I think we don't want to put online translations that are mostly incomplete, but rather have a minimum threshold to put the translated site online, maybe around 30%, and ensure at least the homepage + introduction pages are fully translated?

About the preview, unfortunately, you can't have it easily locally because afaik Crowdin only allow project managers to download the translations through their cli, and I can't create any read-only/project-specific API key that I can securely share.

If someone is actively working on translations and want to have previews, just ask after at least 5%/10% of translations have been done, and I'll add such locales to a separate i18n work-in-progress deployment

Ningensei848 commented 3 years ago

@slorber Hi ! 👋 Greetings from Japan 🗻 🗾 🏯 👺

I couldn't find the Japanese folder, so I will help you with the translation as soon as the subfolder is added.

p.s. I found that the Japanese folder exists in the v1 project. I'm going to practice using CrowdIn a bit there until a new folder is created in the v2 project.

slorber commented 3 years ago

@Ningensei848 I've enabled japanese here: https://crowdin.com/project/docusaurus-v2/ja

noworneverev commented 3 years ago

Hi @slorber, I can help with Traditional Chinese (zh-hant). Thanks.

slorber commented 3 years ago

Thanks: https://crowdin.com/project/docusaurus-v2/zh-TW

f0rb1d commented 3 years ago

Hi @slorber,

I think the progress shown in the screenshot isn't correct, as the project contains 'Versioned docs' mentioned above which takes up a big part of it. Also, a little suggestion here, maybe we can add a feature to automatically fetch and deploy translations per day/week and deploy them? This may be done via GitHub Actions or Netlify plugins.

Last, I think it is a good idea to put thresholds on the process. I've already translated more than homepage + introduction, so please add it to i18n branch. Thank you in advance <3

slorber commented 3 years ago

I think the progress shown in the screenshot isn't correct, as the project contains 'Versioned docs' mentioned above which takes up a big part of it.

0% is 0% no matter the versioning system.

We also use the "hide duplicates strings" feature from crowdin so if 2 versions are similar strings aren't counted multiple times. So when you see "5%" Chinese, it's pretty accurate of the amount translated of upstream docs, just a little bit lower (at least in our case as versions are quite similar).

Also, a little suggestion here, maybe we can add a feature to automatically fetch and deploy translations per day/week and deploy them? This may be done via GitHub Actions or Netlify plugins.

Translations are already fetched whenever code is merged on master. We just don't trigger builds on translation changes, that feels not necessary as the project is active enough to trigger at least a build per day.

Last, I think it is a good idea to put thresholds on the process. I've already translated more than homepage + introduction, so please add it to i18n branch. Thank you in advance <3

Thanks, will review that and try to get a deployment soon, but I'd rather have a bit more of ./docs be translated ;)

slorber commented 3 years ago

I've set up a preview deployment for staging locales. Will add any locale for which there is active translation work going on. For now I just added zh-CN.

Preview: https://docusaurus-i18n-staging.netlify.app/
Netlify site: https://app.netlify.com/sites/docusaurus-i18n-staging
Trigger a build: curl -X POST -d {} https://api.netlify.com/build_hooks/602511032ce0923d1b6cd220

I did not automate the triggering of a build because Crowdin webhooks are not throttled. It feels a bit unnecessary to trigger a build every time there's a new translated string, so for now it's your responsibility to trigger it.

slorber commented 3 years ago

FYI the classic theme also ships with some default translation bundles for theme labels, like "next" / "previous" pagination buttons etc...

If you. want to help, please create a similar translation bundle for your language.

You can just copy this file and localize the messages: https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-theme-classic/codeTranslations/fr.json

eshkaflex commented 3 years ago

Hello! I can help with Russian Language.

slorber commented 3 years ago

Russian enabled :) https://crowdin.com/project/docusaurus-v2/ru

I've re-enabled the top30 Crowdin locales, that will be simpler as your locale is more likely to already be enabled.

felipecespedes commented 3 years ago

Can help with Spanish of Latin America

slorber commented 3 years ago

FYI it's now possible to translate the MDX files, as Crowdin added support for the .mdx extension. Just, please don't translate the JSX syntax in the MDX documents

slorber commented 3 years ago

Hi!

FYI I enabled "ko" and "ja" locales on staging!

https://docusaurus-i18n-staging.netlify.app/

alstn2468 commented 3 years ago

`themeClassic/codeTranslations/ko.json` has a comma at the end.

Flow

yarn install
yarn start -- --locale ko

Error Message

$ docusaurus start --locale ko
Starting the development server...
SyntaxError: Unexpected token } in JSON at position 2841
    at JSON.parse (<anonymous>)
    at readDefaultCodeTranslationMessages (/Users/minsu/Documents/React/Recoil/docs/node_modules/@docusaurus/utils/lib/index.js:494:25)
    at async Promise.all (index 4)
    at async Object.getPluginsDefaultCodeTranslationMessages (/Users/minsu/Documents/React/Recoil/docs/node_modules/@docusaurus/core/lib/server/translations/translations.js:189:29)
    at async Object.load (/Users/minsu/Documents/React/Recoil/docs/node_modules/@docusaurus/core/lib/server/index.js:189:76)
    at async start (/Users/minsu/Documents/React/Recoil/docs/node_modules/@docusaurus/core/lib/commands/start.js:45:19)

There is no problem with the original file. Why do these things happen?

slorber commented 3 years ago

@alstn2468 this was a mistake that has been fixed already but is not released yet (next week, you can try to use @canary in the meantime). I've setup unit tests so that it does not happen again.

alstn2468 commented 3 years ago

@slorber Thank you for your quick reply.

f0rb1d commented 3 years ago

@slorber Just FYI, the Simplified Chinese translation has already reached the minimum translation requirement. You might want to have a peek on the staging site and deploy it to production if it looks good.

BTW, there is an extra space between two translation strings on the staging site, which doesn't exist on previous builds. It might look better if we get rid of it.

Also, there are some special strings were translated which fail builds on Netlify.

slorber commented 3 years ago

Thanks for your work everyone, we now have good progress in fr, ko and zh-CN!

As requested by @f0rb1d , fixed some issues + I'm enabling ko + zh-CN in production with https://github.com/facebook/docusaurus/pull/4599

yuxxeun commented 3 years ago

Hey! I can help with Bahasa which is Indonesian language.

slorber commented 3 years ago

Thanks @yuxxeun , you can submit your translations here already: https://crowdin.com/project/docusaurus-v2/id

TomPeirs commented 3 years ago

Please do not translate for now: Versioned docs Frontmatter such as id, slug, URLs... Code blocks Admonitions JSX syntax in MDX docs

I have a question, I noticed in the crodwin docs files the Admonitions were simply appended A (french) Title. Will there be a .json which interprets admonitions and translates the titles? Because Docusaurus supports remark-admonitions, should it then be docusaurus whom interprets the translation rather then the user who translates it in their Docs?

Otherwise we'll need to write a script to translate the titles of markdown admonitions. (we have 1700 files which might potentially have admonitions ;-) )

slorber commented 3 years ago

Will there be a .json which interprets admonitions and translates the titles?

The md content is translated as a whole, and it's a bit complicated to handle such things unfortunately.

What I mean here is that you should not translate the admonition markers.

This is wrong

- :::caution
+ :::attention

But this is a legit translation:

- :::caution Be careful
+ :::caution Faites attention

Unfortunately, I don't think tooling like Crowdin will help much, as each admonition with title will be displayed as a unique string (unlike a :::tip that can be marked as hidden string), so translators must remain careful for admonitions with titles.

slorber commented 3 years ago

Actually, I think our admonitions plugin hardcode some admonition titles when there is no title, this is probably why @forresst added french titles after the admonition to make sure the default admonition title is translated on the french site:

Reported here: https://github.com/facebook/docusaurus/issues/4542#issuecomment-832898463

TomPeirs commented 3 years ago

Actually, I think our admonitions plugin hardcode some admonition titles when there is no title, this is probably why @forresst added french titles after the admonition to make sure the default admonition title is translated on the french site:

Reported here: #4542

Good to know, in this case we will take the same approach :-)

forresst commented 3 years ago

Actually, I think our admonitions plugin hardcode some admonition titles when there is no title, this is probably why @forresst added french titles after the admonition to make sure the default admonition title is translated on the french site:

Reported here: #4542 (comment)

It is exactly that, it is the only trick that I found to have a translation in French

Neilblaze commented 3 years ago

Thanks everyone,

I've just enabled German, Spanish and Bengali on Crowdin.

@shaonkabir8 @iamrubayet I've enabled Bengali too, but there are 2 options so let me know if I didn't select the best one:

is this still available for grabs? @slorber If yes, then I would like to take it :)

slorber commented 3 years ago

@Neilblaze thanks, you don't need to ask, you can directly follow the instructions of this issue, register to Crowdin and submit translations here: https://crowdin.com/project/docusaurus-v2/bn#

slorber commented 3 years ago

Hi there!

Docusaurus has a new mobile nav UX in beta.4! (https://github.com/facebook/docusaurus/pull/4273)

There are 2 new labels to translate, can you help and submit translation PRs, please?

https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations

  "theme.TOCCollapsible.toggleButtonLabel": "On this page",
  "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": "← Back to main menu",

MrPand-21 commented 3 years ago

Hello, I want to help with Turkish translation. Okay? or am i late?

slorber commented 3 years ago

Thanks @MrPand-21

You don't need to ask any permission for submitting translations: just go there and submit your translations directly: https://crowdin.com/project/docusaurus-v2/tr#

rafaelbmateus commented 3 years ago

Hello @slorber, pt-BR in 59% and counting...

I triiger a build on staging env a few minutes ago, using curl -X POST -d {} https://api.netlify.com/build_hooks/602511032ce0923d1b6cd220.

I'll keep my eye on https://docusaurus-i18n-staging.netlify.app/ to check the changes.

Thanks for now!

facebook / docusaurus