跳到主要内容
版本：3.8.1

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/code.json
 11 translations written at i18n/docusaurus-theme-classic/footer.json
  4 translations written at i18n/docusaurus-theme-classic/navbar.json
  3 translations written at i18n/docusaurus-plugin-content-docs/current.json
提示

使用 --messagePrefix '(fr) ' 选项，使未翻译的字符串更加醒目。

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

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

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

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

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

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

翻译文件​

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

您现在应该能够以法语启动您的站点并查看翻译

npm run start -- --locale fr

您也可以在本地或您的 CI 上构建站点

npm run build
# or
npm run build -- --locale fr

重复​

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

维护​

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

Markdown 翻译​

当未翻译的 Markdown 文档被编辑时，**您有责任维护相应的翻译文件**，遗憾的是，我们没有很好的方法来帮助您完成此操作。

为了保持翻译站点的一致性，当 website/docs/doc1.md 文档被编辑时，您需要**将这些编辑回溯**到 i18n/docusaurus-plugin-content-docs/current/doc1.md。

JSON 翻译​

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

npm run write-translations -- --locale fr

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

提示

使用 --override 选项重置您的翻译。

本地化编辑 URL​

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

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

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