版本：3.5.2

i18n - 簡介

透過其國際化 (i18n) 支援，翻譯 Docusaurus 網站非常容易。

目標

了解 Docusaurus i18n 支援背後的設計決策非常重要。

如需更多脈絡，你可以閱讀這篇初始 RFC 和 PR。

i18n 目標

Docusaurus i18n 系統的目標是

簡易：只要將翻譯後的檔案放在正確的檔案系統位置
彈性的翻譯工作流程：使用 Git（單一儲存庫、分支或子模組）、SaaS 軟體、FTP
彈性的佈署選項：單一網域、多個網域或混合
模組化：允許外掛作者提供 i18n 支援
低額外作業時間執行環境：文件大多為靜態，不需要大型 JS 程式庫或多重載入
可調整建置時間：允許各自建立和佈署地區化的網站
地區化素材：網站的圖片可能包含應翻譯的文字
無關聯性：無須使用任何 SaaS，但可以使用整合功能
容易與 Crowdin 搭配使用：許多 Docusaurus v1 網站使用 Crowdin，並且能夠移轉至 v2
優良的 SEO 預設值：我們設定有用的 SEO 標頭，例如 hreflang
支援 RTL：支援由右至左閱讀的語言 (阿拉伯語、希伯來語等)，且易於實作
預設翻譯：經典佈景主題標籤已為您在多種語言中翻譯

i18n 非目標

我們不支援

自動語言偵測：有立場，且最適合在伺服器 (您的代管供應商) 上完成
翻譯 SaaS 軟體：您有責任了解您選擇的外部工具
區塊翻譯：技術上很複雜，SEO 價值低

翻譯工作流程

概觀

建立已翻譯 Docusaurus 網站的工作流程概觀

設定：在 docusaurus.config.js 中宣告預設語言和備用語言
翻譯：將翻譯檔案放在正確的檔案系統位置
佈署：使用單一或多個網域名稱策略建立和佈署您的網站

翻譯檔案

您將會使用三種翻譯檔案。

Markdown 檔案

這是您的 Docusaurus 網站的主要內容。

Markdown 和 MDX 文件會整體翻譯，以完整保留翻譯脈絡，而非將每句話拆成一個獨立字串。

JSON 檔案

JSON 用於翻譯

您的 React 程式碼：src/pages 中的獨立 React 頁面或其他元件
透過 themeConfig 提供的版面標籤：導航欄、頁尾
透過外掛選項提供的版面標籤：文件側邊欄類別標籤、部落格側邊欄標題...

使用的 JSON 格式稱為 Chrome i18n

{
  "myTranslationKey1": {
    "message": "Translated message 1",
    "description": "myTranslationKey1 is used on the homepage"
  },
  "myTranslationKey2": {
    "message": "Translated message 2",
    "description": "myTranslationKey2 is used on the FAQ page"
  }
}

做出以上選擇的原因有 2 個

描述屬性：提供翻譯人員額外的脈絡說明
受到廣泛支援：Chrome 擴充功能、Crowdin、Transifex、Phrase、Applanga，等等。

資料檔案

有些外掛程式可能會從整體來說已在地化的外部資料檔案中讀取資料。例如，部落格外掛程式會使用 authors.yml 檔案，此檔案可以透過在 i18n/[locale]/docusaurus-plugin-content-blog/authors.yml 下建立一份副本來翻譯。

翻譯檔案位置

翻譯檔案應建立在正確的檔案系統位置。

每個語言環境和外掛程式都有其各自的 i18n 子資料夾

website/i18n/[locale]/[pluginName]/...

請注意

對於多個實例外掛程式，路徑為 website/i18n/[locale]/[pluginName]-[pluginId]/...。

翻譯成法文的一個非常簡單的 Docusaurus 網站會產生下列樹狀結構

website/i18n
└── fr
    ├── code.json  # Any text label present in the React code
    │              # Includes text labels from the themes' code
    ├── docusaurus-plugin-content-blog # translation data the blog plugin needs
    │   └── 2020-01-01-hello.md
    │
    ├── docusaurus-plugin-content-docs # translation data the docs plugin needs
    │   ├── current
    │   │   ├── doc1.md
    │   │   └── doc2.mdx
    │   └── current.json
    │
    └── docusaurus-theme-classic # translation data the classic theme needs
        ├── footer.json   # Text labels in your footer theme config
        └── navbar.json   # Text labels in your navbar theme config

JSON 檔案使用 docusaurus write-translations CLI 命令初始化。每個外掛程式都會在對應資料夾下找出自己的翻譯內容，而 code.json 檔案則會定義 React 程式碼中使用到的所有文字標籤。

每個內容外掛程式或主題都不一樣，而且會定義自己的翻譯檔案位置

目標​

i18n 目標​

i18n 非目標​

翻譯工作流程​

概觀​

翻譯檔案​

Markdown 檔案​

JSON 檔案​

資料檔案​

翻譯檔案位置​

目標