Help us translate the Docusaurus 2 website

[slorber]

Last updated: 20/11/2021

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:
• 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

[cuberleon]

@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

[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

[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 🔍 a country can be for translations 😉

[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 (#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)

[CarlosMarinAquino]

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

[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?