Skip to main content
Version: 3.7.0

已翻译的网站

本页解释了如何将翻译的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，您可以使用 来翻译您的页面：

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

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

在 Docusaurus v2 上，您可以使用 来翻译您的页面

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元素。

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

迁移策略​

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

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

warning

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

首先，我们建议：

danger

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

创建一个新的Crowdin项目​

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

info

此策略用于升级Jest网站。

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

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

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

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

没有我们可以编写的终极指南来修复这些错误，但常见的错误是由于：

  • 在Crowdin中没有将足够的字符串标记为“隐藏字符串”，导致预翻译尝试翻译这些字符串。
  • 存在不良的v1翻译，导致v2中出现无效标记：翻译中存在不良的HTML元素和未闭合的标签
  • 任何被MDX解析器拒绝的内容，例如使用HTML元素而不是JSX元素（使用MDX playground进行调试）

您可能希望重复此预翻译过程，最终尝试“完美”选项，并仅对某些语言/文件进行预翻译。

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文件系统位置。