Facebook Docusaurus 中文文档 翻译&本地化

此系列文章的应用示例已发布于 GitHub: docusaurus-docs-Zh_CN. 可以 Fork 帮助改进或 Star 关注更新. 欢迎 Star.

翻译 & 本地化

Docusaurus允许使用 Crowdin 轻松实现翻译功能。 以英文撰写的文档文件将上传到 Crowdin，由社区内的用户进行翻译。 使用英文字符串编写的顶层页面可以通过在 <translate> 标签中包装要翻译的任何字符串来翻译。 其他标题和标签也将被找到并正确翻译。

Docusaurus 翻译配置

要用 Docusaurus 生成用于翻译的示例文件，请使用命令行参数 translations 运行 examples 脚本：

npm run examples translations

或

yarn examples translations

这将创建以下文件：

pages/en/help-with-translations.js
languages.js
../crowdin.yaml

pages/en/help-with-translations.js 文件包含由 examples 脚本生成的相同的起始帮助页面，但现在包含了翻译标签。

languages.js 文件告诉 Docusaurus 你想为你的网站启用什么语言。 默认情况下，我们希望启用英文。

crowdin.yaml 文件用于配置 crowdin 集成，并将其复制到您的 docusaurus 项目库。 如果您的docusaurus 项目驻留在 /project/website 中，则 crowdin.yaml 将被复制到 /project/crowdin.yaml 中。

翻译现有文档

您的文档文件不需要更改或移动来支持翻译。 他们将被上传到 Crowdin 直接翻译。

在页面上启用翻译

页面允许您自定义页面或帮助页面等页面的布局和特定内容。

包含要翻译的文字的页面应放置在 website/pages/en 文件夹中。

将需要翻译的字符串封装在一个 <translate> 标签中，并在文件的顶部添加下面的 require 语句：

...
const translate = require("../../server/translate.js").translate;
...
<h2>
  <translate>This header will be translated</translate>
</h2>
...

您还可以包含一个可选的 description 属性，为翻译者提供更多关于如何翻译字符串的上下文：

<p>
  <translate desc="flower, not verb">Rose</translate>
<p>

提取字符串到翻译

必须提取本地化页面内的字符串并提供给 Crowdin。

将以下脚本添加到您的package.json文件中：

...
"scripts": {
  "write-translations": "docusaurus-write-translations"
},
...

运行脚本将生成一个 website/i18n/en.json 文件，其中包含所有将从英文翻译成其他语言的字符串。

该脚本将包括来自以下地方的文本：

• 文档 markdown header 中的 title 和 sidebar_label 字符串
• sidebars.json 中的类别名称
• 在 siteConfig.js 中的 tagline
• siteConfig.js 中的 header link 的 label 字符串
• 在 pages 内的任何 .js 文件中的 <translate> 标签中包装的字符串

如何获得翻译的字符串

Docusaurus 本身不会从一种语言翻译到另一种语言。 相反，它集成了 Crowdin 来上传翻译，然后从 Crowdin 下载适当翻译的文件。

Docusaurus 如何使用字符串翻译

本节介绍 Docusaurus 中的翻译如何工作。

字符串

Docusaurus 网站有很多字符串需要本地化。 但是，维持在网站中使用的字符串列表可能是很费力的。 Docusaurus 通过集中字符串来简化这一点。

例如，标题导航可以链接到“主页”或“博客”。 在页面的标题和侧边栏中找到的这个和其他字符串被提取并放置到 i18n/en.json 中。 当你的文件被翻译成西班牙语时，一个 i18n/es-ES.json 文件将从 Crowdin 下载。 然后，当生成西班牙语页面时，Docusaurus 将从相应的本地化字符串文件中替换相应字符串的英文版本（例如，在启用西班牙语的网站“Help”中将变成“Ayuda”）。

Markdown 文件

对于文档文件本身，下载这些文件的翻译版本，然后通过适当的版面模板进行渲染。

其它页面

对于其他页面，Docusaurus 会自动将所发现的所有 <translate> 标签转换为函数调用，从相应的本地化文件 locale.json 返回翻译后的字符串。

Crowdin

Crowdin是一家提供翻译服务的公司。 对于开源项目，Crowdin 提供免费的字符串翻译。

在 Crowdin 上创建您的翻译项目。 您可以使用[Crowdin的指南]](https://support.crowdin.com/t...。 我们建议您不要选择“英语”作为可翻译的语言，以防止创建 en-US 本地化文件，因为这会导致混淆。

您的项目需要生成一个 crowdin.yaml 文件。

你将需要安装 crowdin-cli。 请参照安装说明。

下面的例子可以由 docusaurus cli 用 examples 脚本自动生成。 它应该放置在项目目录的顶层，以配置如何上传/下载文件。

以下是德语，西班牙语，法语，日语，韩语，印度尼西亚语，巴西葡萄牙语，简体中文和繁体中文的各种语言的配置示例。

project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
api_key_env: CROWDIN_DOCUSAURUS_API_KEY
base_path: "./"
preserve_hierarchy: true

files:
  -
    source: '/docs/*.md'
    translation: '/website/translated_docs/%locale%/%original_file_name%'
    languages_mapping: &anchor
      locale:
        'de': 'de'
        'es-ES': 'es-ES'
        'fr': 'fr'
        'ja': 'ja'
        'ko': 'ko'
        'mr': 'mr-IN'
        'pt-BR': 'pt-BR'
        'zh-CN': 'zh-CN'
        'zh-TW': 'zh-TW'

你可以在这里了解更多关于定制你的 crowdin.yaml 文件的信息。

手动同步文件

您将需要手动同步您的文件下拉和上传到 crowdin。 同步过程将上传 / docs 中的任何 markdown 文件以及 website/i18n/en.json 中的可翻译字符串。 （这些字符串可以通过运行 yarn write-translations 来生成。）

您可以将以下内容添加到您的 package.json 中以手动触发 crowdin。

"scripts": {
  "crowdin-upload": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID;
  export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml upload sources --auto-update -b master",
  "crowdin-download": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID;
  export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml download -b master"
},

这些命令需要拥有一个环境变量，用您的 crowdin 项目 id 和 api key（CROWDIN_PROJECT_ID，CROWDIN_API_KEY）设置。 你可以像上面一样内联添加它们，或者将它们永久添加到你的 .bashrc 或 .bash_profile 中。

如果在计算机上运行多个本地化的 Docusaurus 项目，则应该将环境变量的名称更改为唯一(CROWDIN_PROJECTNAME_PROJECT_ID, CROWDIN_PROJECTNAME_API_KEY)。

使用 CircleCI 自动同步文件

您可以使用 CircleCI 网络持续集成服务自动为您的文件下拉和上传翻译。

首先，更新项目目录中的 circle.yml 文件，包括上传要翻译的英文文件的步骤，以及使用 Crowdin CLI 下载已翻译的文件。 这是一个 circle.yml 文件的例子：

machine:
  node:
    version: 6.10.3
  npm:
    version: 3.10.10

test:
  override:
    - "true"

deployment:
  website:
    branch: master
    commands:
      # 配置 git 用户
      - git config --global user.email "[e-mail]"
      - git config --global user.name "Website Deployment Script"
      - echo "machine github.com login test-site-bot password $GITHUB_TOKEN" > ~/.netrc
      # 安装 Docusaurus 并生成英文字符串文件
      - cd website && npm install && npm run write-translations && cd ..
      # 安装 crowdin
      - sudo apt-get install default-jre
      - wget https://artifacts.crowdin.com/repo/deb/crowdin.deb -O crowdin.deb
      - sudo dpkg -i crowdin.deb
      # 翻译 上传/下载
      - crowdin --config crowdin.yaml upload sources --auto-update -b master
      - crowdin --config crowdin.yaml download -b master
      # 构建和发布网站
      - cd website && GIT_USER=test-site-bot npm run publish-gh-pages

crowdin 命令使用 examples 脚本生成的 crowdin.yaml 文件。 它应该放在您的项目目录中，以配置如何上传/下载文件。

请注意，在 crowdin.yaml 文件中，CROWDIN_PROJECT_ID 和 CROWDIN_API_KEY 是Circle 中为你的 Crowdin 项目设置的环境变量。 他们可以在您的 Crowdin 项目设置中找到。

现在，Circle 将帮助您在构建您的网站之前自动获取翻译。 提供的 crowdin.yaml 文件会将翻译后的文件复制到 website/translated_docs/ 中，i18n/en.json 字符串文件的翻译版本将转换为 i18n/${language}.json。

如果你想在本地使用你的机器上的 Crowdin，你可以安装 Crowdin CLI 工具 并运行 circle.yaml 文件中的命令。 唯一的区别是你必须在 crowdin.yaml 文件中设置 project_identifier 和 api_key 值，因为你不会设置 Circle 环境变量。

版本化翻译

如果您希望为文档进行翻译和版本控制，请将以下部分添加到 crowdin.yaml 文件的末尾：

  -
    source: '/website/versioned_docs/**/*.md'
    translation: '/website/translated_docs/%locale%/**/%original_file_name%'
    languages_mapping: *anchor

翻译版本的文档将被复制到 website/translated_docs/${language}/${version}/。

确保在您的 Crowdin 设置的翻译部分中将 “重复字符串” 设置为“隐藏 - 所有重复将共享相同的翻译”。 此设置将确保不同版本之间的相同字符串共享一个翻译。

如果这篇文章对您有帮助, 感谢 下方点赞 或 Star GitHub: docusaurus-docs-Zh_CN 支持, 谢谢.