Skip to content

Commit f883ca5

Browse files
skyace65skyace65
authored
Merge pull request godotengine#5900 from DeeJayLSP/spreadsheet_personal_space
Move localization with spreadsheets to its own page
2 parents 5bbe7cc + 4e76070 commit f883ca5

File tree

5 files changed

+109
-83
lines changed

5 files changed

+109
-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/assets_pipeline/img/import_csv.webp renamed to ‎tutorials/i18n/img/import_csv.webp

File renamed without changes.

‎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: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
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+
The CSV files **must** be saved with UTF-8 encoding
11+
without a `byte order mark <https://en.wikipedia.org/wiki/Byte_order_mark>`__.
12+
13+
.. warning::
14+
15+
By default, Microsoft Excel will always save CSV files with ANSI encoding
16+
rather than UTF-8. There is no built-in way to do this, but there are
17+
workarounds as described
18+
`here <https://stackoverflow.com/questions/4221176/excel-to-csv-with-utf8-encoding>`__.
19+
20+
We recommend using `LibreOffice <https://www.libreoffice.org/>`__ or Google Sheets instead.
21+
22+
Formatting
23+
----------
24+
25+
CSV files must be formatted as follows:
26+
27+
+--------+----------+----------+----------+
28+
| keys | <lang1> | <lang2> | <langN> |
29+
+========+==========+==========+==========+
30+
| KEY1 | string | string | string |
31+
+--------+----------+----------+----------+
32+
| KEY2 | string | string | string |
33+
+--------+----------+----------+----------+
34+
| KEYN | string | string | string |
35+
+--------+----------+----------+----------+
36+
37+
The "lang" tags must represent a language, which must be one of the :ref:`valid
38+
locales <doc_locales>` supported by the engine, or they must start with an underscore (`_`),
39+
which means the related column is served as comment and won't be imported.
40+
The "KEY" tags must be unique and represent a string universally (they are usually in
41+
uppercase, to differentiate from other strings). These keys will be replaced at
42+
runtime by the matching translated string. Note that the case is important,
43+
"KEY1" and "Key1" will be different keys.
44+
The top-left cell is ignored and can be left empty or having any content.
45+
Here's an example:
46+
47+
+-------+-----------------------+------------------------+------------------------------+
48+
| keys | en | es | ja |
49+
+=======+=======================+========================+==============================+
50+
| GREET | Hello, friend! | Hola, amigo! | こんにちは |
51+
+-------+-----------------------+------------------------+------------------------------+
52+
| ASK | How are you? | Cómo está? | 元気ですか |
53+
+-------+-----------------------+------------------------+------------------------------+
54+
| BYE | Goodbye | Adiós | さようなら |
55+
+-------+-----------------------+------------------------+------------------------------+
56+
| QUOTE | "Hello" said the man. | "Hola" dijo el hombre. | 「こんにちは」男は言いました |
57+
+-------+-----------------------+------------------------+------------------------------+
58+
59+
The same example is shown below as a comma-separated plain text file,
60+
which should be the result of editing the above in a spreadsheet.
61+
When editing the plain text version, be sure to enclose with double
62+
quotes any message that contains commas, line breaks or double quotes,
63+
so that commas are not parsed as delimiters, line breaks don't create new
64+
entries and double quotes are not parsed as enclosing characters. Be sure
65+
to escape any double quotes a message may contain by preceding them with
66+
another double quote. Alternatively, you can select another delimiter than
67+
comma in the import options.
68+
69+
.. code-block:: none
70+
71+
keys,en,es,ja
72+
GREET,"Hello, friend!","Hola, amigo!",こんにちは
73+
ASK,How are you?,Cómo está?,元気ですか
74+
BYE,Goodbye,Adiós,さようなら
75+
QUOTE,"""Hello"" said the man.","""Hola"" dijo el hombre.",「こんにちは」男は言いました
76+
77+
CSV importer
78+
------------
79+
80+
Godot will treat CSV files as translations by default. It will import them
81+
and generate one or more compressed translation resource files next to it.
82+
83+
Importing will also add the translation to the list of
84+
translations to load when the game runs, specified in project.godot (or the
85+
project settings). Godot allows loading and removing translations at
86+
runtime as well.
87+
88+
Select the ``.csv`` file and access the **Import** dock to define import
89+
options. You can toggle the compression of the imported translations, and
90+
select the delimiter to use when parsing the CSV file.
91+
92+
.. image:: img/import_csv.webp
93+
94+
Be sure to click **Reimport** after any change to these options.

0 commit comments

Comments
 (0)