国际化 - 简介

使用其国际化 (i18n) 支持， 轻松翻译 Docusaurus 网站 。

目标

理解 Docusaurus i18n 支持背后的 设计决策 非常重要。

更多上下文，您可以阅读最初的 RFC 和 PR 。

i18n 目标

Docusaurus i18n 系统的目标是：

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

i18n 非目标

我们不提供以下方面的支持：

自动语言环境检测 : 这是主观的，最好在服务器（您的托管提供商）上完成
翻译 SaaS 软件 : 您有责任了解您选择的外部工具
片段的翻译 : 技术上很复杂，SEO 价值很小

翻译工作流程

概述

创建翻译后的 Docusaurus 网站的工作流程概述：

配置 : 在 docusaurus.config.js 中声明默认语言环境和其他语言环境
翻译 : 将翻译文件放在正确的文件系统位置
部署 : 使用单域名或多域名策略构建和部署您的网站

翻译文件

您将使用三种类型的翻译文件。

Markdown 文件

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

Markdown 和 MDX 文档整体翻译，以完全保留翻译上下文，而不是将每个句子拆分成单独的字符串。

JSON 文件

JSON 用于翻译：

您的 React 代码：src/pages 中的独立 React 页面或其他组件
通过 themeConfig 提供的布局标签：导航栏、页脚
通过插件选项提供的布局标签：文档侧边栏类别标签、博客侧边栏标题……

使用的 JSON 格式称为 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"
  }
}

之所以做出这种选择，有两个原因：

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 # 经典主题需要的翻译数据
        ├── footer.json   # 页脚主题配置中的文本标签
        └── navbar.json   # 导航栏主题配置中的文本标签

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

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

目标​

i18n 目标​

i18n 非目标​

翻译工作流程​

概述​

翻译文件​

Markdown 文件​

JSON 文件​

数据文件​

翻译文件位置​

目标