It is easy to translate a Docusaurus website with its internationalization (i18n) support.
It is important to understand the design decisions behind the Docusaurus i18n support.
The goals of the Docusaurus i18n system are:
- Simple: just put the translated files in the correct filesystem location
- Flexible translation workflows: use Git (monorepo, forks, or submodules), SaaS software, FTP
- Flexible deployment options: single, multiple domains, or hybrid
- Modular: allow plugin authors to provide i18n support
- Low-overhead runtime: documentation is mostly static and does not require a heavy JS library or polyfills
- Scalable build-times: allow building and deploying localized sites independently
- Localize assets: an image of your site might contain text that should be translated
- No coupling: not forced to use any SaaS, yet integrations are possible
- Easy to use with Crowdin: multiple Docusaurus v1 sites use Crowdin, and should be able to migrate to v2
- Good SEO defaults: we set useful SEO headers like
- RTL support: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement
- Default translations: classic theme labels are translated for you in many languages
We don't provide support for:
- Automatic locale detection: opinionated, and best done on the server
- Translation SaaS software: you are responsible to understand the external tools of your choice
- Translation of slugs: technically complicated, little SEO value
Overview of the workflow to create a translated Docusaurus website:
- Configure: declare the default locale and alternative locales in
- Translate: put the translation files at the correct filesystem location
- Deploy: build and deploy your site using a single or multi-domain strategy
You will have to work with 2 kind of translation files.
This is the main content of your Docusaurus website.
Markdown and MDX documents are translated as a whole, to fully preserve the translation context, instead of splitting each sentence as a separate string.
JSON is used to translate:
- your React code: using the
- your theme: the navbar, footer
- your plugins: the docs sidebar category labels
The JSON format used is called Chrome i18n:
"message": "Translated message 1",
"description": "myTranslationKey1 is used on the homepage"
"message": "Translated message 2",
"description": "myTranslationKey2 is used on the FAQ page"
The choice was made for 2 reasons:
- Description attribute: to help translators with additional context
- Widely supported: Chrome extensions, Crowdin, Transifex, Phrase, Applanga
Translation files location
The translation files should be created at the correct filesystem location.
Each locale and plugin has its own
For multi-instance plugins, the path is
Translating a very simple Docusaurus site in French would lead to the following tree:
│ └── 2020-01-01-hello.md
│ ├── current #
│ │ ├── doc1.md
│ │ └── doc2.mdx
│ └── current.json
The JSON files are initialized with the
docusaurus write-translations CLI command.
code.json file is extracted from React components using the
Notice that the
docusaurus-plugin-content-docs plugin has a
current subfolder and a
current.json file, useful for the docs versioning feature.
Each content plugin or theme is different, and define its own translation files location: