跳转至主内容
Version: 2.0.0-beta.21 🚧

i18n - 简介

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

目标

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

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

i18n 目标

Docusaurus i18n 系统旨在:

  • 简单易懂:将翻译过的文件放在正确的文件系统位置即可。
  • 弹性翻译流程:可使用 Git(单仓库、派生或子模块)、SaaS 软件或 FTP
  • 弹性部署选项:可部署于单个、多个域名或混合部署
  • 模块化:插件可提供 i18n 支持
  • Low-overhead runtime: documentation is mostly static and does not require heavy JS libraries or polyfills
  • 伸缩构建:允许独立构建及部署本地化内容网站
  • 本地化资源:您网站上的图像可被翻译
  • 无耦合:不强制使用任何 SaaS,但您可自己集成
  • Easy to use with Crowdin: a lot of Docusaurus v1 sites use Crowdin and should be able to migrate to v2
  • 优秀的 SEO 默认值:我们已为您预先设置有用的 SEO 页眉数据(如 hreflang
  • RTL 支持:支持并轻松实现自右向左阅读的语言(阿拉伯语、以色列语等)
  • Default translations: classic theme labels are translated for you in many languages

i18n 非目标

我们不支持:

  • Automatic locale detection: opinionated, and best done on the server (your hosting provider)
  • SaaS 翻译软件:您完全有责任理解您选择的外部工具。
  • 路径转译:技术困难,SEO 价值低。

翻译流程

概览

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

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

翻译文件

You will work with three kinds of translation files.

Markdown 文件

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

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

JSON 文件

JSON 用于翻译:

  • Your React code: standalone React pages in src/pages, or other components
  • Layout labels provided through themeConfig: navbar, footer
  • Layout labels provided through plugin options: docs sidebar category labels, blog sidebar title...

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

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

这一选择有两个原因:

Data files

Some plugins may read from external data files that are localized as a whole. For example, the blog plugin uses an authors.yml file that can be translated by creating a copy under i18n/[locale]/docusaurus-plugin-content-blog/authors.yml.

翻译文件位置

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

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

website/i18n/[locale]/[pluginName]/...
note

For multi-instance plugins, the path is 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

The JSON files are initialized with the docusaurus write-translations CLI command. Each plugin sources its own translated content under the corresponding folder, while the code.json file defines all text labels used in the React code.

Each content plugin or theme is different, and defines its own translation files location: