翻译 & 本地化

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 文件,其中包含所有将从英文翻译成其他语言的字符串。

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

如何获得翻译的字符串

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/translation-process-overview/)来了解有关翻译工作流程的更多信息。 我们建议您不要选择“英语”作为可翻译的语言,以防止创建 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_IDCROWDIN_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 "test-site-bot@users.noreply.github.com"
      - 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_IDCROWDIN_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_identifierapi_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 设置的翻译部分中将 “重复字符串” 设置为“隐藏 - 所有重复将共享相同的翻译”。 此设置将确保不同版本之间的相同字符串共享一个翻译。