i18n - 简介

优质

小牛编辑

142浏览

2023-12-01

借助 Docusaurus 对国际化（i18n）的支持，可以 轻松地翻译 Docusaurus 网站 。

目标

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

有关更多背景信息，请参阅最初的 RFC 和 PR。

i18n 的目标

Docusaurus 的 i18n 系统的目标是：

简单：只需将翻译后的文件放到正确文件系统位置即可使用
灵活的翻译流程：支持 Git（单体仓库、分支或子模块）、SaaS 软件、FTP
灵活的部署选择：单个或多个域名或混合使用
模块化：让插件作者也能提供对 i18n 的支持
低开销的运行时：文档大部分是静态的，不需要引入巨大的 JS 库或 polyfills
弹性构建：允许独立构建和部署本地化的网站
本地化静态资源：网站上的图片可能包含需要翻译的文字
无耦合：不强制使用任何 SaaS 软件，但可以提供相应的集成
易于结合 Crowdin 使用：许多 Docusaurus v1 网站在使用 Crowdin，应当便于迁移到 Docusaurus v2
良好的 SEO 默认设置：我们为你设置了有用的 SEO 标头，例如 hreflang
对 RTL 的支持：支持从右往左读的语言（阿拉伯语、希伯来语等），并且易于实现
默认翻译：classic 主题中的某些内容以为你翻译成多种语言了

非 i18n 的目标

我们不提供以下支持：

自动语言检测: 坚持认为最好在服务器端实现
辅助翻译的 SaaS 软件：了解你所选择使用的外部工具是你自己的责任
对链接（slugs）的翻译：技术复杂，SEO 价值低

翻译流程

概述

翻译 Docusaurus 网站的流程大概如下：

配置：在 docusaurus.config.js 文件中声明默认语言和其它语言
翻译：将待翻译文件放到正确的文件系统位置上
部署：使用单个或多个域名策略来构建并部署你的网站

待翻译文件

有 2 种待翻译文件需要你处理。

Markdown 文件

这是 Docusaurus 网站的主要内容。

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

JSON 文件

以下内容利用 JSON 格式的文件进行翻译：

React 代码：使用 <Translate> 组件的内容
主题：导航条、页脚
插件：文档侧边栏的类别标签

所使用的 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"
  }
}

做出此选择有两个原因：

描述性的属性：为翻译人员提供上下文
广泛的支持：Chrome 扩展程序、Crowdin、Transifex、Phrase、Applanga

待翻译文档所在的位置

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

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

website/i18n/<locale>/<pluginName>/...

note

对于支持多实例的插件，路径是 website/i18n/<locale>/<pluginName>-<pluginId>/....

假如将一个非常简单的网站翻译为法语版本，则会具有以下结构树：

website/i18n
└── fr
    ├── code.json
    │
    ├── 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 文件是利用 <Translate> API 从 React 组件中提取出来的。

info

注意，docusaurus-plugin-content-docs 插件具有一个 current 子文件夹和一个 current.json 文件，用于 文档版本化功能。

每个插件或主题所具有的文件和文件夹都是不同的，并且 对待翻译文件的位置都有各自的定义：