翻译网站

¥Translated sites

本页介绍如何将翻译后的 Docusaurus v1 站点迁移到 Docusaurus v2。

¥This page explains how migrate a translated Docusaurus v1 site to Docusaurus v2.

国际化差异

¥i18n differences

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

¥Docusaurus v2 i18n is conceptually quite similar to Docusaurus v1 i18n with a few differences.

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

¥It is not tightly coupled to Crowdin, and you can use Git or another SaaS instead.

不同的文件系统路径

¥Different filesystem paths

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

¥On Docusaurus v2, localized content is generally found at website/i18n/[locale].

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

¥Docusaurus v2 is modular based on a plugin system, and each plugin is responsible to manage its own translations.

每个插件都有自己的 i18n 子文件夹，例如：website/i18n/fr/docusaurus-plugin-content-blog

¥Each plugin has its own i18n subfolder, like: website/i18n/fr/docusaurus-plugin-content-blog

更新了翻译 API

¥Updated translation APIs

使用 Docusaurus v1，你可以使用 <translate> 翻译页面：

¥With Docusaurus v1, you translate your pages with <translate>:

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

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

在 Docusaurus v2 上，你使用 <Translate> 翻译页面

¥On Docusaurus v2, you translate your pages with <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 仍然可以从代码中提取翻译。

¥The write-translations CLI still works to extract translations from your code.

代码翻译现已使用 Chrome i18n JSON 格式添加到 i18n/[locale]/code.json。

¥The code translations are now added to i18n/[locale]/code.json using Chrome i18n JSON format.

更严格的 Markdown 解析器

¥Stricter Markdown parser

Docusaurus v2 使用 MDX 来解析 Markdown 文件。

¥Docusaurus v2 is using MDX to parse Markdown files.

MDX 将 Markdown 文件编译为 React 组件，比 Docusaurus v1 解析器更严格，并且会使你的构建因错误而失败，而不是渲染一些不良内容。

¥MDX compiles Markdown files to React components, is stricter than the Docusaurus v1 parser, and will make your build fail on error instead of rendering some bad content.

此外，HTML 元素必须替换为 JSX 元素。

¥Also, the HTML elements must be replaced by JSX elements.

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

¥This is particularly important for i18n because if your translations are not good on Crowdin and use invalid Markup, your v2 translated site might fail to build: you may need to do some translation cleanup to fix the errors.

迁移策略

¥Migration strategies

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

¥This section will help you figure out how to keep your existing v1 translations after you migrate to v2.

使用 Crowdin 迁移 Docusaurus v1 站点有多种可能的策略，但需要进行不同的权衡。

¥There are multiple possible strategies to migrate a Docusaurus v1 site using Crowdin, with different tradeoffs.

警告

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

¥This documentation is a best-effort to help you migrate, please help us improve it if you find a better way!

首先，我们建议：

¥Before all, we recommend to:

• 将你的 v1 Docusaurus 站点迁移到 v2，无需翻译

  ¥Migrate your v1 Docusaurus site to v2 without the translations

• 熟悉 Docusaurus v2 全新 i18n 系统 和

  ¥Get familiar with the new i18n system of Docusaurus v2 an

• 使用新的未翻译的 Crowdin 项目和 Crowdin 教程 让 Crowdin 适用于你的 v2 站点

  ¥Make Crowdin work for your v2 site, using a new and untranslated Crowdin project and the Crowdin tutorial

危险

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

¥Don't try to migrate without understanding both Crowdin and Docusaurus v2 i18n.

创建一个新的 Crowdin 项目

¥Create a new Crowdin project

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

¥To avoid any risk of breaking your v1 site in production, one possible strategy is to duplicate the original v1 Crowdin project.

信息

该策略被用于 升级 Jest 网站。

¥This strategy was used to upgrade the Jest website.

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

¥Unfortunately, Crowdin does not have any "Duplicate/clone Project" feature, which makes things complicated.

• 以 .tmx 格式下载原始项目的翻译记忆库 (https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm > View Records)

  ¥Download the translation memory of your original project in .tmx format (https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm > View Records)

