本地化編輯器與說明文件

Godot 旨在使任何人都能進行遊戲開發,其中亦包含不懂或不習慣使用英語的人。因此,我們儘可能地讓許多最重要的資源都有各種語言的版本。感謝社群對翻譯提供的貢獻。

這些資源包含:

  1. Godot 編輯器界面 (約 15,000 個單詞)。

  2. 線上說明文件 (含編輯器手冊與教學,約 30,000 個單詞)。

  3. 類別參照文件 ,可在線上與編輯器內閱讀 (約 200,000 個單詞)。

為了處理翻譯,我們使用了 GNU gettext 檔案格式 (PO 檔) 以及開源的 ``Weblate <https://weblate.org>`__ 網頁本地化平台。通過 Weblate,我們便能與眾多貢獻者輕鬆協作來完成各個元件的翻譯,並保持這些翻譯在最新狀態。請點擊上方的連結來在 Weblate 上存取各個資源。

本頁提供了 Weblate 上一般性翻譯工作流程的概覽,並提供了一些資源特定的說明,如:如何如何處理關鍵字或本地化圖片。

小訣竅

翻譯所有官方的 Godot 內容是龐大的工程,因此我們建議以上面列出各資源的順序來優先處理:先翻譯編輯器界面、然後翻譯線上說明文件、最後如果有足夠多的翻譯任意能保持文件更新,才來翻譯類別參照文件。

使用 Weblate 來進行翻譯

雖然所有翻譯最後都會被放到 Godot Engine 與其說明文件的 Git 儲存庫中,但所有的翻譯更新都是以 Weblate 來處理的。因此我們並不允許直接往 Git 儲存庫上打開 Pull Request。翻譯是由維護人員手動在 Weblate 與 Godot 儲存庫間同步的。

因此你應先 在 Weblate 上註冊 才能參與貢獻 Godot 的翻譯。

登入後,請瀏覽想參與貢獻的 Godot 資源 (在本頁中我們會以 編輯器翻譯 為例) 來看看所有語言的列表:

../../_images/l10n_01_language_list.png

也參考

歡迎參考 Weblate 自己 翻譯工作流程 說明文件來瞭解更多詳情。

新增新語言

若你要翻譯的語言已在列表中,只需要點擊其名稱即可存取該語言的概覽,並請略過本段落。

若你的語言未在列表中,請滾動至所有語言列表的最下方,並點擊「Start new translation」按鈕,然後選擇想要翻譯的語言:

../../_images/l10n_02_new_translation.png

重要

若你的語言在不同的國家或地區內使用,而地區間的差異僅有一小部分,建議先將翻譯加到通用的變體 (如法語為 fr) 而不是地區變體 (如法文 (法國) 為 fr_FR 、法語 (加拿大) 為 fr_CA、法語 (阿爾及利亞) 為 fr_DZ))。

Godot 有大量需要翻譯的內容,因此這些對於地區變體的重複性工作應只在這些語言變體有足夠的差異時才進行。另外,若翻譯是在地區變體內完成的,則只有位於該地區的使用者才能自動使用到這些語言 (或是系統語言設定在該地區內的使用者)。

當這些地區變體的差異足夠大到能進行個別的翻譯時,我們建議儘可能先完成通用變體,然後將完整的翻譯複製到其他地區變體再進行相關的編輯。這個策略應適用於如西班牙語 (先進行 es,然後若有必要的話再將翻譯複製到 es_AR, es_ES, es_MX…等) 或葡萄牙語 (pt_BR v.s. pt_PT)。

翻譯界面

選擇語言後,可以看到翻譯狀態的概覽,包含還剩餘多少字串需要翻譯或需要審閱。可以點擊各個項目來瀏覽對應的列表。另外也可以點擊「Translate」按鈕來開始處理需要處理的字串列表。

../../_images/l10n_03_translation_overview.png

選擇列表並點擊「Translate」後,可以看到主要的翻譯界面,這個界面就是用來處理所有翻譯工作的:

../../_images/l10n_04_translation_interface.png

