跳转至主内容
Version: 2.0.0-alpha.75

i18n - 简介

您可以使用自带的国际化(i18n)支持来轻松翻译 Docusaurus 网站

目标#

了解 Docusaurus i18n 支持背后的设计决策是极为重要的。

要了解来龙去脉,您可阅读原始的 RFC合并请求提案。

i18n 目标#

Docusaurus i18n 系统旨在:

  • 简单易懂:将翻译过的文件放在正确的文件系统位置即可。
  • 弹性翻译流程:可使用 Git(单仓库、派生或子模块)、SaaS 软件或 FTP
  • 弹性部署选项:可部署于单个、多个域名或混合部署
  • 模块化:插件可提供 i18n 支持
  • 快速运行时:文档多为静态,无需重量级的 JS 库或 Polyfill
  • 伸缩构建:允许独立构建及部署本地化内容网站
  • 本地化资源:您网站上的图像可被翻译
  • 无耦合:不强制使用任何 SaaS,但您可自己集成
  • 轻松搭配 Crowdin:多个 Docusaurus v1 站点使用 Crowdin,它们都可迁移至 v2。
  • 优秀的 SEO 默认值:我们已为您预先设置有用的 SEO 页眉数据(如 hreflang
  • RTL 支持:支持并轻松实现自右向左阅读的语言(阿拉伯语、以色列语等)
  • 默认译文:经典主题的标签已为您翻译成多种语言

i18n 非目标#

我们不支持:

  • 自动检测语言:我们认为此功能在服务器上实现最佳。
  • SaaS 翻译软件:您完全有责任理解您选择的外部工具。
  • 路径转译:技术困难,SEO 价值低。

翻译流程#

概览#

下方是创建翻译版 Docusaurus 站点的工作流程:

  1. 配置:在 docusaurus.config.js 中声明默认及备选语言
  2. 翻译:将翻译过的文件放置在正确的文件系统位置即可。
  3. 部署:使用单域名或多域名策略构建并部署您的站点

翻译文件#

您将处理两种翻译文件。

Markdown 文件#

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

统一翻译 Markdown 及 MDX 文档以保证翻译语境正确,而不要将每个语句分成独立的字符串。

JSON 文件#

JSON 用于翻译:

  • 您的 React 代码:使用 <Translate> 组件
  • 您的主题:导航栏,页脚
  • 您的插件:文档侧边栏类别标签

我们使用的 JSON 格式名为 Chrome i18n

{  "myTranslationKey1": {    "message": "已翻译的信息 1",    "description": "myTranslationKey1 用于主页"  },  "myTranslationKey2": {    "message": "已翻译的信息2",    "description": "myTranslationKey2 用于 FAQ 页"  }}

这一选择有两个原因:

翻译文件位置#

翻译文件应该创建在正确的文件系统位置。

每种语言和每个插件均有其自己的 i18n 子文件夹:

website/i18n/<语言>/<插件名称>/...
note

对于多实例插件而言,路径则为 website/i18n/<语言>/<插件名称>-<插件 ID>/...

翻译简单的 Docusaurus 网站至简体中文会有如下的网站结构:

website/i18n└── zh-cn    ├── 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 组件中提取。

信息

注意,docusaurus-plugin-content-docs 插件有 current 子文件夹和 current.json 文件,这对文档分版功能较为有用。

每个内容插件或主题都不同,您需要定义其自己的翻译文件位置