版本：3.9.2

i18n - 简介

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.

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

i18n 目标

Docusaurus i18n 系统旨在：

简单易懂：将翻译过的文件放在正确的文件系统位置即可
灵活翻译流程：可以使用 Git（monorepo、fork、子模块）、SaaS 软件、FTP，等等
灵活部署选择：可以部署于单个、多个域名，或混合部署
模块化：插件作者也可提供国际化支持
轻量运行时：文档大多数内容都是静态的，无需重量级的 JS 库或 Polyfill
构建时间可控：允许独立构建并部署本地化内容网站
本地化资源：你的网站上的图像可被翻译
无耦合：不强制使用任何 SaaS，但你可以自己集成
轻松搭配 Crowdin：许多 Docusaurus v1 网站使用 Crowdin，它们都可以迁移至 v2
不错的 SEO 默认配置：我们为你设置了有用的 SEO 标头，类似 hreflang
RTL 支持：从右往左读的的本地化阅读方式（阿拉伯语、希伯来语等）被支持并易于实现
Default translations: classic theme labels are translated for you in many languages

i18n 非目标

我们不支持：

Automatic locale detection: opinionated, and best done on the server (your hosting provider)
Translation SaaS software: you are responsible to understand the external tools of your choice
Translation of slugs: technically complicated, little SEO value

翻译流程

概览

以下是创建翻译版 Docusaurus 站点的主要流程：

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

翻译文件

你会和三种翻译文件打交道。

Markdown 文件

这是你的 Docusaurus 网站的主要内容。

Markdown 和 MDX 文档会被统一翻译，而不会把每个句子分割成独立的字符串，以保证翻译语境正确。

JSON 文件

JSON 用于翻译：

Your React code: standalone React pages in src/pages, or other components
Layout labels provided through themeConfig: navbar, footer
通过插件选项提供的布局文本：文档侧边栏菜单标签，博客侧边栏标题等

The JSON format used is called Chrome i18n:

{
  "myTranslationKey1": {
    "message": "已翻译的信息 1",
    "description": "myTranslationKey1 用于主页"
  },
  "myTranslationKey2": {
    "message": "已翻译的信息2",
    "description": "myTranslationKey2 用于 FAQ 页"
  }
}

这一选择有两个原因：

Description attribute: to help translators with additional context
Widely supported: Chrome extensions, Crowdin, Transifex, Phrase, Applanga, etc.

数据文件

某些插件可能会读取外部数据文件，这些数据文件会被整体翻译。 For example, the blog plugin uses an authors.yml file that can be translated by creating a copy under i18n/[locale]/docusaurus-plugin-content-blog/authors.yml.

翻译文件位置

翻译文件必须创建在正确的文件系统位置。

Each locale and plugin has its own i18n subfolder:

website/i18n/[语言]/[插件名]/...

备注

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

把一个简单的 Docusaurus 网站翻译成简体中文，会产生如下的网站结构：

website/i18n
└── fr
    ├── code.json  # 所有 React 代码里的文本标签
    │              # 也包括主题代码里的文本
    ├── 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. Each plugin sources its own translated content under the corresponding folder, while the code.json file defines all text labels used in the React code.

Each content plugin or theme is different, and defines its own translation files location:

目标​

i18n 目标​

i18n 非目标​

翻译流程​

概览​

翻译文件​

Markdown 文件​

JSON 文件​

数据文件​

翻译文件位置​

目标