Skip to content

Commit f31a1c7

Browse files
DeeJayLSPskyace65
DeeJayLSP
authored and
skyace65
committed
Move localization with spreadsheets to its own page
1 parent 5bbe7cc commit f31a1c7

File tree

4 files changed

+97
-83
lines changed

4 files changed

+97
-83
lines changed

‎tutorials/assets_pipeline/importing_translations.rst‎

Lines changed: 10 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -31,86 +31,16 @@ each string. This allows you to revise the text while it is being
3131
translated to other languages. The unique ID can be a number, a string,
3232
or a string with a number (it's just a unique string anyway).
3333

34-
.. note:: If you need a more powerful file format, Godot also supports
35-
loading translations written in the gettext ``.po`` format. See
36-
:ref:`doc_localization_using_gettext` for details.
37-
38-
Translation format
39-
------------------
34+
Supported formats
35+
-----------------
4036

4137
To complete the picture and allow efficient support for translations,
4238
Godot has a special importer that can read CSV files. Most spreadsheet
43-
editors can export to this format, so the only requirement is that the files
44-
have a special arrangement. The CSV files **must** be saved with UTF-8 encoding
45-
without a `byte order mark <https://en.wikipedia.org/wiki/Byte_order_mark>`__.
46-
47-
CSV files must be formatted as follows:
48-
49-
+--------+----------+----------+----------+
50-
| keys | <lang1> | <lang2> | <langN> |
51-
+========+==========+==========+==========+
52-
| KEY1 | string | string | string |
53-
+--------+----------+----------+----------+
54-
| KEY2 | string | string | string |
55-
+--------+----------+----------+----------+
56-
| KEYN | string | string | string |
57-
+--------+----------+----------+----------+
58-
59-
The "lang" tags must represent a language, which must be one of the :ref:`valid
60-
locales <doc_locales>` supported by the engine, or they must start with an underscore (`_`),
61-
which means the related column is served as comment and won't be imported.
62-
The "KEY" tags must be unique and represent a string universally (they are usually in
63-
uppercase, to differentiate from other strings). These keys will be replaced at
64-
runtime by the matching translated string. Note that the case is important,
65-
"KEY1" and "Key1" will be different keys.
66-
The top-left cell is ignored and can be left empty or having any content.
67-
Here's an example:
68-
69-
+-------+-----------------------+------------------------+------------------------------+
70-
| keys | en | es | ja |
71-
+=======+=======================+========================+==============================+
72-
| GREET | Hello, friend! | Hola, amigo! | こんにちは |
73-
+-------+-----------------------+------------------------+------------------------------+
74-
| ASK | How are you? | Cómo está? | 元気ですか |
75-
+-------+-----------------------+------------------------+------------------------------+
76-
| BYE | Goodbye | Adiós | さようなら |
77-
+-------+-----------------------+------------------------+------------------------------+
78-
| QUOTE | "Hello" said the man. | "Hola" dijo el hombre. | 「こんにちは」男は言いました |
79-
+-------+-----------------------+------------------------+------------------------------+
80-
81-
The same example is shown below as a comma-separated plain text file,
82-
which should be the result of editing the above in a spreadsheet.
83-
When editing the plain text version, be sure to enclose with double
84-
quotes any message that contains commas, line breaks or double quotes,
85-
so that commas are not parsed as delimiters, line breaks don't create new
86-
entries and double quotes are not parsed as enclosing characters. Be sure
87-
to escape any double quotes a message may contain by preceding them with
88-
another double quote. Alternatively, you can select another delimiter than
89-
comma in the import options.
90-
91-
.. code-block:: none
92-
93-
keys,en,es,ja
94-
GREET,"Hello, friend!","Hola, amigo!",こんにちは
95-
ASK,How are you?,Cómo está?,元気ですか
96-
BYE,Goodbye,Adiós,さようなら
97-
QUOTE,"""Hello"" said the man.","""Hola"" dijo el hombre.",「こんにちは」男は言いました
98-
99-
CSV importer
100-
------------
101-
102-
Godot will treat CSV files as translations by default. It will import them
103-
and generate one or more compressed translation resource files next to it.
104-
105-
Importing will also add the translation to the list of
106-
translations to load when the game runs, specified in project.godot (or the
107-
project settings). Godot allows loading and removing translations at
108-
runtime as well.
109-
110-
Select the ``.csv`` file and access the **Import** dock to define import
111-
options. You can toggle the compression of the imported translations, and
112-
select the delimiter to use when parsing the CSV file.
113-
114-
.. image:: img/import_csv.webp
115-
116-
Be sure to click **Reimport** after any change to these options.
39+
editors can export to this format, so the only requirement is that the
40+
files have a special arrangement. See
41+
:ref:`doc_localization_using_spreadsheets` for detailed info on
42+
formatting and importing CSVs.
43+
44+
If you need a more powerful file format, Godot also supports loading
45+
translations written in the gettext ``.po`` format. See
46+
:ref:`doc_localization_using_gettext` for details.

‎tutorials/i18n/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Internationalization
88
:name: toc-learn-features-i18n
99

1010
internationalizing_games
11+
localization_using_spreadsheets
1112
localization_using_gettext
1213
locales
1314
pseudolocalization

‎tutorials/i18n/localization_using_gettext.rst‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,10 @@
33
Localization using gettext
44
==========================
55

6-
In addition to :ref:`doc_importing_translations` in CSV format, Godot
7-
also supports loading translation files written in the GNU gettext
8-
format (text-based ``.po`` and compiled ``.mo`` since Godot 4.0).
6+
In addition to importing translations in
7+
:ref:`CSV format <doc_localization_using_spreadsheets>`, Godot also
8+
supports loading translation files written in the GNU gettext format
9+
(text-based ``.po`` and compiled ``.mo`` since Godot 4.0).
910

1011
.. note:: For an introduction to gettext, check out
1112
`A Quick Gettext Tutorial <https://www.labri.fr/perso/fleury/posts/programming/a-quick-gettext-tutorial.html>`_.

‎tutorials/i18n/localization_using_spreadsheets.rst‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
.. _doc_localization_using_spreadsheets:
2+
3+
Localization using spreadsheets
4+
===============================
5+
6+
Spreadsheets are one of the most common formats for localizing games.
7+
In Godot, spreadsheets are supported through the CSV format. This
8+
guide explains how to work with CSVs.
9+
10+
Formatting
11+
----------
12+
13+
CSV files must be formatted as follows:
14+
15+
+--------+----------+----------+----------+
16+
| keys | <lang1> | <lang2> | <langN> |
17+
+========+==========+==========+==========+
18+
| KEY1 | string | string | string |
19+
+--------+----------+----------+----------+
20+
| KEY2 | string | string | string |
21+
+--------+----------+----------+----------+
22+
| KEYN | string | string | string |
23+
+--------+----------+----------+----------+
24+
25+
The "lang" tags must represent a language, which must be one of the :ref:`valid
26+
locales <doc_locales>` supported by the engine, or they must start with an underscore (`_`),
27+
which means the related column is served as comment and won't be imported.
28+
The "KEY" tags must be unique and represent a string universally (they are usually in
29+
uppercase, to differentiate from other strings). These keys will be replaced at
30+
runtime by the matching translated string. Note that the case is important,
31+
"KEY1" and "Key1" will be different keys.
32+
The top-left cell is ignored and can be left empty or having any content.
33+
Here's an example:
34+
35+
+-------+-----------------------+------------------------+------------------------------+
36+
| keys | en | es | ja |
37+
+=======+=======================+========================+==============================+
38+
| GREET | Hello, friend! | Hola, amigo! | こんにちは |
39+
+-------+-----------------------+------------------------+------------------------------+
40+
| ASK | How are you? | Cómo está? | 元気ですか |
41+
+-------+-----------------------+------------------------+------------------------------+
42+
| BYE | Goodbye | Adiós | さようなら |
43+
+-------+-----------------------+------------------------+------------------------------+
44+
| QUOTE | "Hello" said the man. | "Hola" dijo el hombre. | 「こんにちは」男は言いました |
45+
+-------+-----------------------+------------------------+------------------------------+
46+
47+
The same example is shown below as a comma-separated plain text file,
48+
which should be the result of editing the above in a spreadsheet.
49+
When editing the plain text version, be sure to enclose with double
50+
quotes any message that contains commas, line breaks or double quotes,
51+
so that commas are not parsed as delimiters, line breaks don't create new
52+
entries and double quotes are not parsed as enclosing characters. Be sure
53+
to escape any double quotes a message may contain by preceding them with
54+
another double quote. Alternatively, you can select another delimiter than
55+
comma in the import options.
56+
57+
.. code-block:: none
58+
59+
keys,en,es,ja
60+
GREET,"Hello, friend!","Hola, amigo!",こんにちは
61+
ASK,How are you?,Cómo está?,元気ですか
62+
BYE,Goodbye,Adiós,さようなら
63+
QUOTE,"""Hello"" said the man.","""Hola"" dijo el hombre.",「こんにちは」男は言いました
64+
65+
CSV importer
66+
------------
67+
68+
Godot will treat CSV files as translations by default. It will import them
69+
and generate one or more compressed translation resource files next to it.
70+
71+
Importing will also add the translation to the list of
72+
translations to load when the game runs, specified in project.godot (or the
73+
project settings). Godot allows loading and removing translations at
74+
runtime as well.
75+
76+
Select the ``.csv`` file and access the **Import** dock to define import
77+
options. You can toggle the compression of the imported translations, and
78+
select the delimiter to use when parsing the CSV file.
79+
80+
.. image:: img/import_csv.webp
81+
82+
Be sure to click **Reimport** after any change to these options.

0 commit comments

Comments
 (0)