跳到主要内容
版本：2.3.1

i18n - 使用 git

一种可行的翻译方法是通过 Git（或其他 VCS）来版本控制翻译文件。

利弊​

这一方法有如下优势：

  • 易于上手：在 Git 上添加 i18n 文件夹即可
  • 开发方便：Git、GitHub 及合并请求均为主流的开发者工具
  • 免费（至少不需要额外费用，如果你已经使用 Git 的话）
  • 工作量小：不需注册第三方工具
  • 高反馈：贡献者乐于看到自己漂亮的贡献历史

但使用 Git 也存在一些劣势：

  • 对非开发者不友好：他们并未掌握 Git 及合并请求
  • 对专业译者不友好：他们惯于使用 SaaS 翻译软件与高级功能
  • 难以维护：你必须保持已翻译和未翻译的文件同步
备注

有一些大规模的技术项目（如 React、Vue.js、MDN、TypeScript、Nuxt.js 等等）使用 Git 翻译。

请参见 Docusaurus i18n RFC 查看我们研究这些系统的链接与笔记。

初始化​

This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the i18n tutorial.

准备 Docusaurus 站点​

初始化新的 Docusaurus 站点：

npx create-docusaurus@latest website classic

添加简体中文版网站的配置：

docusaurus.config.js
module.exports = {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'zh-Hans'],
  },
  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 文件夹​

Use the write-translations CLI command to initialize the JSON translation files for the French locale:

npm run write-translations -- --locale zh-Hans

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

使用 --messagePrefix '(zh-Hans) ' 选项来标记未翻译的字符串。

Hello 会被显示为 (zh-Hans) Hello，表明缺少译文。

把未翻译的 Markdown 文件复制到简体中文文件夹：

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

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

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

把所有文件添加到 Git。

翻译文件​

翻译 i18n/zh-Hans 中的 Markdown 及 JSON 文件，并提交译文。

你现在可以用简体中文启动站点，并查看翻译：

npm run start -- --locale zh-Hans

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

npm run build
# 或者
npm run build -- --locale zh-Hans

以此类推​

为你要支持的每一个语言重复相同的流程。

维护​

将已翻译的文件与源文件保持一致是较为困难的，尤其对 Markdown 文档而言。

翻译 Markdown 文档​

当编辑未翻译的 Markdown 文档时，你还要负责维护相应的译文文件，而我们在这方面并没有好方法帮助你。

要使翻译版站点保持一致，你需要在编辑 website/docs/doc1.md 文档后，把这些编辑转移到 i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc1.md。

翻译 JSON​

To help you maintain the JSON translation files, it is possible to run again the write-translations CLI command:

npm run write-translations -- --locale zh-Hans

新译文会被追加，而旧译文不会被覆盖。

提示

可以用 --override 选项来重置你的译文。

本地化编辑链接​

当用户浏览位于 /zh-Hans/doc1 的页面时，编辑按钮会默认指向 website/docs/doc1.md 处的未翻译文档。

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

编辑按钮会指向位于 i18n/zh-Hans/docusaurus-plugin-content-docs/current/doc1.md 的本地化文档。