版本：3.5.2

i18n - 简介

借助其国际化（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 软件：您有责任了解您选择的外部工具
翻译 slug：技术上很复杂，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  # Any text label present in the React code
    │              # Includes text labels from the themes' code
    ├── docusaurus-plugin-content-blog # translation data the blog plugin needs
    │   └── 2020-01-01-hello.md
    │
    ├── docusaurus-plugin-content-docs # translation data the docs plugin needs
    │   ├── current
    │   │   ├── doc1.md
    │   │   └── doc2.mdx
    │   └── current.json
    │
    └── docusaurus-theme-classic # translation data the classic theme needs
        ├── footer.json   # Text labels in your footer theme config
        └── navbar.json   # Text labels in your navbar theme config

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

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

目标​

i18n 目标​

i18n 非目标​

翻译工作流程​

概述​

翻译文件​

Markdown 文件​

JSON 文件​

数据文件​

翻译文件位置​

目标