Help us translate the Docusaurus 2 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.

• 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 🙋‍♂️ and super excited to be assigned as a 🇧🇩 Bengali translator. ❤️

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

[SilverTee]

I want to collab in the Spanish version, did you have one branch for this language?

you could do this here:
https://crowdin.com/project/docusaurus-v2/es-ES

[shawshankkumar]

Hey @slorber is there a chance https://docusaurus-i18n-staging.netlify.app/ this isn't auto updating? because I don's see a few things on the production link here. Also, I'd like to contribute to Hindi, anything I should be aware of?

[slorber]

There's a section in our "Preview your translation work" that explains how this preview work. It is supposed to be up to date (but sometimes fail, not a big deal). Last successful publish was yesterday. I don't know what you are looking for that you don't find so it's hard to say if there's a problem or not.

Nothing particular to do to contribute to Hindi apart reading the docs. If you have any question left after reading that doc and giving it a try, I'll answer them.

[shawshankkumar]

Thanks I'll give it a try!

…

On Thu, Dec 15, 2022 at 8:34 PM Sébastien Lorber ***@***.***> wrote: There's a section in our "Preview your translation work" that explains how this preview work. It is supposed to be up to date (but sometimes fail, not a big deal). Last successful publish was yesterday. I don't know what you are looking for that you don't find so it's hard to say if there's a problem or not. Nothing particular to do to contribute to Hindi apart reading the docs. If you have any question left after reading that doc and giving it a try, I'll answer them. — Reply to this email directly, view it on GitHub <#3526 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AR22P3MZMNWXKPK2QWB2R4DWNMXPTANCNFSM4SBW5NKQ> . You are receiving this because you commented.Message ID: ***@***.***>

[kgolubic]

@slorber I'd like to help with the translation of localization and translation of Docusarus to Croatian. It is not available as theme default translations at the moment. What can be done so that I can start with the translation process?

[slorber]

@kgolubic I've clarified the instructions, to create a new theme language in the issue. We have a CLI for that. Please let me know if anything is still unclear.

[slorber]

We are experiencing some issues with Crowdin for all newly uploaded .mdx files.

Notably, the newly released version 2.4.0 has lost its previously existing translations

I hope we'll be able to fix this soon with Crowdin support.

In the meantime, it's probably not worth investing your time in translating these new strings from v2.4.

More info here: #8821

[tyzion]

hey italian guy here!
Could help with italian translation!

[tats-u]

Japanese now meets all the criteria.

P.S.
Can't we translate the banner string "⭐️ If you like Docusaurus, give it a star on GitHub and follow us on Twitter" at the top of each page?

[slorber]

Thanks for your work on this @tats-u

Due to recent changes on Crowdin and Netlify I have to adjust a bit our translation workflows and versioning archive procedure, so it's not a great timing right now to enable a new language, but we'll do this when I figure it out.

[CarlosMarinAquino]

Recently I was working in the Spanish version but I can understand how the platform works in some strings shows 1/2 and then turns into 1/163.
I attending the transition as long I can

[slorber]

some strings shows 1/2 and then turns into 1/163.

@CarlosMarinAquino I don't understand what you mean here 😅 screenshot?

[Zubiii333]

I'm working on Bangla localization. Could you please let me know how do I push the changes to test app? @slorber

[slorber]

@Zubiii333 by Bangla you mean Bengali / bn right?

As explained in the intro post, you can't test it locally, and we ask you to first translate at least 10% on Crowdin before turning your local on in our preview environment. Currently Bengali is at 0% translated: https://crowdin.com/project/docusaurus-v2/bn

[tats-u]

The build of https://docusaurus-i18n-staging.netlify.app/ has been broken for a long time, hasn't it?

[yuxxeun]

The build of https://docusaurus-i18n-staging.netlify.app/ has been broken for a long time, hasn't it?

it seems working-well currently, i've visiting it by now

[tats-u]

@yuxxeun
It's too old. The latest version there is RC of 2.0.
It shows the build has failed for a very long time.
If it succeeded, the latest version there would be much newer (e.g. 2.4.x).

[slorber]

The build of docusaurus-i18n-staging.netlify.app has been broken

Yes.

Fixing an issue that prevents the build to even start:
#9374

for a long time, hasn't it?

What's the point here?

The build logs are public: https://app.netlify.com/sites/docusaurus-i18n-staging/deploys

The project is open-source and you can submit a PR or translation fixes if you see it failing, or kindly report them if we didn't notice.

Even with my PR above, I'm not sure it will fix every issues, we'll see.
It's not my top priority to fix this deployment right now: shipping v3 is way more important.

---

Edit, apparently no translation problem and i18n staging is now able to build again:
https://docusaurus-i18n-staging.netlify.app/

[tats-u]

@slorber It's just because it was too difficult and expected to take too much time for me to specify the trouble spot from the error logs. I never expected that spot to be the culprit. Thanks a lot for fixing the issue on behalf of me.

[tats-u]

Some languages are better translated than Japanese. How about adding them to the staging site?

[slorber]

Some languages are better translated than Japanese. How about adding them to the staging site?

There's a cost for me to adding any language in terms of maintenance (when i18n staging is blocked due to a bad translation, happens often and hard to debug) and adding languages can also add time to the CI builds (and we are already close to the max build time on Netlify).

Unless they request it, until I find a solution to these problems I am cautious when adding new languages, in both prod and staging.

For example if I release v3.0, I don't want the prod deployment to be stuck due to having added a new language in staging just before. This is the kind of risk we encounter right now with the current setup.

[paraskevasleivadaros]

I am excited to inform you that I have commenced work on the Greek translation for the project. I will be actively updating my progress on Crowdin and look forward to contributing to making Docusaurus more accessible to Greek-speaking users. I'll provide updates and reach out if I encounter any issues or need further guidance!