在本頁中有:

  • A toolbar which lets you cycle through strings of the current list, change to another predefined list or do a custom search, etc. There is also a "Zen" editing mode with a simplified interface.

  • 目前實際在處理的字串位於「Translation」面板內。預設情況下,這裡應該會顯示英語的原始字串以及一個用於你的語言的編輯框。若你也熟悉其他語言,可以在使用者設定內加上其他語言來協助你在翻譯上取得更多脈絡。編輯好目前字串後,請點擊「Save」按鈕來確認更改並移至下一個欄位。或者,也可以使用「Skip」按鈕來跳過翻譯。「Needs editing」勾選框表示原始字串經過更新,因此該翻譯需要進行審閱來處理這些更新 (用 PO 的語言來說,這些翻譯是所謂的「Fuzzy」字串)。這些字串在被修正前將不會被用於翻譯。

  • 下方的面板有許多的工具可以協助進行翻譯,如附近字串可提供上下文 (這些字串通常為同一個編輯器工具或同一個說明文件頁面內的,因此這些字串可能會使用類似的術語)、來自其他翻譯人員的留言、機器翻譯、以及其他現有語言中該字串的翻譯列表。

  • 右上方的「Glossary」顯示了之前加入的術語,這些術語為目前字串中有出現的。舉例來說,如果你與其他翻譯人員決定為 Godot 的「Node」術語使用特定的翻譯,則可以將其加入 Glossary 來確保其他翻譯人員使用相同的翻譯慣例。

  • 右下方的面板包含了原始字串的資訊。最重要的項目為「source string location」,其中包含了 GitHub 上原始字串的連結。可能需要在該頁面中搜尋字串才能找到該字串與其附近的上下文。

找出原始內容

PO 檔是原始字串 (msgid) 的有序列表,以及其翻譯 (msgstr)。在預設情況下,Weblate 會以其順序顯示這些字串。因此,可以通過字串的順序來瞭解該內容在 PO 檔內是如何排列的,並可通過該順序來找出原始內容並於翻譯時作為參考。

重要

許多的單詞根據其上下文都會都不同的翻譯,因此在翻譯時參考原始上下文是重要的。如果用了不對的翻譯對使用者來說並不好,且比起將這些字串保留為英語來說,使用者可能更難理解錯誤的翻譯。通過瞭解上下文也能讓翻譯工作更輕鬆愉快,而且你也能直接看到這些翻譯在其脈絡中是否合理。

  • 編輯器界面的翻譯樣板時通過以 字母順序 剖析所有 C++ 原始碼來產生的。因此,所有在相同檔案內定義的字串都會被放在一起。舉例來說,若「source string location」顯示為 editor/code_editor.cpp ,則目前的字串 (以及其相鄰的字串) 都時定義在 editor/code_editor.cpp 程式碼內的,而該字串也就是與 Godot 程式碼編輯器相關的 (GDScript, Shader)。

  • The online documentation's translation template is generated from the source RST files in the same order as seen in the table of contents, so for example the first strings are from the front page of the documentation. The recommended workflow is therefore to find a unique string corresponding to a page that you want to translate, and then translate all the strings with the same source string location while comparing with the online version of that page in English. An example of source string location could be getting_started/step_by_step/nodes_and_scenes.rst for the page 節點與場景.

  • 類別參照文件樣板是以 字母順序 從原始 XML 檔產生的,該順序也與線上版本的目錄順序相同。因此可以通過某個類別的簡介來找到相應的原始字串,並以該原始字串來搜尋第一個翻譯字串,然後該列表的所有其他說明在 Weblate 上就應該位於該字串後方。舉例來說,class_Node2D` 類別說明的 Source string location 應為 doc/classes/Node2D.xml

A handy tool to locate specific pages/classes is to use Weblate's advanced search feature, and especially the "Location strings" query (which can also be used with the location: token, e.g. location:nodes_and_scenes.rst):

../../_images/l10n_05_search_location.png ../../_images/l10n_06_browse_by_location.png

備註

When a given source string is used in multiple source locations, they will all be concatenated into one. For example, the above location:nodes_and_scenes.rst query would land first on the "Introduction" source string which is used in dozens of pages, including some that come before nodes_and_scenes.rst in the template. Clicking the "Next" button then brings us to the "Scene and nodes" title string displayed above. So it may happen that a given paragraph or section title is not at the location you'd expect it when reading the online version of a page.

遵守原本的標記語法

各個翻譯資源的原始格式都不同。瞭解各個資源使用的標記語言可以避免在翻譯中出現語法錯誤。

編輯器界面 (C++)

編輯器翻譯來自 C++ 字串,這些字串可能會使用到:

  • C 語言格式規範%s (字串) 或 %d (數字) 。這些規範會在執行階段被替取代,在翻譯時應將這些符號保留在翻譯內,並讓這些字串被取代掉之後還能保持其原意。如果從句子來看不清楚會被取代成什麼內容的話,則可能會需要參考 Source string location。範例 (%s 會被取代為檔案名稱或路徑):

    # PO file:
    "There is no '%s' file."
    
    # Weblate:
    There is no '%s' file.
    
  • C 語言逸出字元\n (換行) 或 \t (Tab 字元)。在 Weblate 編輯器中, \n 字元會被取代為 (Return),而 \t 則會被取代為 。Tab 字元並補償用,但在翻譯時應確保換行的使用與原始英語字串中使用的方式一致 (如果未正確使用則 Weblate 會顯示警告)。換行資源有時候也會被用來作為垂直空白,或是當字串太長的話用來手動斷行 (常用於編輯器翻譯)。如:

    # PO file:
    "Scene '%s' is currently being edited.\n"
    "Changes will only take effect when reloaded."
    
    # Weblate:
    Scene '%s' is currently being edited.↵
    Changes will only take effect when reloaded.
    

備註

Only logical order of the characters matters, in the right-to-left text, format specifiers may be displayed as s%.

顯示說明文件 (RST)

線上說明文件的翻譯源自 reStructuredText (RST) 檔。RST 檔也使用了自己的標記語法來格式化文字、建立內部或外部連結…等。下列為翻譯:

# "development" is styled bold.
# "Have a look here" is a link pointing to https://docs.godotengine.org/en/latest.
# You should translate "Have a look here", but not the URL, unless there is
# a matching URL for the same content in your language.
# Note: The `, <, >, and _ characters all have a meaning in the hyperlink
# syntax and should be preserved.

