跳到主要内容
版本:3.0.0-rc.1

i18n - 使用 git

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

Tradeoffs

这一方法有如下优势:

  • Easy to get started: just commit the i18n folder to Git
  • Easy for developers: Git, GitHub and pull requests are mainstream developer tools
  • 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 也存在一些劣势:

  • Hard for non-developers: they do not master Git and pull-requests
  • 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
备注

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

初始化新的 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>
);
}

Initialize the i18n folder

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
提示

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.

把未翻译的 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。

Translate the files

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

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

npm run start -- --locale zh-Hans

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

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

Repeat

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

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 run write-translations -- --locale zh-Hans

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

提示

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.