i18n - 简介

优质
小牛编辑
145浏览
2023-12-01

借助 Docusaurus 对国际化(i18n)的支持,可以 轻松地翻译 Docusaurus 网站

目标

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

有关更多背景信息,请参阅最初的 RFCPR

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 网站的流程大概如下:

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

待翻译文件

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

做出此选择有两个原因:

待翻译文档所在的位置

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

每种语言和插件都有其自己的 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 文件,用于 文档版本化功能

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