Looking for the documentation of the current **development** branch?
`Have a look here <https://docs.godotengine.org/en/latest>`_.

# "|supported|" is an inline reference to an image and should stay unchanged.
# "master" uses the markup for inline code, and will be styled as such.
# Note: Inline code in RST uses 2 backticks on each side, unlike Markdown.
# Single backticks are used for hyperlinks.

|supported| Backwards-compatible new features (backported from the ``master``
branch) as well as bug, security, and platform support fixes.

# The :ref: Sphinx "role" is used for internal references to other pages of
# the documentation.
# It can be used with only the reference name of a page (which should not be
# changed), in which case the title of that page will be displayed:

See :ref:`doc_ways_to_contribute`.

# Or it can be used with an optional custom title, which should thus be translated:

See :ref:`how to contribute <doc_ways_to_contribute>`.

# You may encounter other Sphinx roles, such as :kbd: used for shortcut keys.
# You can translate the content between backticks to match the usual key names,
# if it's different from the English one.

Save the scene. Click Scene -> Save, or press :kbd:`Ctrl + S` on Windows/Linux
or :kbd:`Cmd + S` on macOS.

也參考

請參考 reStructured Text primer (英語) 以快速瞭解可能出現在原始字串內的 RST 標記語言。在翻譯時可能會遇到特殊的行內標記 (粗體、斜體、行內程式碼) 以及內部與外部超連結標記。

類別參照文件 (BBCode)

類別參照文件是放在 Godot 主儲存庫中的說明文件,使用 XML 檔案,並使用類似 BBCode 的標記語言來格式化字串與進行內部參照。

有些標籤來自原版 BBCode (如 [b]粗體[/b][i]Italics[/i]),而其他標籤則為 Godot 專用的,用來提供進階功能,如行內程式碼 (如 [code]true[/code]) 、到其他類別的連結 (如 [Node2D]) 或到指定類別屬性的連結 (如 [member Node2D.position]) 、以及多行程式碼區塊。如:

Returns a color according to the standardized [code]name[/code] with [code]alpha[/code] ranging from 0 to 1.
[codeblock]
red = ColorN("red", 1)
[/codeblock]
Supported color names are the same as the constants defined in [Color].

在上方的範例中,[code]name[/code], [code]alpha[/code][Color] 不應 進行翻譯,因為這些字串是用來引用其對應的引數名稱與 Godot API 中的類別。同樣地,[codeblock] 中的內容也不應翻譯,如 ColorN 為 GodotAPI 的函式,而 "red" 為該函式支援的其中一個顏色名稱。要翻譯的話頂多只能翻譯保存其結果的變數名稱 (red = ...)。

另外也請注意,在 XML 中每一行都是一個獨立的段落,因此若原始翻譯中沒有斷行的話,就不應加上新的斷行。

也參考

See our documentation for class reference writers for the list of BBCode-like tags which are used throughout the class reference.

離線翻譯與測試

雖然我們建議使用 Weblate 的界面來撰寫翻譯,但也可以下載 PO 檔到本機上來以慣用的 PO 編輯器進行翻譯,如 PoeditLokalize

要下載 PO 檔到本機上,請瀏覽對應語言的翻譯概覽頁面,然後選擇「Files」選單中的第一項:

../../_images/l10n_07_download_po_file.png

完成一系列的編輯後,請使用相同選單中的「Upload translation」項目並選擇編輯好的檔案。上傳模式請選擇「Adds as translation」。

備註

如果從下載 PO 檔到上傳編輯後版本間經過了一段時間,翻譯內容就有可能其他貢獻者複寫。這也是我們建議使用線上界面的原因,因為這樣一來就能確保在處理的為最新版本。

若想在本機上測試所做出的更改 (尤其是編輯器翻譯),可以下載 PO 檔並 從原始碼編譯 Godot

重新命名 PO 檔為 <lang>.po (如世界語為 eo.po),並將該檔案放置於 editor/translations/ 資料夾內 (GitHub) 。

也可以以相同的名稱來測試類別參照文件,更改 PO 檔案的名稱,然後將該檔案放置於 doc/translations/ 資料夾 (GitHub)。

本地化說明文件圖片

線上說明文件包含了許多圖片,這些圖片可能時 Godot 編輯器的截圖、自製圖像、或是其他類型的圖片內容。有些圖片包含文字,因此可能需要翻譯為你使用的語言。

圖片翻譯的部分不是通過 Weblate 處理的,而是直接通過 godot-docs-l10n 這個 Git 儲存庫處理的。該儲存庫中包含了所有從 Weblate 同步來的說明文件翻譯。

備註

此一工作流程並不直觀,且需要一些 Git 的知識。我們計劃要製作一個簡單的 Web 工具來更方便地處理圖片本地化,藉此簡化這些步驟。

若要翻譯圖片,首先應在其原始英語說明文件找到這些圖片。要找出圖片檔案,請先在英語版說明文件中瀏覽相關的頁面,如 First look at Godot's editor 。然後點擊右上角的「Edit on GitHub」連結:

../../_images/l10n_08_edit_on_github.png

在 GitHub 上,請點擊欲翻譯的圖片,然後點擊「Download」按鈕來將該圖片下載到本機保存,然後通過圖片編輯工具來編輯該圖片。請記下該圖片的完整路徑,接下來還會用到 (本例中為 getting_started/step_by_step/img/project_manager_first_open.png)。

../../_images/l10n_09_path_to_image.png

建立該圖片的本地化版本,可以通過編輯英語版圖片來製作,若該圖片為截圖的話,則直接以你的語言來在編輯器內截圖。有些圖片也有 SVG 格式的原始檔,因此瀏覽 img/ 資料夾內來看看是否有原始檔。

將本地化的圖片以與原始圖片相同的名稱保存,但應在副檔名前加上語言代碼,如 project_manager_first_open.png 的法語本地化版本應為 project_manager_first_open.fr.png

最後,在 godot-docs-l10n 中,在 images 子資料夾中建立與原始圖片相同的資料夾結構 (GitHub),然後將翻譯好的圖片放在這裡。在本例中,最終的結果應放置為 images/getting_started/step_by_step/img/project_manager_first_open.fr.png

為其他圖片重複此一過程,然後 開啟 Pull Request