跳转至主内容
Version: 2.0.0-beta.5 🚧

i18n - 使用 git

其中一种翻译方法为使用 Git (或其他 VCS 软件) 来版本控制翻译文件。

利弊#

这一方法有如下优势：

  • 易于上手：添加 i18n 文件夹至 Git 即可
  • 开发方便：Git、GitHub 及合并请求均为主流的开发者工具
  • 免费 (假设您已使用了 Git，则无需其他工具)
  • 低关联：无需注册第三方工具
  • 高反馈：贡献者乐于看到自己优良的贡献历史

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

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

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

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

Git 教程#

下方是使用 Git 来翻译新创建的英文版 Docusaurus 站点至简体中文的手把手教程，本文假设您已遵循了 i18n 教程。

准备 Docusaurus 站点#

初始化新的 Docusaurus 站点：

npx @docusaurus/init@latest init website classic

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

docusaurus.config.js
module.exports = {  i18n: {    defaultLocale: 'en',    locales: ['en', 'zh-cn'],  },  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-cn
  1 translations written at i18n/zh-cn/code.json 11 translations written at i18n/zh-cn/docusaurus-theme-classic/footer.json  4 translations written at i18n/zh-cn/docusaurus-theme-classic/navbar.json  3 translations written at i18n/zh-cn/docusaurus-plugin-content-docs/current.json
tip

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

Hello 将显示为 (fr) Hello，标明缺少译文。

复制为翻译的 Markdown 文件至简体中文文件夹：

mkdir -p i18n/fr/docusaurus-plugin-content-docs/currentcp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current
mkdir -p i18n/fr/docusaurus-plugin-content-blogcp -r blog/** i18n/fr/docusaurus-plugin-content-blog
mkdir -p i18n/fr/docusaurus-plugin-content-pagescp -r src/pages/**.md i18n/fr/docusaurus-plugin-content-pagescp -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/zh-cn/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 fr

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

tip

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

本地化编辑链接#

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

您的译文托管于 Git 上，同时您可使用文档及博客插件的 editLocalizedFiles: true 选项。

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