跳至主要内容
版本：3.5.2

i18n - 使用 Git

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

权衡取舍​

此策略具有以下优势

  • 易于上手：只需将 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
# or
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。

编辑此页面
上次更新于 由 Sébastien Lorber 更新