跳到主要内容

已翻译的站点

此页面解释如何将已翻译的 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 源文件上传到新项目
  • 将诸如 id 或 slug 之类的敏感字符串标记为 Crowdin 上的“隐藏字符串”
  • 在“翻译”选项卡上，单击“预翻译 > 通过 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 playground 进行调试）

您可能希望重复此预翻译过程，最终尝试“完美”选项并将预翻译限制在某些语言/文件上。

提示

在有问题的 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 文件系统位置。

编辑此页
最后由 HomeUbuntu 于 更新