Help us translate the Docusaurus website

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](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations/locales) exist for your language.
- Sign-up on [Crowdin](https://crowdin.com/) and join the [Docusaurus-v2](https://crowdin.com/project/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 ` ([more info here](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations))
- **Manual**: just copy the `base/**.json` file as `/**.json`, and remove the `___DESCRIPTION` attributes.

In most cases, use a simple language code like `fr` or `es` for ``, 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](https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html) (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:

```js
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: [](https://app.netlify.com/sites/docusaurus-i18n-staging/deploys)
- 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/67e11ff9b02eaa60ad565e2c` (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 😃