• 将翻译记忆库上传到你的新项目 (https://crowdin.com/project/<NEW_PROJECT>/settings#tm > View Records)

  ¥Upload the translation memory to your new project (https://crowdin.com/project/<NEW_PROJECT>/settings#tm > View Records)

• 根据 i18n 文档为 Docusaurus v2 重新配置 crowdin.yml

  ¥Reconfigure crowdin.yml for Docusaurus v2 according to the i18n docs

• 使用 Crowdin CLI 将 Docusaurus v2 源文件上传到新项目

  ¥Upload the Docusaurus v2 source files with the Crowdin CLI to the new project

• 在 Crowdin 上将 id 或 slug 等敏感字符串标记为 "隐藏字符串"

  ¥Mark sensitive strings like id or slug as "hidden string" on Crowdin

• 在 "翻译" 选项卡上，单击 "预翻译 > 通过 TM" (https://crowdin.com/project/<NEW_PROJECT>/settings#translations)

  ¥On the "Translations" tab, click on "Pre-Translation > via TM" (https://crowdin.com/project/<NEW_PROJECT>/settings#translations)

• 首先尝试使用 "100% 匹配"（将比 "完美的" 翻译更多内容），然后预翻译你的源代码

  ¥Try first with "100% match" (more content will be translated than "Perfect"), and pre-translate your sources

• 将 Crowdin 翻译下载到本地

  ¥Download the Crowdin translations locally

• 尝试运行/构建你的网站并查看是否有任何错误

  ¥Try to run/build your site and see if there are any errors

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

¥You will likely have errors on your first-try: the pre-translation might try to translate things that it should not be translated (front matter, admonition, code blocks...), and the translated MD files might be invalid for the MDX parser.

你必须修复所有错误，直到你的网站构建完成。你可以通过在本地修改翻译后的 MD 文件来实现这一点，并使用 docusaurus build --locale fr 一次针对一种语言环境修复你的站点。

¥You will have to fix all the errors until your site builds. You can do that by modifying the translated MD files locally, and fix your site for one locale at a time using docusaurus build --locale fr.

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

¥There is no ultimate guide we could write to fix these errors, but common errors are due to:

• 在 Crowdin 中没有将足够的字符串标记为 "隐藏字符串"，导致预翻译尝试翻译这些字符串。

  ¥Not marking enough strings as "hidden strings" in Crowdin, leading to pre-translation trying to translate these strings.

• v1 翻译错误，导致 v2 中的标记无效：翻译中的 HTML 元素和未封闭的标签有问题

  ¥Having bad v1 translations, leading to invalid markup in v2: bad HTML elements inside translations and unclosed tags

• MDX 解析器拒绝的任何内容，例如使用 HTML 元素而不是 JSX 元素（使用 MDX 在线运行 进行调试）

  ¥Anything rejected by the MDX parser, like using HTML elements instead of JSX elements (use the MDX playground for debugging)

你可能想要重复此预翻译过程，最终尝试 "完美的" 选项并限制仅预翻译某些语言/文件。

¥You might want to repeat this pre-translation process, eventually trying the "Perfect" option and limiting pre-translation only some languages/files.

提示

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

¥Use mdx-code-block around problematic Markdown elements: Crowdin is less likely mess things up with code blocks.

注意

你可能会注意到，有些内容已在旧项目中翻译，但现在在新项目中未翻译。

¥You will likely notice that some things were translated on your old project, but are now untranslated in your new project.

Crowdin Markdown 解析器正在不断发展，每个 Crowdin 项目都有不同的解析器版本，这可能导致预翻译无法预翻译所有字符串。

¥The Crowdin Markdown parser is evolving other time and each Crowdin project has a different parser version, which can lead to pre-translation not being able to pre-translate all the strings.

该解析器版本没有记录，你必须询问 Crowdin 支持人员以了解你项目的解析器版本并修复一个特定版本。

¥This parser version is undocumented, and you will have to ask the Crowdin support to know your project's parser version and fix one specific version.

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

¥Using the same CLI version and parser version across the 2 Crowdin projects might give better results.

危险

Crowdin 有 "上传翻译" 功能，但根据我们的经验，它并没有为 Markdown 提供很好的结果

¥Crowdin has an "upload translations" feature, but in our experience it does not give very good results for Markdown

使用现有的 Crowdin 项目

¥Use the existing Crowdin project

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

¥If you don't mind modifying your existing Crowdin project and risking to mess things up, it may be possible to use the Crowdin branch system.

警告

此工作流程尚未经过实践测试，请向我们报告其效果如何。

¥This workflow has not been tested in practice, please report us how good it is.

这样，你就不需要创建新的 Crowdin 项目、传输翻译记忆库、应用预翻译以及尝试修复预翻译错误。

¥This way, you wouldn't need to create a new Crowdin project, transfer the translation memory, apply pre-translations, and try to fix the pre-translations errors.

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

¥You could create a Crowdin branch for Docusaurus v2, where you upload the v2 sources, and merge the Crowdin branch to main once ready.

使用 Git 代替 Crowdin

¥Use Git instead of Crowdin

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

¥It is possible to migrate away of Crowdin, and add the translation files to Git instead.

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

¥Use the Crowdin CLI to download the v1 translated files, and put these translated files at the correct Docusaurus v2 filesystem location.