Version: 2.0.0-alpha.71 🚧

i18n - Introduction

It is possible to translate a Docusaurus website through its internationalization support (abbreviated as i18n).

caution

i18n is a new feature (released early 2021), please report any bug you find.

Goals#

This section should help you understand the design decisions behind the Docusaurus i18n support.

For more context, you can read the initial RFC and PR.

i18n goals#

The goals of the Docusaurus i18n system are:

  • Simple: just put the translated files in the correct file-system location.
  • Flexible translation workflows: based on Git (monorepo, forks or submodules), SaaS software, FTP...
  • Flexible deployment options: single or multiple domains.
  • Modular: allow plugin author to provide i18n support.
  • Low-overhead runtime: static json/markdown content does not require a heavy i18n JS library.
  • Acceptable 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 the integration is possible.
  • Easy to use with Crowdin: multiple Docusaurus v1 sites use Crowdin, and should be able to migrate to v2.

i18n goals (TODO)#

Features that are not yet implemented:

  • Good SEO defaults: setting useful html meta headers like hreflang for you.
  • RTL support: one locale should not be harder to use than another.
  • Contextual translations: reduce friction to contribute to the translation effort.
  • Anchor links: linking should not break when you localize headings.
  • Advanced configuration options: customize route paths, file-system paths.

i18n non-goals#

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.

Translation workflow#

Overview#

Overview of the workflow to create a translated Docusaurus website:

  • Configure: declare the default locale and alternative locales in docusaurus.config.js.
  • Translate: put the translation files at the correct file-system location.
  • Deploy: build and deploy your site using a single or multi-domain strategy.

Translation files#

You will have to work with 2 kind of translation files.

Markdown 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 sentance as a separate string.

JSON files#

JSON is used to translate:

  • your React code: using the <Translate> component
  • your theme: the navbar, footer...
  • your plugins: the docs sidebar category labels...

The JSON format used is called Chrome i18n:

{
"myTranslationKey1": {
"message": "Translated message 1",
"description": "myTranslationKey1 is used on the homepage"
},
"myTranslationKey2": {
"message": "Translated message 2",
"description": "myTranslationKey2 is used on the FAQ page"
}
}

The choice was made for 2 reasons:

Translation files location#

The translation files should be created at the correct file-system location.

Each locale and plugin has its own i18n subfolder:

website/i18n/<locale>/<pluginName>/...
note

For multi-instance plugins, the path is website/i18n/<locale>/<pluginName>-<pluginId>/....

Translating a very simple Docusaurus site in French would lead to the following tree:

website/i18n
└── fr
β”œβ”€β”€ code.json
β”‚
β”œβ”€β”€ docusaurus-plugin-content-blog
β”‚Β Β  └── 2020-01-01-hello.md
β”‚
β”œβ”€β”€ docusaurus-plugin-content-docs
β”‚Β Β  β”œβ”€β”€ current #
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ doc1.md
β”‚Β Β  β”‚Β Β  └── doc2.mdx
β”‚Β Β  └── current.json
β”‚
└── docusaurus-theme-classic
β”œβ”€β”€ footer.json
└── navbar.json

The JSON files are initialized with the docusaurus write-translations CLI command.

The code.json file is extracted from React components using the <Translate> api.

info

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:

Last updated on by slorber