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 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/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 😃

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?

@leeyspaul

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.

@slorber

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

I could help with French, if needed.

@leeyspaul

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...

@slorber

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

I could help with spanish. This feature is a must

I can help you with Bengali

@slorber

Hi @slorber,
I'm highly interested in translating Docusaurus 2 website in Bengali 🙋‍♂️ and super excited to be assigned as a 🇧🇩 Bengali translator. ❤️

Thanks

@slorber

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

Thanks

I can translate Chinese and Spanish version of the doc. Do you need any help?^_^

Thanks, yes we'd be happy to improve on these languages

You don't need to ask, you can submit contributions here directly: https://crowdin.com/project/docusaurus-v2

Can we fix the BCP 47 language tag to use zh-Hans/zh-Hans-CN instead of zh-CN?

https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry

Thanks.

@winstonsung

@winstonsung Docusaurus site and other sites could configure this thanks to the i18n.<localeConfig>['zh-CN'].htmlLang = 'zh-Hans'

But from my understanding zh-CN is also a valid BCP 47 tag, and you'll find references to it in those docs:

Or perhaps a user would want to associate
requests for the range "zh-Hans" (Chinese as written in the
Simplified script) with content bearing the language tag "zh-CN"
(Chinese as used in China, where the Simplified script is
predominant).

We can study this more, but from my understanding, a BCP47 tag (like zh, present in your doc) remains perfectly valid if we add a region to it (-ZN).

Why do you think zh-CN is broken, and what would this change fix exactly?

Any opinion @Josh-Cena ?

If you think our HTML lang tag is wrong, we are not alone using it:

I didn't mean zh-CN is wrong/invalid, but it's not preferred as zh-CN was first being used when the script subtags were not being considered.

Android and MediaWiki both include the script subtag, and it's better for the definition (zh doesn't have the Suppress-Script field and is written in multiple scripts) and fallback.

https://android.googlesource.com/platform/frameworks/base/+/android15-release/core/res/res/values/locale_config.xml#612

https://developer.android.com/guide/topics/resources/app-languages

https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/core/+/refs/tags/1.43.1/includes/language/LanguageCode.php#136

Is there any option to translate it into Japanese?

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

hey I want to contribute translating the docs to spanish is it available to do it ?

Hello, I would love to help with the Turkish translation if needed. Let me know!

if possible, i would love to help in hindi translation.Let me know!

A kind reminder that you do not need to ask permission to start translating things on Crowdin

However, I'm not sure it's super useful anymore to translate sites manually. Most likely in the future, we will fully pre-translate sites with AI. Then you would only have to proofread and correct strings when the AI was wrong.

@slorber

@slorber yes exactly. We only need to do proofreading and cross check the translation done by AI.

Added Azerbaijani (az) default theme translations in #12370. Happy to help with the Crowdin side once the locale is enabled.

Hi! I would like to help translate the Docusaurus website into Indonesian (id). I have joined the Crowdin project and checked the existing locale files. I plan to start with the homepage, getting-started documentation, and default theme translations. Please let me know if this locale needs to be enabled or if there are any current translation guidelines I should follow.

Navigation Menu

Repository navigation

Help us translate the Docusaurus website #3526

Help us translate the Docusaurus 2 website

Translation process

Theme default translations

Existing language

New language

Use appropriate pluralization

Files to translate on Crowdin

Preview your translation work

Production

111 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Help us translate the Docusaurus website #3526

Description

Help us translate the Docusaurus 2 website

Translation process

Theme default translations

Existing language

New language

Use appropriate pluralization

Files to translate on Crowdin

Preview your translation work

Production

Activity

leeyspaul commented on Oct 10, 2020

slorber commented on Oct 12, 2020

leeyspaul commented on Oct 12, 2020

ArtFlag commented on Oct 14, 2020

slorber commented on Oct 14, 2020

leeyspaul commented on Oct 14, 2020

limkinZero commented on Oct 26, 2020

iamrubayet commented on Nov 13, 2020

shaonkabir8 commented on Jan 16, 2021

ayonious commented on Jan 27, 2021

111 remaining items

slorber commented on May 26, 2025

winstonsung commented on Jun 22, 2025

slorber commented on Jun 23, 2025

winstonsung commented on Jun 23, 2025

xeneize1212 commented on Nov 14, 2025

Roushan901 commented on Nov 18, 2025

tats-u commented on Nov 18, 2025

MateoLoz commented on Jan 17, 2026

alihanbays commented on Mar 29, 2026

Injora commented on Apr 2, 2026

slorber commented on Apr 2, 2026

tats-u commented on Apr 11, 2026

ankur0904 commented on May 2, 2026

OrkhanAbbasli commented on Aug 20, 2026

Zahid09987 commented on Oct 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions