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