Skip to main content

翻译站点

本页解释了如何将翻译的道格龙（Docusaurus）v1 站点迁移到道格龙（Docusaurus）v2。

国际化差异​

道格龙（Docusaurus）v2 国际化在概念上与道格龙（Docusaurus）v1 国际化非常相似，但有一些差异。

它不与 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>;
note

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 站点，各有不同的权衡。

warning

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

首先，我们建议：

danger

不要在不理解 Crowdin 和道格龙（Docusaurus）v2 国际化的情况下尝试迁移。

创建新的 Crowdin 项目​

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

info

此策略用于升级 Jest 网站。

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

  • 以 .tmx 格式下载原始项目的翻译记忆（https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm > View Records）
  • 将翻译记忆上传到您的新项目（https://crowdin.com/project/<NEW_PROJECT>/settings#tm > View Records）
  • 根据国际化文档为新项目重新配置 crowdin.yml
  • 使用 Crowdin CLI 将道格龙（Docusaurus）v2 源文件上传到新项目
  • 在 Crowdin 上将敏感字符串如 id 或 slug 标记为"隐藏字符串"
  • 在"翻译"选项卡上，点击"预翻译 > 通过 TM"（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 游乐场 进行调试）

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

tip

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

note

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

Crowdin Markdown 解析器随时间演变，每个 Crowdin 项目都有不同的解析器版本，这可能导致预翻译无法预翻译所有字符串。

此解析器版本未记录，您必须询问 Crowdin 支持以了解您项目的解析器版本并修复特定版本。

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

danger

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

使用现有的 Crowdin 项目​

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

warning

此工作流程尚未在实践中测试，请向我们报告它的效果如何。

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

您可以为道格龙（Docusaurus）v2 创建 Crowdin 分支，在那里上传 v2 源文件，并在准备就绪时将 Crowdin 分支合并到主分支。

使用 Git 而不是 Crowdin​

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

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

Last updated on