Skip to main content
Version: 3.5.1

国际化 - 使用 git

¥i18n - Using git

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

¥A possible translation strategy is to version control the translation files with Git (or any other VCS).

权衡​

¥Tradeoffs

该策略具有以下优点：

¥This strategy has advantages:

  • 易于上手：只需将 i18n 文件夹提交到 Git

    ¥Easy to get started: just commit the i18n folder to Git

  • 对开发者来说很容易：Git、GitHub 和 Pull Request 是主流开发者工具

    ¥Easy for developers: Git, GitHub and pull requests are mainstream developer tools

  • 免费（或者没有任何额外费用，假设你已经使用 Git）

    ¥Free (or without any additional cost, assuming you already use Git)

  • 低摩擦：不需要注册外部工具

    ¥Low friction: does not require signing up to an external tool

  • 奖励：贡献者很高兴拥有良好的贡献历史

    ¥Rewarding: contributors are happy to have a nice contribution history

使用 Git 也存在一些缺点：

¥Using Git also present some shortcomings:

  • 对于非开发者来说很难：他们不掌握 Git 和 pull-requests

    ¥Hard for non-developers: they do not master Git and pull-requests

  • 对于专业翻译来说很难：他们习惯于 SaaS 翻译软件和高级功能

    ¥Hard for professional translators: they are used to SaaS translation software and advanced features

  • 维护困难：你必须使已翻译的文件与未翻译的文件保持同步

    ¥Hard to maintain: you have to keep the translated files in sync with the untranslated files

注意

一些大型技术项目（React、Vue.js、MDN、TypeScript、Nuxt.js 等）使用 Git 进行翻译。

¥Some large-scale technical projects (React, Vue.js, MDN, TypeScript, Nuxt.js, etc.) use Git for translations.

请参阅 Docusaurus i18n RFC 了解我们研究这些系统的注释和链接。

¥Refer to the Docusaurus i18n RFC for our notes and links studying these systems.

初始化​

¥Initialization

这是使用 Git 将新初始化的英语 Docusaurus 网站翻译成法语的演练，并假设你已经遵循了 国际化教程。

¥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 站点​

¥Prepare the Docusaurus site

初始化一个新的 Docusaurus 站点：

¥Initialize a new Docusaurus site:

npx create-docusaurus@latest website classic

添加法语站点配置：

¥Add the site configuration for the French language:

docusaurus.config.js
export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
  },
  themeConfig: {
    navbar: {
      items: [
        // ...
        {
          type: 'localeDropdown',
          position: 'left',
        },
        // ...
      ],
    },
  },
  // ...
};

翻译主页：

¥Translate the homepage:

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 文件夹​

¥Initialize the i18n folder

使用 write-translations CLI 命令初始化法语区域设置的 JSON 翻译文件：

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

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) ' 选项可以突出未翻译的字符串。

¥Use the --messagePrefix '(fr) ' option to make the untranslated strings stand out.

Hello 将显示为 (fr) Hello，并明确表示缺少翻译。

¥Hello will appear as (fr) Hello and makes it clear a translation is missing.

将未翻译的 Markdown 文件复制到 French 文件夹中：

¥Copy your untranslated Markdown files to the French folder:

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。

¥Add all these files to Git.

翻译文件​

¥Translate the files

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

¥Translate the Markdown and JSON files in i18n/fr and commit the translation.

你现在应该能够以法语启动你的网站并查看翻译：

¥You should now be able to start your site in French and see the translations:

npm run start -- --locale fr

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

¥You can also build the site locally or on your CI:

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

重复​

¥Repeat

对于需要支持的每个区域设置，请遵循相同的流程。

¥Follow the same process for each locale you need to support.

维护​

¥Maintenance

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

¥Keeping translated files consistent with the originals can be challenging, in particular for Markdown documents.

Markdown 翻译​

¥Markdown translations

当编辑未翻译的 Markdown 文档时，你有责任维护相应的翻译文件，但遗憾的是，我们没有很好的方法来帮助你这样做。

¥When an untranslated Markdown document is edited, it is your responsibility to maintain the respective translated files, and we unfortunately don't have a good way to help you do so.

为了保持翻译网站的一致性，当编辑 website/docs/doc1.md 文档时，你需要将这些编辑向后移植到 i18n/fr/docusaurus-plugin-content-docs/current/doc1.md。

¥To keep your translated sites consistent, when the website/docs/doc1.md doc is edited, you need backport these edits to i18n/fr/docusaurus-plugin-content-docs/current/doc1.md.

JSON 翻译​

¥JSON translations

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

¥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

将附加新的翻译，并且现有的翻译不会被覆盖。

¥New translations will be appended, and existing ones will not be overridden.

提示

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

¥Reset your translations with the --override option.

本地化编辑 URL​

¥Localize edit URLs

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

¥When the user is browsing a page at /fr/doc1, the edit button will link by default to the unlocalized doc at website/docs/doc1.md.

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

¥Your translations are on Git, and you can use the editLocalizedFiles: true option of the docs and blog plugins.

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

¥The edit button will link to the localized doc at i18n/fr/docusaurus-plugin-content-docs/current/doc1.md.