i18n - 简介

借助其国际化（i18n）支持，翻译一个道格龙（Docusaurus）网站非常容易。

目标

了解道格龙（Docusaurus） i18n 支持背后的设计决策至关重要。

想了解更多背景信息，你可以阅读最初的 RFC 和 PR。

i18n 目标

道格龙（Docusaurus） i18n 系统的目标是：

简单：只需将翻译文件放置在正确的文件系统位置。
灵活的翻译工作流：可使用 Git（单一仓库、forks 或子模块）、SaaS 软件、FTP。
灵活的部署选项：支持单域名、多域名或混合部署。
模块化：允许插件作者提供 i18n 支持。
低运行时开销：文档大多是静态的，不需要庞大的 JS 库或 polyfill。
可扩展的构建时间：允许独立构建和部署本地化站点。
本地化资源：网站中的图片可能包含需要翻译的文本，i18n 系统也支持对这类资源进行本地化。
无耦合：不强制使用任何 SaaS，但可以轻松集成。
易于与 Crowdin 配合使用：许多道格龙（Docusaurus）v1 网站使用 Crowdin，我们希望它们能够顺利迁移到 v2。
良好的 SEO 默认设置：我们会为你设置有用的 SEO 标头，如 hreflang。
RTL 支持：支持从右到左阅读的语言环境（如阿拉伯语、希伯来语等），并且易于实现。
默认翻译：经典主题的标签已为你翻译成多种语言。

i18n 不支持

我们不提供以下支持：

自动语言环境检测：这是一个主观性很强的特性，最好在服务器（你的托管服务提供商）层面实现。
翻译 SaaS 软件：你需要自己负责了解并选择外部翻译工具。
slug 的翻译：技术上很复杂，且 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 页面"
  }
}

选择这种格式主要有两个原因：

description 属性：为翻译者提供额外的上下文信息。
广泛支持：被 Chrome 扩展、Crowdin、Transifex、Phrase、Applanga 等多种工具支持。

数据文件

有些插件可能会从外部数据文件读取内容，这些文件也是作为整体进行本地化的。例如，博客插件使用一个 authors.yml 文件，可以通过在 i18n/[locale]/docusaurus-plugin-content-blog/authors.yml 下创建一个副本来进行翻译。

翻译文件位置

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

每个语言环境和插件都有其自己的 i18n 子文件夹：

website/i18n/[locale]/[pluginName]/...

备注

对于多实例插件，路径为 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 # classic 主题需要的翻译数据
        ├── footer.json   # 页脚主题配置中的文本标签
        └── navbar.json   # 导航栏主题配置中的文本标签

JSON 文件通过 docusaurus write-translations CLI 命令进行初始化。每个插件会从其对应的文件夹中获取翻译内容，而 code.json 文件则定义了 React 代码中使用的所有文本标签。

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

目标​

i18n 目标​

i18n 不支持​

翻译工作流​

概览​

翻译文件​

Markdown 文件​

JSON 文件​

数据文件​

翻译文件位置​

目标