跳到主要内容
版本：3.8.1

i18n - 简介

通过 Docusaurus 的国际化（i18n）支持，**轻松翻译 Docusaurus 网站**。

目标​

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

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

i18n 目标​

Docusaurus i18n 系统的目标是：

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

i18n 非目标​

我们不提供以下支持：

  • **自动语言环境检测**：有主观性，最好在服务器（你的托管提供商）端完成。
  • **翻译 SaaS 软件**：你有责任了解你选择的外部工具。
  • **slug 翻译**：技术上复杂，SEO 价值小。

翻译工作流​

概述​

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

  1. **配置**：在 docusaurus.config.js 中声明默认语言环境和替代语言环境。
  2. **翻译**：将翻译文件放置在正确的文件系统位置。
  3. **部署**：使用单域或多域策略构建和部署你的站点。

翻译文件​

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

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"
  }
}

做出此选择有 2 个原因：

数据文件​

一些插件可能会读取作为整体进行本地化的外部数据文件。例如，博客插件使用 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 代码中使用的所有文本标签。

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