使用 gettext 進行在地化

除了支援 CSV 格式的 匯入翻譯 外，Godot 也支援載入 GNU gettext 格式的翻譯檔案（以文字為基礎的 .po 以及自 Godot 4.0 起支援的編譯 .mo 檔案）。

備註

如需 gettext 的基礎介紹，請參考 A Quick Gettext Tutorial。雖然該教學以 C 專案為例，但大多數內容同樣適用於 Godot（除了 xgettext 相關部分）。

優點

  • gettext 是一種標準格式，可以使用任何文字編輯器，或如 Poedit 這類圖形介面編輯器進行編輯。

  • 如 Transifex 及 Weblate 等翻譯平台也支援 gettext，讓多人協作在地化更加便利。

  • 與 CSV 相比，gettext 更適合與如 Git 這類版本控制系統配合，每種語言各有獨立的訊息檔案。

  • 多行字串在 gettext 檔案中比在 CSV 檔案中更容易編輯。

缺點

  • gettext 格式比 CSV 複雜，新手在地化人員可能較難上手。

  • 維護在地化檔案的人員需要在系統上安裝 gettext 工具。不過，由於 Godot 支援以文字為基礎的 .po 檔案，譯者無需安裝 gettext 工具也可直接測試翻譯成果。

安裝 gettext 工具

部分維護操作（如更新訊息檔案）需使用命令列 gettext 工具，因此強烈建議安裝。

  • Windows： 請從 此頁面 下載安裝程式。各種架構與二進位型式（動態或靜態）皆可使用；若不確定，建議選擇 64 位元靜態安裝程式。

  • macOS： 可透過 Homebrew 使用 brew install gettext 指令安裝，或使用 MacPorts 的 sudo port install gettext 指令。

  • Linux： 在大多數發行版上，請透過套件管理器安裝 gettext 套件。

建立 PO 範本

用編輯器自動產生

自 Godot 4.0 起，編輯器可根據指定的場景與 GDScript 檔案自動產生 PO 範本。此 POT 產生亦支援翻譯語境與複數形式（如於腳本中使用 tr() 的第二參數或 tr_n() 方法）。

開啟專案設定的 在地化 > POT 產生 分頁，點選 新增… 按鈕，指定專案中含有可在地化字串的場景與腳本路徑：

於專案設定的「在地化 > POT 產生」分頁中建立 PO 範本

於專案設定的 在地化 > POT 產生 分頁中建立 PO 範本

新增至少一個場景或腳本後，請點選右上角的 產生 POT，再指定輸出檔案的路徑。該檔案可存放於專案目錄任一位置，但建議集中於如 locale 的子目錄，因每種語言環境將有獨立檔案。

關於在 GDScript 檔案中加入譯者註解或排除特定字串不加入 PO 範本，請參閱下方 從 GDScript 檔案擷取可在地化字串。

接著，請參考 如何從 PO 範本建立訊息檔。

備註

每當你變更可在地化字串、或新增場景、腳本後，請記得重新產生 PO 範本。否則，新字串將無法在地化，且舊有字串的翻譯也無法及時更新。

手動建立

如果自動產生無法滿足需求，你也可以用文字編輯器手動建立 PO 範本。檔案可放在專案目錄任意位置，但建議集中於子目錄，以利各語言版本管理。

在專案目錄下建立名為 locale 的資料夾，並於該資料夾內儲存名為 messages.pot 的檔案，內容如下：

# Don't remove the two lines below, they're required for gettext to work correctly.
msgid ""
msgstr ""

# Example of a regular string.
msgid "Hello world!"
msgstr ""

# Example of a string with pluralization.
msgid "There is %d apple."
msgid_plural "There are %d apples."
msgstr[0] ""
msgstr[1] ""

# Example of a string with a translation context.
msgctxt "Actions"
msgid "Close"
msgstr ""

gettext 的訊息由 msgid 與 msgstr 配對組成。msgid 是原文（通常為英文），msgstr 則是對應的譯文。

警告

