跳到主要内容

i18n - 使用 Git

一个可能的翻译策略是使用 Git（或任何其他 VCS）对翻译文件进行版本控制。

权衡利弊​

此策略有以下优点：

  • 易于上手：只需将 i18n 文件夹提交到 Git。
  • 对开发者友好：Git、GitHub 和 pull requests 是主流的开发者工具。
  • 免费（或无需额外费用，假设你已经在使用 Git）。
  • 低门槛：不需要注册外部工具。
  • 成就感：贡献者会很高兴能拥有一个漂亮的贡献历史记录。

使用 Git 也有一些缺点：

  • 对非开发者不友好：他们不熟悉 Git 和 pull-requests。
  • 对专业翻译人员不友好：他们习惯于使用 SaaS 翻译软件和其高级功能。
  • 难以维护：你必须保持翻译文件与未翻译文件同步。
备注

一些大型技术项目（如 React、Vue.js、MDN、TypeScript、Nuxt.js 等）使用 Git 进行翻译。

请参阅 道格龙（Docusaurus） i18n RFC 了解我们研究这些系统的笔记和链接。

初始化​

本节将引导你使用 Git 将一个新初始化的英文道格龙（Docusaurus）网站翻译成法语，并假设你已经完成了 i18n 教程。

准备道格龙（Docusaurus）站点​

初始化一个新的道格龙（Docusaurus）站点：

npx create-docusaurus@latest website classic

为法语添加站点配置：

docusaurus.config.js
export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
  },
  themeConfig: {
    navbar: {
      items: [
        // ...
        {
          type: 'localeDropdown',
          position: 'left',
        },
        // ...
      ],
    },
  },
  // ...
};

翻译主页：

src/pages/index.js
import React from 'react';
import Translate from '@docusaurus/Translate';
import Layout from '@theme/Layout';

export default function Home() {
  return (
    <Layout>
      <h1 style={{margin: 20}}>
        <Translate description="The homepage main heading">
          Welcome to my Docusaurus translated site!
        </Translate>
      </h1>
    </Layout>
  );
}

初始化 i18n 文件夹​

使用 write-translations CLI 命令为法语语言环境初始化 JSON 翻译文件：

npm run write-translations -- --locale fr

  1 translations written at i18n/fr/code.json
 11 translations written at i18n/fr/docusaurus-theme-classic/footer.json
  4 translations written at i18n/fr/docusaurus-theme-classic/navbar.json
  3 translations written at i18n/fr/docusaurus-plugin-content-docs/current.json
提示

使用 --messagePrefix '(fr) ' 选项可以使未翻译的字符串更加突出。

Hello 将显示为 (fr) Hello，从而清楚地表明缺少翻译。

将你未翻译的 Markdown 文件复制到法语文件夹：

mkdir -p i18n/fr/docusaurus-plugin-content-docs/current
cp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current

mkdir -p i18n/fr/docusaurus-plugin-content-blog
cp -r blog/** i18n/fr/docusaurus-plugin-content-blog

mkdir -p i18n/fr/docusaurus-plugin-content-pages
cp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pages
cp -r src/pages/**.mdx i18n/fr/docusaurus-plugin-content-pages

将所有这些文件添加到 Git。

翻译文件​

翻译 i18n/fr 中的 Markdown 和 JSON 文件，并提交翻译。

现在你应该能够以法语启动你的站点并看到翻译：

npm run start -- --locale fr

你也可以在本地或 CI 上构建站点：

npm run build
# 或
npm run build -- --locale fr

重复​

为每个需要支持的语言环境重复相同的过程。

维护​

保持翻译文件与源文件一致可能具有挑战性，特别是对于 Markdown 文档。

Markdown 翻译​

当一个未翻译的 Markdown 文档被编辑时，你有责任维护相应的翻译文件，不幸的是，我们目前没有很好的方法来帮助你做到这一点。

为了保持你的翻译站点的一致性，当 website/docs/doc1.md 文档被编辑时，你需要将这些编辑反向移植到 i18n/fr/docusaurus-plugin-content-docs/current/doc1.md。

JSON 翻译​

为了帮助你维护 JSON 翻译文件，可以再次运行 write-translations CLI 命令：

npm run write-translations -- --locale fr

新的翻译将被追加，而现有的翻译不会被覆盖。

提示

使用 --override 选项可以重置你的翻译。

本地化编辑 URL​

当用户浏览 /fr/doc1 页面时，编辑按钮默认会链接到未本地化的文档 website/docs/doc1.md。

你的翻译在 Git 上，你可以使用文档和博客插件的 editLocalizedFiles: true 选项。

这样，编辑按钮将链接到本地化的文档 i18n/fr/docusaurus-plugin-content-docs/current/doc1.md。