跳到主要内容

翻译站点

本页面解释如何将 Docusaurus v1 的多语言站点迁移到 Docusaurus v2。

国际化的差异​

Docusaurus v2 的国际化（i18n）在概念上与 Docusaurus v1 非常相似，但有一些不同之处。

它不再紧密耦合于 Crowdin，您可以使用 Git 或其他 SaaS 平台。

不同的文件系统路径​

在 Docusaurus v2 中，本地化内容通常位于 website/i18n/[locale]。

Docusaurus v2 基于插件系统，每个插件负责管理自己的翻译。

每个插件都有自己的国际化子文件夹，例如：website/i18n/fr/docusaurus-plugin-content-blog

更新的翻译 API​

在 Docusaurus v1 中，您使用 <translate> 翻译页面：

const translate = require('../../server/translate.js').translate;

<h2>
  <translate desc="the header description">
    This header will be translated
  </translate>
</h2>;

在 Docusaurus v2 中，您使用 <Translate> 翻译页面：

import Translate from '@docusaurus/Translate';

<h2>
  <Translate id="header.translation.id" description="the header description">
    This header will be translated
  </Translate>
</h2>;
备注

write-translations CLI 仍然可以从您的代码中提取翻译。

代码翻译现在使用 Chrome i18n JSON 格式添加到 i18n/[locale]/code.json。

更严格的 Markdown 解析器​

Docusaurus v2 使用 MDX 解析 Markdown 文件。

MDX 将 Markdown 文件编译为 React 组件，比 Docusaurus v1 的解析器更严格，并且会在出错时使构建失败，而不是渲染一些不正确的内容。

另外，HTML 元素必须替换为 JSX 元素。

这对国际化尤其重要，因为如果您在 Crowdin 上的翻译不好并使用无效的标记，您的 v2 翻译站点可能无法构建：您可能需要清理翻译以修复错误。

迁移策略​

本节将帮助您找出如何在迁移到 v2 后保留现有的 v1 翻译。

有多种可能的策略可以迁移使用 Crowdin 的 Docusaurus v1 站点，各有利弊。

注意

这份文档尽最大努力帮助您迁移，如果您找到更好的方法，请帮助我们改进！

首先，我们建议：

危险

不要在不了解 Crowdin 和 Docusaurus v2 国际化的情况下尝试迁移。

创建新的 Crowdin 项目​

为了避免破坏生产环境中的 v1 站点的风险，一种可能的策略是复制原始 v1 Crowdin 项目。

信息

这个策略被用于升级 Jest 网站。

不幸的是，Crowdin 没有"复制/克隆项目"功能，这使事情变得复杂。

  • 以 .tmx 格式下载原始项目的翻译记忆（https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm > 查看记录）
  • 将翻译记忆上传到新项目（https://crowdin.com/project/<NEW_PROJECT>/settings#tm > 查看记录）
  • 根据国际化文档为 Docusaurus v2 重新配置 crowdin.yml
  • 使用 Crowdin CLI 将 Docusaurus v2 源文件上传到新项目
  • 将敏感字符串（如 id 或 slug）标记为"隐藏字符串"
  • 在"翻译"选项卡上，点击"预翻译 > 通过翻译记忆"（https://crowdin.com/project/<NEW_PROJECT>/settings#translations）
  • 首先尝试"100% 匹配"（比"完美"匹配更多内容将被翻译），并预翻译您的源文件
  • 在本地下载 Crowdin 翻译
  • 尝试运行/构建您的站点并查看是否有错误

您很可能在第一次尝试时遇到错误：预翻译可能会尝试翻译不应该翻译的内容（前言、提示、代码块...），并且翻译后的 MD 文件可能对 MDX 解析器无效。

您将不得不修复所有错误，直到您的站点可以构建。您可以通过本地修改翻译后的 MD 文件来完成，并使用 docusaurus build --locale fr 为一个语言环境修复站点。

我们无法写出一个终极指南来修复这些错误，但常见的错误是由于：

  • 在 Crowdin 中未标记足够的字符串为"隐藏字符串"，导致预翻译尝试翻译这些字符串。
  • 存在不好的 v1 翻译，导致 v2 中标记无效：翻译中的错误 HTML 元素和未关闭的标签
  • 被 MDX 解析器拒绝的任何内容，如使用 HTML 元素而不是 JSX 元素（使用 MDX 游乐场 进行调试）

您可能想重复这个预翻译过程，最终尝试"完美"选项，并仅限制某些语言/文件的预翻译。

提示

在有问题的 Markdown 元素周围使用 mdx-code-block：Crowdin 不太可能破坏代码块。

备注

您可能会注意到，在旧项目中已翻译的某些内容现在在新项目中未翻译。

Crowdin Markdown 解析器正在不断发展，每个 Crowdin 项目都有不同的解析器版本，这可能导致预翻译无法预翻译所有字符串。

这个解析器版本是未记录的，您将不得不询问 Crowdin 支持以了解您项目的解析器版本并修复特定版本。

在两个 Crowdin 项目中使用相同的 CLI 版本和解析器版本可能会带来更好的结果。

危险

Crowdin 有一个"上传翻译"功能，但根据我们的经验，它对 Markdown 的效果并不好。

使用现有的 Crowdin 项目​

如果您不介意修改现有的 Crowdin 项目并冒险破坏它，可能可以使用 Crowdin 分支系统。

注意

这个工作流程尚未在实践中测试，请向我们报告其效果。

这样，您就不需要创建新的 Crowdin 项目、转移翻译记忆、应用预翻译并尝试修复预翻译错误。

您可以为 Docusaurus v2 创建一个 Crowdin 分支，在其中上传 v2 源文件，并在准备就绪后将 Crowdin 分支合并到主分支。

使用 Git 代替 Crowdin​

可以迁移出 Crowdin，并改为将翻译文件添加到 Git。

使用 Crowdin CLI 下载 v1 翻译文件，并将这些翻译文件放置在正确的 Docusaurus v2 文件系统位置。