It is easy to translate a Docusaurus website with its internationalization (i18n) support.
i18n is a new feature (released early 2021), please report any bug you find.
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:
The choice was made for 2 reasons:
- Description attribute: to help translators with additional context
- Widely supported: Chrome extensions, Crowdin, Transifex, Phrase, Applanga
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:
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: