Skip to main content
Version: Canary 🚧

i18n - 介绍

使用其国际化（i18n）支持，翻译Docusaurus网站非常容易。

目标​

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

如需更多背景信息，您可以阅读最初的RFC和PR。

国际化目标​

Docusaurus 国际化系统的目标是：

  • 简单：只需将翻译后的文件放在正确的文件系统位置
  • 灵活的翻译工作流程：使用Git（单仓库、分支或子模块）、SaaS软件、FTP
  • 灵活的部署选项：单域、多域或混合
  • 模块化: 允许插件作者提供i18n支持
  • 低开销运行时：文档大多是静态的，不需要大量的JS库或polyfills
  • 可扩展的构建时间：允许独立构建和部署本地化站点
  • 本地化资源: 您网站上的图片可能包含需要翻译的文本
  • 无耦合：不强制使用任何SaaS，但可以进行集成
  • 易于与Crowdin一起使用：许多Docusaurus v1站点使用Crowdin，应该能够迁移到v2
  • 良好的SEO默认设置：我们为您设置了有用的SEO头信息，如hreflang
  • RTL支持: 支持从右到左阅读的语言环境（阿拉伯语、希伯来语等），并且易于实现
  • 默认翻译: 经典主题标签已为您翻译成多种语言

i18n 非目标​

我们不提供以下支持：

  • 自动语言环境检测: 有主见的，最好在服务器（您的托管提供商）上完成
  • 翻译SaaS软件：您需要负责理解您选择的外部工具
  • 翻译 slugs：技术上复杂，SEO 价值低

翻译工作流程​

概述​

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

  1. 配置: 在docusaurus.config.js中声明默认语言环境和替代语言环境
  2. 翻译: 将翻译文件放置在正确的文件系统位置
  3. 部署: 使用单域或多域策略构建和部署您的站点

翻译文件​

您将使用三种类型的翻译文件。

Markdown 文件​

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

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

JSON 文件​

JSON 用于翻译：

  • 您的React代码：在src/pages中的独立React页面，或其他组件
  • 通过themeConfig提供的布局标签：导航栏，页脚
  • 通过插件选项提供的布局标签：文档侧边栏分类标签，博客侧边栏标题...

使用的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"
  }
}

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

数据文件​

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

翻译文件位置​

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

每个地区和插件都有自己的i18n子文件夹：

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

对于多实例插件，路径是 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

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

每个内容插件或主题都是不同的，并且定义了自己的翻译文件位置：