Facebook Docusaurus 中文文檔 翻譯&本地化

此係列文章的應用示例已發佈於 GitHub: docusaurus-docs-Zh_CN. 能夠 Fork 幫助改進或 Star 關注更新. 歡迎 Star.

翻譯 & 本地化

Docusaurus容許使用 Crowdin 輕鬆實現翻譯功能。 以英文撰寫的文檔文件將上傳到 Crowdin，由社區內的用戶進行翻譯。 使用英文字符串編寫的頂層頁面能夠經過在 <translate> 標籤中包裝要翻譯的任何字符串來翻譯。 其餘標題和標籤也將被找到並正確翻譯。

Docusaurus 翻譯配置

要用 Docusaurus 生成用於翻譯的示例文件，請使用命令行參數 translations 運行 examples 腳本：

npm run examples translations

或

yarn examples translations

這將建立如下文件：

pages/en/help-with-translations.js
languages.js
../crowdin.yaml

pages/en/help-with-translations.js 文件包含由 examples 腳本生成的相同的起始幫助頁面，但如今包含了翻譯標籤。

languages.js 文件告訴 Docusaurus 你想爲你的網站啓用什麼語言。 默認狀況下，咱們但願啓用英文。

crowdin.yaml 文件用於配置 crowdin 集成，並將其複製到您的 docusaurus 項目庫。 若是您的docusaurus 項目駐留在 /project/website 中，則 crowdin.yaml 將被複制到 /project/crowdin.yaml 中。

翻譯現有文檔

您的文檔文件不須要更改或移動來支持翻譯。 他們將被上傳到 Crowdin 直接翻譯。

在頁面上啓用翻譯

頁面容許您自定義頁面或幫助頁面等頁面的佈局和特定內容。

包含要翻譯的文字的頁面應放置在 website/pages/en 文件夾中。

將須要翻譯的字符串封裝在一個 <translate> 標籤中，並在文件的頂部添加下面的 require 語句：

...
const translate = require("../../server/translate.js").translate;
...
<h2>
  <translate>This header will be translated</translate>
</h2>
...

您還能夠包含一個可選的 description 屬性，爲翻譯者提供更多關於如何翻譯字符串的上下文：

<p>
  <translate desc="flower, not verb">Rose</translate>
<p>

提取字符串到翻譯

必須提取本地化頁面內的字符串並提供給 Crowdin。

將如下腳本添加到您的package.json文件中：

...
"scripts": {
  "write-translations": "docusaurus-write-translations"
},
...

運行腳本將生成一個 website/i18n/en.json 文件，其中包含全部將從英文翻譯成其餘語言的字符串。

該腳本將包括來自如下地方的文本：

• 文檔 markdown header 中的 title 和 sidebar_label 字符串
• sidebars.json 中的類別名稱
• 在 siteConfig.js 中的 tagline
• siteConfig.js 中的 header link 的 label 字符串
• 在 pages 內的任何 .js 文件中的 <translate> 標籤中包裝的字符串

如何得到翻譯的字符串

Docusaurus 自己不會從一種語言翻譯到另外一種語言。 相反，它集成了 Crowdin 來上傳翻譯，而後從 Crowdin 下載適當翻譯的文件。

Docusaurus 如何使用字符串翻譯

本節介紹 Docusaurus 中的翻譯如何工做。

字符串

Docusaurus 網站有不少字符串須要本地化。 可是，維持在網站中使用的字符串列表多是很費力的。 Docusaurus 經過集中字符串來簡化這一點。

例如，標題導航能夠連接到「主頁」或「博客」。 在頁面的標題和側邊欄中找到的這個和其餘字符串被提取並放置到 i18n/en.json 中。 當你的文件被翻譯成西班牙語時，一個 i18n/es-ES.json 文件將從 Crowdin 下載。 而後，當生成西班牙語頁面時，Docusaurus 將從相應的本地化字符串文件中替換相應字符串的英文版本（例如，在啓用西班牙語的網站「Help」中將變成「Ayuda」）。

Markdown 文件

對於文檔文件自己，下載這些文件的翻譯版本，而後經過適當的版面模板進行渲染。

其它頁面

對於其餘頁面，Docusaurus 會自動將所發現的全部 <translate> 標籤轉換爲函數調用，從相應的本地化文件 locale.json 返回翻譯後的字符串。

Crowdin

Crowdin是一家提供翻譯服務的公司。 對於開源項目，Crowdin 提供免費的字符串翻譯。

在 Crowdin 上建立您的翻譯項目。 您可使用[Crowdin的指南]](https://support.crowdin.com/t...。 咱們建議您不要選擇「英語」做爲可翻譯的語言，以防止建立 en-US 本地化文件，由於這會致使混淆。

您的項目須要生成一個 crowdin.yaml 文件。

你將須要安裝 crowdin-cli。 請參照 安裝說明。

下面的例子能夠由 docusaurus cli 用 examples 腳本自動生成。 它應該放置在項目目錄的頂層，以配置如何上傳/下載文件。

如下是德語，西班牙語，法語，日語，韓語，印度尼西亞語，巴西葡萄牙語，簡體中文和繁體中文的各類語言的配置示例。

project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
api_key_env: CROWDIN_DOCUSAURUS_API_KEY
base_path: "./"
preserve_hierarchy: true

files:
  -
    source: '/docs/*.md'
    translation: '/website/translated_docs/%locale%/%original_file_name%'
    languages_mapping: &anchor
      locale:
        'de': 'de'
        'es-ES': 'es-ES'
        'fr': 'fr'
        'ja': 'ja'
        'ko': 'ko'
        'mr': 'mr-IN'
        'pt-BR': 'pt-BR'
        'zh-CN': 'zh-CN'
        'zh-TW': 'zh-TW'

你能夠在這裏瞭解更多關於定製你的 crowdin.yaml 文件的信息。

手動同步文件

您將須要手動同步您的文件下拉和上傳到 crowdin。 同步過程將上傳 / docs 中的任何 markdown 文件以及 website/i18n/en.json 中的可翻譯字符串。 （這些字符串能夠經過運行 yarn write-translations 來生成。）

您能夠將如下內容添加到您的 package.json 中以手動觸發 crowdin。

"scripts": {
  "crowdin-upload": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID;
  export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml upload sources --auto-update -b master",
  "crowdin-download": "export CROWDIN_DOCUSAURUS_PROJECT_ID=$YOUR_CROWDIN_ID;
  export CROWDIN_DOCUSAURUS_API_KEY=$YOUR_CROWDIN_API_KEY; crowdin-cli --config ../crowdin.yaml download -b master"
},

這些命令須要擁有一個環境變量，用您的 crowdin 項目 id 和 api key（CROWDIN_PROJECT_ID，CROWDIN_API_KEY）設置。 你能夠像上面同樣內聯添加它們，或者將它們永久添加到你的 .bashrc 或 .bash_profile 中。

若是在計算機上運行多個本地化的 Docusaurus 項目，則應該將環境變量的名稱更改成惟一(CROWDIN_PROJECTNAME_PROJECT_ID, CROWDIN_PROJECTNAME_API_KEY)。

使用 CircleCI 自動同步文件

您可使用 CircleCI 網絡持續集成服務自動爲您的文件下拉和上傳翻譯。

首先，更新項目目錄中的 circle.yml 文件，包括上傳要翻譯的英文文件的步驟，以及使用 Crowdin CLI 下載已翻譯的文件。 這是一個 circle.yml 文件的例子：

machine:
  node:
    version: 6.10.3
  npm:
    version: 3.10.10

test:
  override:
    - "true"

deployment:
  website:
    branch: master
    commands:
      # 配置 git 用戶
      - git config --global user.email "test-site-bot@users.noreply.github.com"
      - git config --global user.name "Website Deployment Script"
      - echo "machine github.com login test-site-bot password $GITHUB_TOKEN" > ~/.netrc
      # 安裝 Docusaurus 並生成英文字符串文件
      - cd website && npm install && npm run write-translations && cd ..
      # 安裝 crowdin
      - sudo apt-get install default-jre
      - wget https://artifacts.crowdin.com/repo/deb/crowdin.deb -O crowdin.deb
      - sudo dpkg -i crowdin.deb
      # 翻譯 上傳/下載
      - crowdin --config crowdin.yaml upload sources --auto-update -b master
      - crowdin --config crowdin.yaml download -b master
      # 構建和發佈網站
      - cd website && GIT_USER=test-site-bot npm run publish-gh-pages

crowdin 命令使用 examples 腳本生成的 crowdin.yaml 文件。 它應該放在您的項目目錄中，以配置如何上傳/下載文件。

請注意，在 crowdin.yaml 文件中，CROWDIN_PROJECT_ID 和 CROWDIN_API_KEY 是Circle 中爲你的 Crowdin 項目設置的環境變量。 他們能夠在您的 Crowdin 項目設置中找到。

如今，Circle 將幫助您在構建您的網站以前自動獲取翻譯。 提供的 crowdin.yaml 文件會將翻譯後的文件複製到 website/translated_docs/ 中，i18n/en.json 字符串文件的翻譯版本將轉換爲 i18n/${language}.json。

若是你想在本地使用你的機器上的 Crowdin，你能夠安裝 Crowdin CLI 工具 並運行 circle.yaml 文件中的命令。 惟一的區別是你必須在 crowdin.yaml 文件中設置 project_identifier 和 api_key 值，由於你不會設置 Circle 環境變量。

版本化翻譯

若是您但願爲文檔進行翻譯和版本控制，請將如下部分添加到 crowdin.yaml 文件的末尾：

-
    source: '/website/versioned_docs/**/*.md'
    translation: '/website/translated_docs/%locale%/**/%original_file_name%'
    languages_mapping: *anchor

翻譯版本的文檔將被複制到 website/translated_docs/${language}/${version}/。

確保在您的 Crowdin 設置的翻譯部分中將 「重複字符串」 設置爲 「隱藏 - 全部重複將共享相同的翻譯」。 此設置將確保不一樣版本之間的相同字符串共享一個翻譯。

若是這篇文章對您有幫助, 感謝 下方點贊 或 Star GitHub: docusaurus-docs-Zh_CN 支持, 謝謝.