跳至主要内容
版本：3.5.2

翻译后的网站

本页说明如何将翻译后的 Docusaurus v1 网站迁移到 Docusaurus v2。

i18n 差异​

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

它没有与 Crowdin 紧密耦合，你可以使用 Git 或其他 SaaS 代替。

不同的文件系统路径​

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

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

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

这对 i18n 尤其重要，因为如果你的翻译在 Crowdin 上不好并且使用无效的标记，你的 v2 翻译后的网站可能无法构建：你可能需要进行一些翻译清理以修复错误。

迁移策略​

本节将帮助你弄清楚如何 **在迁移到 v2 后保留你现有的 v1 翻译**。

有多种 **可能的策略** 可以使用 Crowdin 迁移 Docusaurus v1 网站，它们有不同的权衡。

警告

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

首先，我们建议你

危险

不要尝试在不了解 Crowdin 和 Docusaurus v2 i18n 的情况下进行迁移。

创建一个新的 Crowdin 项目​

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

信息

此策略用于 升级 Jest 网站。

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

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

你的第一次尝试可能会出现错误：预翻译可能会尝试翻译不应该翻译的内容（前置 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 支持人员咨询你的项目的解析器版本并修复特定版本。

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

危险

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

使用现有的 Crowdin 项目​

如果你不介意修改你现有的 Crowdin 项目并冒着弄乱事情的风险，可以使用 Crowdin 分支系统。

警告

此工作流程尚未在实践中进行测试，请报告我们它有多好。

通过这种方式，你无需创建新的 Crowdin 项目、传输翻译记忆、应用预翻译并尝试修复预翻译错误。

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

使用 Git 代替 Crowdin​

可以迁移到 Crowdin 之外，并将翻译文件添加到 Git 中。

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

编辑此页面
上次更新于 由 Sébastien Lorber 更新