跳转至主内容
Version: 2.0.0-beta.0

i18n - 简介

您可以使用自带的国际化 (i18n) 支持来轻松翻译 Docusaurus 网站

目标#

了解 Docusaurus i18n 支持背后的设计决策是极为重要的。

要了解来龙去脉,您可阅读原始的 RFC合并请求提案。

i18n 目标#

Docusaurus i18n 系统旨在:

  • Simple: just put the translated files in the correct filesystem location
  • 弹性翻译流程:可使用 Git (单仓库、派生或子模块)、SaaS 软件或 FTP
  • 弹性部署选项:可部署于单个、多个域名或混合部署
  • 模块化:插件可提供 i18n 支持
  • 快速运行时:文档多为静态,无需重量级的 JS 库或 Polyfill
  • 伸缩构建:允许独立构建及部署本地化内容网站
  • 本地化资源:您网站上的图像可被翻译
  • 无耦合:不强制使用任何 SaaS,但您可自己集成
  • Easy to use with Crowdin: multiple Docusaurus v1 sites use Crowdin, and should be able to migrate to v2
  • 优秀的 SEO 默认值:我们已为您预先设置有用的 SEO 页眉数据(如 hreflang
  • RTL 支持:支持并轻松实现自右向左阅读的语言(阿拉伯语、以色列语等)
  • 默认译文:经典主题的标签已为您翻译成多种语言

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

翻译流程#

概览#

Overview of the workflow to create a translated Docusaurus website:

  1. 配置:在 docusaurus.config.js 中声明默认及备选语言
  2. Translate: put the translation files at the correct filesystem location
  3. 部署:使用单域名或多域名策略构建并部署您的站点

翻译文件#

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

Markdown 文件#

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:

翻译文件位置#

The translation files should be created at the correct filesystem 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: