翻譯內容¶

雖然英文是軟體開發人員非常常用的語言，但仍有許多開發人員不會說英文或說得不流利。對開發人員而言，這是一個無障礙的問題 - 因此，我們希望提供儘可能多種語言的文件。

不幸的是，BeeWare的核心團隊大部分都是說英語的單語人士。我們需要您的幫助，將我們的文件翻譯成其他語言。

我們使用 Weblate 來管理我們的翻譯。Weblate 是一種工具，讓我們可以將文件中的每一段內容都視為待辦事項清單，一次完成一個。

我們使用 DeepL 進行機器翻譯，以產生翻譯的初稿。機器翻譯遠非完美，但通常作為初稿已經很好了。我們期望這些機器翻譯會在必要時進行編輯、審查和改進。

貢獻翻譯¶

翻譯內容

開始翻譯¶

如果您想為BeeWare的翻譯工作出一份力，您需要在Weblate上註冊一個帳號。如果您目前沒有帳號，請建立新帳號；然後讓我們知道您有興趣幫忙翻譯。

有兩種方式可以讓我們知道您想要協助翻譯：

如果您在 Discord 上，請加入 BeeWare 伺服器，並前往 #translations 頻道。
如果您不在 Discord 上，可以在 BeeWare 套件庫上建立新問題。

在這兩種情況下，請留下包含下列資訊的訊息：

您的 Weblate 使用者名稱
您計劃翻譯內容的語言

一旦我們得到這些資訊，我們就會將您加入團隊。

新增翻譯¶

如果您打算幫忙的語言還未存在，在開始之前還需要一些額外的步驟：

建立 /docs/mkdocs.language-code.yml 檔案，其中包含特定語言的內容。
更新 tox.ini 以包含新的語言建立指令。
更新 /docs/config.yml，將語言包含在 extra: alternate: 下。

以下以德語為例，示範必要的變更；德語翻譯版已經存在；請針對您的目標語言，取代對德語、de 或其他內容的引用。

新的 MkDocs 設定檔¶

首先，在 docs 目錄中建立一個名為 mkdocs.de.yml 的新檔案，內容如下：

INHERIT: config.yml
site_name: BeeWare Dokumentation
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

以下是此檔案的內容：

這個檔案繼承了 config.yml 的設定內容。
會翻譯 site_name 值。
site_url 值是專案網站的 URL，接著是語言代碼。
docs_dir` 應該是語言代碼。
theme: language: 值應該是 MkDocs Material theme 所指定的語言代碼。對大多數語言而言，這與 docs_dir 語言代碼相同；但對某些語言 (尤其是像 zh_CN 這種有區域性變異的語言) 而言，則會有差異。
extra: translation_type: 應該是 machine，直到翻譯首次達到 100%，此時它應該是 human。如果它倒退到低於 90%，就會從 human 回復到 machine。

更新 `tox.ini¶

您需要對 tox.ini 檔案進行幾項變更。

您可以添加以下內容：

