跳到主要内容

i18n - 简介

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

目标

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

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

i18n 的目标

Docusaurus 的 i18n 系统的目标是:

  • Simple: just put the translated files in the correct filesystem location
  • Flexible translation workflows: use Git (monorepo, forks, or submodules), SaaS software, FTP
  • Flexible deployment options: single, multiple domains, or hybrid
  • Modular: allow plugin authors to provide i18n support
  • Low-overhead runtime: documentation is mostly static and does not require heavy JS libraries or polyfills
  • Scalable build-times: allow building and deploying localized sites independently
  • Localize assets: an image of your site might contain text that should be translated
  • No coupling: not forced to use any SaaS, yet integrations are possible
  • Easy to use with Crowdin: a lot of Docusaurus v1 sites use Crowdin and should be able to migrate to v2
  • Good SEO defaults: we set useful SEO headers like hreflang for you
  • RTL support: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement
  • 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)
  • Translation SaaS software: you are responsible to understand the external tools of your choice
  • Translation of slugs: technically complicated, little SEO value

翻译流程

概述

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

  1. Configure: declare the default locale and alternative locales in docusaurus.config.js
  2. Translate: put the translation files at the correct filesystem location
  3. Deploy: build and deploy your site using a single or multi-domain strategy

待翻译文件

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": "Translated message 1",
"description": "myTranslationKey1 is used on the homepage"
},
"myTranslationKey2": {
"message": "Translated message 2",
"description": "myTranslationKey2 is used on the FAQ page"
}
}

做出此选择有两个原因:

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]/...
备注

对于支持多实例的插件,路径是 website/i18n/[locale]/[pluginName]-[pluginId]/....

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

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: