跳到主要内容

国际化 - 使用 Git

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

权衡​

此策略具有以下优势：

  • 易于上手 : 只需将 i18n 文件夹提交到 Git
  • 对开发人员友好 : Git、GitHub 和拉取请求是主流的开发者工具
  • 免费(或无任何额外成本，假设您已经使用 Git)
  • 低摩擦 : 不需要注册外部工具
  • 有益 : 贡献者很乐意拥有良好的贡献历史

使用 Git 也存在一些缺点：

  • 对非开发人员来说很难 : 他们不精通 Git 和拉取请求
  • 对专业翻译人员来说很难 : 他们习惯于使用 SaaS 翻译软件和高级功能
  • 难以维护 : 您必须使翻译文件与未翻译文件保持同步
备注

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

请参考 Docusaurus 国际化 RFC 获取我们对这些系统的研究笔记和链接。

初始化​

这是使用 Git 将新初始化的英文 Docusaurus 网站翻译成法文的步骤，并假设您已经按照 国际化教程 操作。

准备 Docusaurus 网站​

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

初始化 i18n 文件夹​

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

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) ' 选项使未翻译的字符串脱颖而出。

Hello 将显示为 (fr) Hello，这清楚地表明缺少翻译。

将未翻译的 Markdown 文件复制到法语文件夹：

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。

翻译文件​

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

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

npm run start -- --locale fr

您也可以在本地或 CI 上构建站点：

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

重复​

对您需要支持的每个区域设置重复此过程。

维护​

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

Markdown 翻译​

当编辑未翻译的 Markdown 文档时， 您有责任维护相应的翻译文件 ，并且我们不幸地没有一个好方法来帮助您做到这一点。

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

JSON 翻译​

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

npm run write-translations -- --locale fr

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

提示

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

本地化编辑 URL​

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

您的翻译在 Git 上，您可以使用 docs 和 blog 插件的 editLocalizedFiles: true 选项。

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

编辑此页
最后由 HomeUbuntu 于 更新