跳到主要内容

i18n - 使用 Git

使用 Git（或任何其他版本控制系统）版本控制翻译文件是一种可能的翻译策略。

权衡​

这种策略有以下优点：

  • 易于入门：只需将 i18n 文件夹提交到 Git
  • 对开发者友好：Git、GitHub 和拉取请求是主流开发工具
  • 免费（或不产生额外成本，假设您已经使用 Git）
  • 低摩擦：不需要注册外部工具
  • 有成就感：贡献者很高兴有一个漂亮的贡献历史

使用 Git 也有一些缺点：

  • 对非开发者很难：他们不精通 Git 和拉取请求
  • 对专业翻译者很难：他们习惯于 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。