docusaurus/website/docs/i18n/i18n-introduction.md

id	title	sidebar_label	slug
introduction	i18n - Introduction	Introduction	/i18n/introduction

It is easy to translate a Docusaurus website with its internationalization (i18n) support.

:::caution

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

:::

Goals

It is important to 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: documentation is mostly static and does not require a heavy JS library or polyfills.
• 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.
• Good SEO defaults: setting useful SEO headers like hreflang for you.
• RTL support: locales reading right-to-left (Arabic, Hebrew...) should be easy to use.
• Default translations: theme labels are translated for you in many languages.

i18n goals (TODO)

Features that are not yet implemented:

• 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 sentence 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:

• 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 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:

• Docs i18n
• Blog i18n
• Pages i18n
• Themes i18n