i18n - 介绍

使用 Docusaurus 的国际化（i18n）支持，翻译网站变得非常简单。

目标

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

更多背景信息，您可以阅读最初的 RFC 和 PR。

i18n 目标

Docusaurus i18n 系统的目标是：

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

i18n 非目标

我们不提供以下支持：

自动语言环境检测：这是有偏见的，最好在服务器（您的托管提供商）上完成
翻译 SaaS 软件：您需要自行了解所选的外部工具
翻译别名（slugs）：技术上很复杂，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 在常见问题页面上使用"
  }
}

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

描述属性：帮助翻译者提供额外的上下文
广泛支持：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 # 经典主题需要的翻译数据
        ├── footer.json   # 页脚主题配置中的文本标签
        └── navbar.json   # 导航栏主题配置中的文本标签

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

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

目标​

i18n 目标​

i18n 非目标​

翻译工作流程​

概述​

翻译文件​

Markdown 文件​

JSON 文件​

数据文件​

翻译文件位置​

目标