版本：Canary 🚧

i18n - 使用 git

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

Tradeoffs

这种策略有好处:

易于入门: just commit the i18n folder to Git
易于开发人员使用: Git, GitHub and pull requests are mainstream developer tools
免费的 (or without any additional cost, assuming you already use Git)
低摩擦: does not require signing up to an external tool
奖励: contributors are happy to have a nice contribution history

使用 Git 也有一些缺点:

对于非开发者来说很难: they do not master Git and pull-requests
专业翻译人员难: they are used to SaaS translation softwares and advanced features
难以维护: you have to keep the translated files in sync with the untranslated files

备注

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

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

Initialization

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.

Prepare the Docusaurus site

Initialize a new Docusaurus site:

npx create-docusaurus@latest website classic

Add the site configuration for the French language:

docusaurus.config.js
module.exports = {
  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>
  );
}

Initialize the `i18n` folder

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

npm
Yarn
pnpm

npm run write-translations -- --locale fr

translations written at i18n/fr/code.json
translations written at i18n/fr/docusaurus-theme-classic/footer.json
translations written at i18n/fr/docusaurus-theme-classic/navbar.json
translations written at i18n/fr/docusaurus-plugin-content-docs/current.json

yarn write-translations --locale fr

translations written at i18n/fr/code.json
translations written at i18n/fr/docusaurus-theme-classic/footer.json
translations written at i18n/fr/docusaurus-theme-classic/navbar.json
translations written at i18n/fr/docusaurus-plugin-content-docs/current.json

pnpm run write-translations -- --locale fr

translations written at i18n/fr/code.json
translations written at i18n/fr/docusaurus-theme-classic/footer.json
translations written at i18n/fr/docusaurus-theme-classic/navbar.json
translations written at i18n/fr/docusaurus-plugin-content-docs/current.json

提示

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

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

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

Add all these files to Git.

Translate the files

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
Yarn
pnpm

npm run start -- --locale fr

yarn run start --locale fr

pnpm run start -- --locale fr

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

npm
Yarn
pnpm

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

yarn build
# or
yarn build --locale fr

pnpm run build
# or
pnpm run build -- --locale fr

Repeat

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

Maintenance

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

Markdown translations

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.

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 translations

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

npm
Yarn
pnpm

npm run write-translations -- --locale fr

yarn write-translations --locale fr

pnpm run write-translations -- --locale fr

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

提示

Reset your translations with the --override option.

Localize edit URLs

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.

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

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

i18n - 使用 git

Tradeoffs​

Initialization​

Prepare the Docusaurus site​

Initialize the i18n folder​

Translate the files​

Repeat​

Maintenance​

Markdown translations​

JSON translations​

Localize edit URLs​