翻译站点

本页解释了如何将翻译过的 Docusaurus v1 站点迁移到 Docusaurus v2。

i18n 差异

Docusaurus v2 i18n 在概念上与 Docusaurus v1 i18n 非常相似，但有一些不同。

它与 Crowdin 没有紧密耦合，你可以选择使用 Git 或其他 SaaS 服务。

不同的文件系统路径

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

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

每个插件都有自己的 i18n 子文件夹，例如：website/i18n/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 元素。

这对于 i18n 尤为重要，因为如果你的 Crowdin 翻译质量不佳并使用了无效标记，你的 v2 翻译站点可能会构建失败：你可能需要进行一些翻译清理来修复错误。

迁移策略

本节将帮助你了解如何在迁移到 v2 后保留你现有的 v1 翻译。

迁移使用 Crowdin 的 Docusaurus v1 站点有多种可能的策略，每种策略都有不同的权衡。

警告

本文档是帮助你迁移的最佳努力，如果你找到更好的方法，请帮助我们改进它！

首先，我们建议

• 将你的 v1 Docusaurus 站点迁移到 v2，不包含翻译
• 熟悉 Docusaurus v2 的新 i18n 系统 an
• 让 Crowdin 适用于你的 v2 站点，使用新的未翻译的 Crowdin 项目和 Crowdin 教程

危险

在不理解 Crowdin 和 Docusaurus v2 i18n 的情况下，请勿尝试迁移。

创建新的 Crowdin 项目

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

信息

这种策略曾用于 升级 Jest 网站。

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

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

你很可能会在第一次尝试时遇到错误：预翻译可能会尝试翻译不应翻译的内容（front matter、警告、代码块等），并且翻译后的 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 文件系统位置。