版本：Canary 🚧

i18n - 简介

Docusaurus 自带国际化（i18n）支持，你可以轻松翻译 Docusaurus 网站。

目标

了解 Docusaurus 的 i18n 支持背后作出的设计决策非常关键。

要了解来龙去脉，你可以阅读最初的 RFC 和合并请求提案。

i18n 目标

Docusaurus i18n 系统旨在：

简单易懂：将翻译过的文件放在正确的文件系统位置即可。
灵活翻译流程：可以使用 Git（单仓、fork、子模块）、SaaS 软件、FTP，等等
灵活部署选择：可以部署于单个、多个域名，或混合部署
模块化：插件作者也可提供国际化支持
轻量运行时：文档大多数内容都是静态的，无需重量级的 JS 库或 Polyfill
构建时间可控：允许独立构建并部署本地化内容网站
本地化资源：你的网站上的图像可被翻译
无耦合：不强制使用任何 SaaS，但您可自己集成
轻松搭配 Crowdin：许多 Docusaurus v1 网站使用 Crowdin，它们都可以迁移至 v2。
优秀的 SEO 默认值：我们已经为你预先设置好了有用的 SEO head 数据（如 hreflang）
RTL 支持：支持并轻松实现自右向左阅读的语言（阿拉伯语、以色列语等）
默认翻译：经典主题的文本已为你翻译成多种语言

i18n 非目标

我们不支持：

自动检测语言：太主观，最好在服务器上实现。
SaaS 翻译软件：理解你选择的外部工具是你的责任。
翻译 URL 路径：技术困难，SEO 价值低。

翻译流程

概览

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

配置：在 docusaurus.config.js 中声明默认语言和可选语言
翻译：将翻译过的文件放置在正确的文件系统位置即可
部署：使用单域名或多域名策略构建并部署你的站点

翻译文件

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

Markdown 文件

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

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

JSON 文件

JSON 用于翻译：

你的 React 代码： src/pages 中的独立 React 页面或其他组件
通过 themeConfig 提供的布局文本：导航栏，页脚等
通过插件选项提供的布局文本：文档侧边栏菜单标签，博客侧边栏标题等

我们使用的 JSON 格式名为 Chrome i18n：

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

这一选择有两个原因：

每条文本都有描述属性：为翻译者提供额外的语境
广泛支持：Chrome 插件、Crowdin、Transifex、Phrase、Applanga，等等

数据文件

某些插件可能会读取外部数据文件，这些数据文件会被整体翻译。比如博客插件用了一个 authors.yml 文件，这个文件的翻译方法就是在 i18n/[locale]/docusaurus-plugin-content-blog/authors.yml 目录下复制一份，然后翻译。

翻译文件位置

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

每种语言和每个插件均有其自己的 i18n 子文件夹：

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

备注

对于多实例插件而言，路径则为 website/i18n/[语言]/[插件名]-[插件 ID]/...。

把一个简单的 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   # 导航栏主题配置对应的文本

JSON 文件由 docusaurus write-translations CLI 命令初始化。 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.

每个内容插件或主题都不同，都会定义它自己的翻译文件位置：

目标​

i18n 目标​

i18n 非目标​

翻译流程​

概览​

翻译文件​

Markdown 文件​

JSON 文件​

数据文件​

翻译文件位置​

目标