PO 範本檔（.pot）裡的 msgstr 值應 一律 保持空白。在地化內容則會填寫於產生的 .po 檔案中。

從 PO 範本建立訊息檔案

msginit 指令可將 PO 範本轉換為訊息檔案。例如，若要建立法文翻譯檔，請在 locale 目錄下執行以下指令：

msginit --no-translator --input=messages.pot --locale=fr

上述指令會在同目錄下產生名為 fr.po 的檔案。

你也可以用 Poedit 圖形介面操作，或將 POT 檔上傳至你選用的協作平台來建立。

在 Godot 載入訊息檔案

若要將訊息檔註冊為專案翻譯，請打開 專案設定，進入 在地化 分頁。在 翻譯 區域點選 新增...，於檔案對話框選擇 .po 或 .mo 檔案。語言區域會根據訊息檔中的 "Language: <code>\n" 屬性自動判斷。

備註

更多關於在 Godot 匯入與測試翻譯的資訊，請參閱 將遊戲國際化。

依照 PO 範本更新訊息檔案

更新 PO 範本後，也要同步更新各語言訊息檔，以包含新字串並移除已不存在的字串。此操作可用 msgmerge 工具自動完成：

# The order matters: specify the message file *then* the PO template!
msgmerge --update --backup=none fr.po messages.pot

若需保留原始訊息檔備份（如本例將備份為 fr.po~），請移除 --backup=none 參數。

備註

執行 msgmerge 後，若原文有改動，則對應譯文前會自動添加 "fuzzy" 註解。這表示翻譯需檢查修正，否則可能已不精確。

帶有「fuzzy」註解的字串將**不會**被 Godot 讀取，直到翻譯被更新且「fuzzy」註解被移除。

檢查 PO 檔案或範本有效性

你可以用下列指令檢查 gettext 檔案語法是否正確：

msgfmt fr.po --check

如有語法錯誤或警告，將顯示於終端機，否則 msgfmt 不會有任何輸出。

使用二進位 MO 檔案（僅適用於大型專案）

若你的專案有成千上萬條需翻譯字串，建議使用二進位（編譯後）MO 檔案取代文字型 PO 檔案。MO 檔案體積更小、讀取速度更快。

可用下列指令產生 MO 檔案：

msgfmt fr.po --no-hash -o fr.mo

若 PO 檔案有效，這條指令會在同資料夾下產生 fr.mo，可如上所述載入 Godot。

建議將原始 PO 檔案納入版本控制，便於日後維護翻譯。若遺失原始 PO 檔需將 MO 檔反編譯回文字 PO 檔，可用下列指令：

msgunfmt fr.mo > fr.po

反編譯回來的檔案不會包含註解或 fuzzy 標記，因為這些資訊原本就不會被編入 MO 檔案中。

從 GDScript 檔案擷取可在地化字串

內建的 編輯器外掛 可識別多種原始碼模式，從 GDScript 檔案中擷取可在地化字串，包含但不限於下列類型：

  • tr() 、 tr_n() 、 atr() 及 atr_n() 呼叫;

  • 設定 text 、 placeholder_text 、 tooltip_text 屬性時;

  • 呼叫 add_tab() 、 add_item() 、 set_tab_title() 等方法;

  • FileDialog 篩選字串，如 "*.png ; PNG Images"。

備註

參數或右側運算元必須是常數字串，否則編輯器外掛將無法解析並會忽略該表達式。

若外掛擷取了不需翻譯的字串，可在其前方加上 NO_TRANSLATE 註解來忽略。你也可以用 TRANSLATORS: 註解提供補充說明給譯者。這些註解必須與被識別的程式碼在同一行或直接前一行。

$CharacterName.text = "???" # NO_TRANSLATE

# NO_TRANSLATE: Language name.
$TabContainer.set_tab_title(0, "Python")

item.text = "Tool" # TRANSLATORS: Up to 10 characters.

# TRANSLATORS: This is a reference to Lewis Carroll's poem "Jabberwocky",
# make sure to keep this as it is important to the plot.
say(tr("He took his vorpal sword in hand. The end?"))