Help us translate the Docusaurus website

[slorber]

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]

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]

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]

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

I could help with French, if needed.

[slorber]

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]

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

[limkinZero]

I could help with spanish. This feature is a must

[iamrubayet]

I can help you with Bengali

[shaonkabir8]

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]

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

Thanks

[slorber]

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]

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

[slorber]

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

[mrcsvg]

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]

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

[murleo]

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

[slorber]

Thanks :)

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

[f0rb1d]

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

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]

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

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

[noworneverev]

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

[slorber]

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

[f0rb1d]

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]

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]

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]

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]

Hello! I can help with Russian Language.

[slorber]

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]

Can help with Spanish of Latin America

[slorber]

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]

Hi!

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

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

[alstn2468]

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

Flow

1. yarn install
2. 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]

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

@slorber Thank you for your quick reply.

[f0rb1d]

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

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]

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

[slorber]

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

[TomPeirs]

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]

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]

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]

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]

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]

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]

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

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]

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

[yokymia]

Thank you so much

[slorber]

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]

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!

[slorber]

Thanks a lot @rafaelbmateus ! I'll enable the pt-BR locale in our staging env asap, just busy finishing things for a release but it will be done very soon!

[massoudmaboudi]

@slorber @lex111 I would appreciate it if you could enable Farsi (fa-IR) translation to start the translation. Please consider that when a user chooses to use Farsi, the style should also change from LTR to RTL.

[slorber]

Thanks @massoudmaboudi , just enabled Farsi here: https://crowdin.com/project/docusaurus-v2/fa Will enable it on our staging env once 10% translations were submitted.

Please consider that when a user chooses to use Farsi, the style should also change from LTR to RTL.

Yes, this is applied automatically by Docusaurus as Intl apis can tell us language direction for a language/locale code.

[massoudmaboudi]

Thanks @massoudmaboudi , just enabled Farsi here: https://crowdin.com/project/docusaurus-v2/fa Will enable it on our staging env once 10% translations were submitted.

Please consider that when a user chooses to use Farsi, the style should also change from LTR to RTL.

Yes, this is applied automatically by Docusaurus as Intl apis can tell us language direction for a language/locale code.

Thank you @slorber. I will inform you when the translation happens.

[slorber]

We have merged 2 new translation keys (in https://github.com/facebook/docusaurus/pull/3646, feature visible here: https://docusaurus.io/tests/docs/)

Please help us translate those new keys:

"theme.docs.tagDocListPageTitle": "{nDocsTagged} with \"{tagName}\"",
"theme.docs.tagDocListPageTitle___DESCRIPTION": "The title of the page for a docs tag",

"theme.docs.tagDocListPageTitle.nDocsTagged": "One doc tagged|{count} docs tagged",
"theme.docs.tagDocListPageTitle.nDocsTagged___DESCRIPTION": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)",

[supernover]

i would like to help out,if you could enable Kinyarwanda (eng-ki) thanks!

[slorber]

Thanks @supernover , enabled it here: https://crowdin.com/project/docusaurus-v2/rw

[hanancs]

Hi @slorber, I can help with Tamil. Thanks

[slorber]

Thanks, Tamil is now enabled @hanancs https://crowdin.com/project/docusaurus-v2/ta

[caleeli]

Hi! I can help with Spanish translations.

[MrTechHunter]

Hey! I can help with Persian/Farsi which is Iranian language.

[lex111]

For those who want to contribute with code, you can help translate our classic theme by adding new or improving existing translation. For more details, please see this section https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/codeTranslations#for-docusaurus-users

[MrTechHunter]

Hey mate @lex111 This is my PR: https://github.com/facebook/docusaurus/pull/5640

Sincerely, Mahdi Hamldar

[uguraktas]

hey, @slorber I am happy to help with Turkish translation.

[slorber]

Thanks @uguraktas

It's not necessary to tell us there, you can directly submit your translations on Crowdin (https://crowdin.com/project/docusaurus-v2/tr) and I'll enable a Turkish site once enough translations have been submitted

[jrmejiaa]

Hi @slorber I would like to help with Spanish, I saw that there are just 4% of the page translated. However, I don't have much time, so could you tell me which pages are the more important ones in order to have a first Spanish version of docusaurus?

[slorber]

FYI the default theme translations have been moved to a new package: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations

I edited the issue to reflect this change

[slorber]

@jrmejiaa this issue is up-to-date and all the relevant info are displayed at the top. Unfortunately navigating a i18n site that is only half translated is not very nice for the users. If we could get at least the getting started + guides in Spanish, that would be nice

[noomorph]

• ~Slave~ languages, 4 plural forms: "One post|Few posts|Many posts|{count} posts"

It is rude and unpleasant to see. 🤦‍♂️ Please fix to Slavic whenever you can.

[ss-o]

Hey @slorber,

I recently adopted Docusaurus for my projects. While having the learning curve I can kick off Lithuanian translations, at the same time would be a great practice for me. If there are no limits on how small :mag: a country can be for translations :wink:

[slorber]

Thanks @ss-o 👍 , you can now translate our site to lt here: https://crowdin.com/project/docusaurus-v2/lt

[zixuan945]

Some snippets like <code>'light' \| 'dark'</code> is not escaped correctly and becomes garbage characters on the pages in other languages, looking like ! !crwdBlockTags_299_sgaTkcolBdwrc!!!

[Josh-Cena]

@zixuan945 This is a known bug with Crowdin. See #5602

[slorber]

Admonition default titles are now translatable (https://github.com/facebook/docusaurus/pull/7556) (canary or next release)

Please help us and provide the missing admonition translations for your language: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations/locales

(tip: also provide all the other missing translations at the same time)