跳至主要內容
版本：3.5.2

i18n - 使用 git

可能的翻譯策略是使用 Git（或任何其他 VCS）版本控制翻譯檔案。

取捨​

這個策略有以下優點

  • 易於入門：只要提交 i18n 資料夾到 Git 即可
  • 對開發人員來說很容易：Git、GitHub 和拉取要求是主流的開發人員工具
  • 免費（或不需要任何額外費用，假設您已經使用 Git）
  • 阻力小：不需要註冊外部工具
  • 有回饋：貢獻者很樂意擁有良好的貢獻記錄

使用 Git 也有一些缺點

  • 對非開發人員來說很難：他們不熟悉 Git 和拉取要求
  • 對於專業翻譯來說很困難：他們習慣使用 SaaS 翻譯軟體和進階功能
  • 難以維護：您必須讓已翻譯檔案與未翻譯檔案保持同步
注意

一些大型技術專案（React、Vue.js、MDN、TypeScript、Nuxt.js 等）使用 Git 進行翻譯。

參閱 Docusaurus i18n RFC 以取得我們的筆記和研究這些系統的連結。

初始化​

以下是如何使用 Git 將剛初始化的英文 Docusaurus 網站翻譯成法文，並假設您已經遵循 i18n 指南。

準備 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 翻譯​

當未翻譯的 Markdwon 文件遭到編輯時，您有責任維護相關的已翻譯檔案，而不幸的是我們沒有好的方法來協助您這麼做。

要讓您翻譯的網站保持一致性，當 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 選項重設您的翻譯內容。

本地化編輯網址​

當使用者在 /fr/doc1 瀏覽頁面時，編輯按鈕預設會連結至 website/docs/doc1.md 中的非本地化文件。

您的翻譯位於 Git 上，而您可以使用文件和部落格外掛的 editLocalizedFiles: true 選項。

編輯按鈕會連結至 i18n/fr/docusaurus-plugin-content-docs/current/doc1.md 中的非本地化文件。