Skip to main content
Version: 3.5.1

国际化 - 介绍

¥i18n - Introduction

借助国际化 (国际化) 支持，翻译 Docusaurus 网站非常容易。

¥It is easy to translate a Docusaurus website with its internationalization (i18n) support.

目标​

¥Goals

了解 Docusaurus i18n 支持背后的设计决策非常重要。

¥It is important to understand the design decisions behind the Docusaurus i18n support.

有关更多上下文，你可以阅读最初的 RFC 和 PR。

¥For more context, you can read the initial RFC and PR.

国际化目标​

¥i18n goals

Docusaurus i18n 系统的目标是：

¥The goals of the Docusaurus i18n system are:

  • 简单的：只需将翻译后的文件放入正确的文件系统位置

    ¥Simple: just put the translated files in the correct filesystem location

  • 灵活的翻译工作流程：使用 Git（monorepo、forks 或子模块）、SaaS 软件、FTP

    ¥Flexible translation workflows: use Git (monorepo, forks, or submodules), SaaS software, FTP

  • 灵活的部署选项：单个、多个域或混合

    ¥Flexible deployment options: single, multiple domains, or hybrid

  • 模块化的：允许插件作者提供 i18n 支持

    ¥Modular: allow plugin authors to provide i18n support

  • 低开销运行时：文档大部分是静态的，不需要大量的 JS 库或 polyfill

    ¥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

  • 无耦合：不强制使用任何 SaaS，但可以集成

    ¥No coupling: not forced to use any SaaS, yet integrations are possible

  • 易于与 Crowdin 一起使用：许多 Docusaurus v1 网站都使用 Crowdin，应该能够迁移到 v2

    ¥Easy to use with Crowdin: a lot of Docusaurus v1 sites use Crowdin and should be able to migrate to v2

  • 良好的 SEO 默认设置：我们为你设置有用的 SEO 标头，例如 hreflang

    ¥Good SEO defaults: we set useful SEO headers like hreflang for you

  • RTL 支持：支持从右到左阅读的区域设置（阿拉伯语、希伯来语等）并且易于实现

    ¥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 non-goals

我们不提供以下支持：

¥We don't provide support for:

  • 自动区域设置检测：有态度，最好在 服务器（你的托管提供商） 上完成

    ¥Automatic locale detection: opinionated, and best done on the server (your hosting provider)

  • 翻译 SaaS 软件：你有责任了解你选择的外部工具

    ¥Translation SaaS software: you are responsible to understand the external tools of your choice

  • 蛞蝓的翻译:技术复杂，SEO 价值不大

    ¥Translation of slugs: technically complicated, little SEO value

翻译工作流程​

¥Translation workflow

概述​

¥Overview

创建翻译后的 Docusaurus 网站的工作流程概述：

¥Overview of the workflow to create a translated Docusaurus website:

  1. 配置：在 docusaurus.config.js 中声明默认语言环境和替代语言环境

    ¥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

翻译文件​

¥Translation files

你将使用三种翻译文件。

¥You will work with three kinds of translation files.

Markdown 文件​

¥Markdown files

这是 Docusaurus 网站的主要内容。

¥This is the main content of your Docusaurus website.

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

¥Markdown and MDX documents are translated as a whole, to fully preserve the translation context, instead of splitting each sentence as a separate string.

JSON 文件​

¥JSON files

JSON 用于翻译：

¥JSON is used to translate:

  • 你的 React 代码：src/pages 中的独立 React 页面或其他组件

    ¥Your React code: standalone React pages in src/pages, or other components

  • 通过 themeConfig 提供的布局标签：导航栏、页脚

    ¥Layout labels provided through themeConfig: navbar, footer

  • 通过插件选项提供的布局标签：文档侧边栏类别标签、博客侧边栏标题...

    ¥Layout labels provided through plugin options: docs sidebar category labels, blog sidebar title...

使用的 JSON 格式称为 Chrome i18n：

¥The JSON format used is called 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"
  }
}

做出这个选择有两个原因：

¥The choice was made for 2 reasons:

数据文件​

¥Data files

某些插件可能会从整体本地化的外部数据文件中读取。例如，博客插件使用 authors.yml 文件，可以通过在 i18n/[locale]/docusaurus-plugin-content-blog/authors.yml 下创建副本来翻译该文件。

¥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.

翻译文件位置​

¥Translation files location

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

¥The translation files should be created at the correct filesystem location.

每个语言环境和插件都有自己的 i18n 子文件夹：

¥Each locale and plugin has its own i18n subfolder:

website/i18n/[locale]/[pluginName]/...
注意

对于多实例插件，路径为 website/i18n/[locale]/[pluginName]-[pluginId]/...。

¥For multi-instance plugins, the path is website/i18n/[locale]/[pluginName]-[pluginId]/....

将一个非常简单的 Docusaurus 站点翻译成法语将生成以下树：

¥Translating a very simple Docusaurus site in French would lead to the following tree:

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

JSON 文件使用 docusaurus write-translations CLI 命令初始化。每个插件在相应的文件夹下获取自己的翻译内容，而 code.json 文件定义了 React 代码中使用的所有文本标签。

¥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: