Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

使用試算表進行在地化

試算表是遊戲在地化最常見的格式之一。在 Godot 中，透過 CSV 格式支援試算表。此指南將說明如何使用 CSV。

CSV 檔案必須以沒有 byte order mark 的 UTF-8 編碼儲存。

警告

預設情況下，Microsoft Excel 會以 ANSI 而非 UTF-8 儲存 CSV。雖然沒有內建的方式可直接以 UTF-8 儲存，但可依此處的替代做法處理。

建議改用 LibreOffice 或 Google 試算表。

格式

CSV 檔案必須使用如下格式：

keys	<語言1>	<語言2>	<語言N>
KEY1	字串	字串	字串
KEY2	字串	字串	字串
KEYN	字串	字串	字串

The "lang" tags must represent a language, which must be one of the valid locales supported by the engine, or they must start with an underscore (_), which means the related column is served as comment and won't be imported. The KEY tags must be unique and represent a string universally. By convention, these are usually in uppercase to differentiate them from other strings. These keys will be replaced at runtime by the matching translated string. Note that the case is important: KEY1 and Key1 will be different keys. The top-left cell is ignored and can be left empty or having any content. Here's an example:

keys	en	es	ja
GREET	Hello, friend!	Hola, amigo!	こんにちは
ASK	How are you?	Cómo está?	元気ですか
BYE	Goodbye	Adiós	さようなら
QUOTE	"Hello" said the man.	"Hola" dijo el hombre.	「こんにちは」男は言いました

下面是同一份 CSV 轉成純文字檔的長相，這通常是你用試算表編輯好之後存檔的結果。如果你直接編輯純文字 CSV，要特別注意：只要內容有逗號、換行或雙引號，整段一定要加雙引號，否則會被當成多個欄或多列，雙引號本身要用兩個連寫（"Hello" 變成 ""Hello""）。也可以在 Godot 匯入時改用逗號以外的分隔符。

keys,en,es,ja
GREET,"Hello, friend!","Hola, amigo!",こんにちは
ASK,How are you?,Cómo está?,元気ですか
BYE,Goodbye,Adiós,さようなら
QUOTE,"""Hello"" said the man.","""Hola"" dijo el hombre.",「こんにちは」男は言いました

Specifying plural forms

Since Godot 4.6, it is possible to specify plural forms in CSV files.

This is done by adding a column named ?plural anywhere in the table (except on the first column, which is reserved for translation keys). By convention, it's recommended to place it on the second column. Note that in the example below, the key column is the one that contains English localization.

en,?plural,fr,ru,ja,zh
?pluralrule,,nplurals=2; plural=(n >= 2);,,
There is %d apple,There are %d apples,Il y a %d pomme,Есть %d яблоко,リンゴが%d個あります,那里有%d个苹果
,,Il y a %d pommes,Есть %d яблока,,
,,,Есть %d яблок,,

備註

Automatic Control translation is not supported when using plural forms. You must translate the string manually using tr_n().

Specifying translation contexts

Since Godot 4.6, it is possible to specify translation contexts in CSV files. This can be used to disambiguate identical source strings that have different meanings. While this is generally not needed when using translation keys LIKE_THIS, it's useful when using plain English text as translation keys.

This is done by adding a column named ?context column anywhere in the table (except on the first column, which is reserved for translation keys). By convention, it's recommended to place it on the second column, or after ?plural if it's also used. Note that in the example below, the key column is the one that contains English localization.

en,?context,fr,ru,ja,zh
Letter,Alphabet,Lettre,Буква,字母,字母
Letter,Message,Courrier,Письмо,手紙,信件

備註

Automatic Control translation is not supported when using context. You must translate the string manually using tr() or tr_n().

CSV 匯入器

Godot 會自動把 CSV 檔當作翻譯檔來處理，然後在同一目錄下產生一個或多個翻譯資源檔（壓縮格式）。

匯入時也會自動把這份翻譯檔加進專案設定（project.godot／專案選單）裡的載入清單。Godot 也支援在執行時動態載入或卸載翻譯。

Select the .csv file and access the Import dock to define import options. You can toggle the compression of the imported translations, and select the delimiter to use when parsing the CSV file.

Be sure to click Reimport after any change to these options.

Loading the CSV file as a translation

Once a CSV file is imported, it is not automatically registered as a translation source for the project. Remember to follow the steps described in 配置匯入的譯文 so that the translation is actually used when running the project.