新的語言代碼環境標誌到以 [testenv:docs 開頭的標頭行，語言代碼前面加上 -，不含空格，例如 -de。
新的語言代碼排除到第一個指令，以 !lint 開頭，前面加上 -!，不含空格，例如 -!de。
新的語言代碼到以 translate : build_po_translations 開頭的行尾。
新的語言代碼到以 translate : update_machine_translations 開頭的行尾
在其他現有的特定語言指令之後，新增一個新指令，例如以 de : build_md_translations 開頭的德文指令，將這些指令的內容與新的語言代碼相匹配。
新的語言代碼到以 all,serve : 開頭的行尾。

更新 `config.yml`¶

將語言加入 config.yml 中，使其顯示在標頭的語言選擇器中。找到以extra:開頭的部分，然後再找到以alternate:開頭的小節。對於德語，您可以新增以下內容：

    - name: Deutsch
      link: /de/
      lang: de

語言名稱應翻譯為該語言。連結必須包含 /。

新的語言現在可以開始翻譯了。

翻譯指引¶

當您加入團隊後，就可以登入 Weblate 並開始進行翻譯字串的工作。

語調與逐字翻譯¶

保持英文文本的語調比追求一字不差的翻譯更重要。我們嘗試在內容上表現得友善且有點口語化；在您的翻譯中嘗試維持這種精神。

如果英文文本中包含強烈的英文慣用語，如果您的語言中有類似的慣用語也同樣適用，請不要覺得必須保留該慣用語。如果英文文本中的詞彙或詞組是特別的成語或俚語，請不要害怕告訴我們應該考慮做出修改。即使對於英語使用者而言，成語和俚語也會造成困難。有時我們需要修改英文原文，讓翻譯者和讀者都能更直覺地理解。

我應該翻譯嗎？¶

下列項目不應 _ 翻譯或更新：

命令。例如，在 "You should run briefcase create\.「中，應只翻譯」You should run"。
名稱空間，例如類別、方法或屬性名稱。
** 連結 URL**。標準的 Markdown 連結應該在 Weblate 中顯示為 [連結文字]{1}，其中 1 是連結在字串中的位置，並參照其他可能的連結。如果完整的 URL 包含在字串中，如 [連結文字](https://example.com)，在翻譯時應跳過 URL。
** 包含類別、方法或屬性名稱的參考連結**。這些連結應保持原樣，包括反標記。這裡顯示的範例連結的每個部分都不會被翻譯。
```
[`Class.attribute`][Class.attribute]
```
參考連結的連結內容。例如，以下內容中的 link-content 將被跳過：
```
[Link text][link-content]
```
Jinja 指令。這是包裝在兩對相對的大括弧內的任何內容，或是包裝在一對相對的單一大括弧內的任何內容，兩端都有百分號。注意：在此加入語法範例會導致 Macros 外掛嘗試渲染該語法；範例請參閱 Macros 文件。
** 自訂錨點**。它們會出現在標題之後或某些內容之上，格式為 { #anchor }。
訓誡語法。在下面的範例中，「訓誡」一詞不應該被翻譯。這適用於所有樣式的訓誡，包括註解、警告等。有關翻譯其他內容的資訊，請參閱下一節。
```
/// admonition | Page Title

Content.

///
```
反標記。它們應保持為反標記；它們用於格式化內嵌程式碼和程式碼區塊。
包含外部內容的語法。這是與 -8<- 在同一行的任何內容，或是在兩行分開的 -8<- 之間的內容。

下列項目 _ 應該翻譯：

** 連結文字**。在連結語法中，文字在URL之前，並用括弧括起，如[連結文字](URL)。標準的 Markdown 連結應該在 Weblate 中顯示為 [連結文字]{1}，其中 1 是連結在字串中的位置，並參照其他可能的連結。
參考連結文字。例如，Link text 將在以下內容中被翻譯為：
```
[Link text][link-content]
```
告誡標題和內容。在前面的訓誡範例中，「頁面標題」和「內容」應該被翻譯。

Weblate¶

我們使用 Weblate 進行內容翻譯。當我們新增翻譯時，我們會使用 DeepL 進行機器翻譯，以產生第一遍翻譯。這表示，一般而言，您要翻譯的內容已經由機器翻譯完成。我們的期望是，身為譯者的您將審閱、編輯並改善現有的機器翻譯。

Weblate 會逐個字串處理。它會對變更進行批次處理，每隔幾小時就會提交一次批量提交，其中包含在該時間間隔內發生變更的所有字串。因此，您的變更可能需要幾小時才能顯示在網站上，但您可以預期更新會在四小時內出現。

若超過上述時間後，您的修改仍未顯示，可能原因在於標記錯誤導致該語言的文件建置失敗。任何字串中的標記問題都會阻擋整個翻譯版本公開發布。您可持續關注您語言的建置頁面，確認是否已成功建置。連結格式類似此法語建置頁面連結：https://app.readthedocs.org/projects/beewareorg/; 請將語言代碼替換為您所屬語言，即可查看對應的建置頁面。此頁面將顯示網站最新建置狀態。若建置失敗，請查閱建置日誌以釐清問題根源。