godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2025-12-31 17:49:03 +03:00
Code Issues Packages Projects Releases Wiki Activity

Move localization with spreadsheets to its own page

Browse Source
This commit is contained in:
DeeJayLSP
2022-07-01 03:21:32 -03:00
committed by skyace65
parent 5bbe7cc549
commit f31a1c7fa6
4 changed files with 96 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
tutorials/assets_pipeline/importing_translations.rst
View File

@@ -31,86 +31,16 @@ each string. This allows you to revise the text while it is being
translated to other languages. The unique ID can be a number, a string,
or a string with a number (it's just a unique string anyway).
.. note:: If you need a more powerful file format, Godot also supports
loading translations written in the gettext ``.po`` format. See
:ref:`doc_localization_using_gettext` for details.
Translation format
------------------
Supported formats
-----------------
To complete the picture and allow efficient support for translations,
Godot has a special importer that can read CSV files. Most spreadsheet
editors can export to this format, so the only requirement is that the files
have a special arrangement. The CSV files **must** be saved with UTF-8 encoding
without a `byte order mark <https://en.wikipedia.org/wiki/Byte_order_mark>`__.
editors can export to this format, so the only requirement is that the
files have a special arrangement. See
:ref:`doc_localization_using_spreadsheets` for detailed info on
formatting and importing CSVs.
CSV files must be formatted as follows:
+--------+----------+----------+----------+
| keys | <lang1> | <lang2> | <langN> |
+========+==========+==========+==========+
| KEY1 | string | string | string |
+--------+----------+----------+----------+
| KEY2 | string | string | string |
+--------+----------+----------+----------+
| KEYN | string | string | string |
+--------+----------+----------+----------+
The "lang" tags must represent a language, which must be one of the :ref:`valid
locales <doc_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 (they are usually in
uppercase, to differentiate 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. | 「こんにちは」男は言いました |
+-------+-----------------------+------------------------+------------------------------+
The same example is shown below as a comma-separated plain text file,
which should be the result of editing the above in a spreadsheet.
When editing the plain text version, be sure to enclose with double
quotes any message that contains commas, line breaks or double quotes,
so that commas are not parsed as delimiters, line breaks don't create new
entries and double quotes are not parsed as enclosing characters. Be sure
to escape any double quotes a message may contain by preceding them with
another double quote. Alternatively, you can select another delimiter than
comma in the import options.
.. code-block:: none
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 importer
------------
Godot will treat CSV files as translations by default. It will import them
and generate one or more compressed translation resource files next to it.
Importing will also add the translation to the list of
translations to load when the game runs, specified in project.godot (or the
project settings). Godot allows loading and removing translations at
runtime as well.
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.
.. image:: img/import_csv.webp
Be sure to click **Reimport** after any change to these options.
If you need a more powerful file format, Godot also supports loading
translations written in the gettext ``.po`` format. See
:ref:`doc_localization_using_gettext` for details.

1
tutorials/i18n/index.rst
View File

@@ -8,6 +8,7 @@ Internationalization
:name: toc-learn-features-i18n
internationalizing_games
localization_using_spreadsheets
localization_using_gettext
locales
pseudolocalization

7
tutorials/i18n/localization_using_gettext.rst
View File

@@ -3,9 +3,10 @@
Localization using gettext
==========================
In addition to :ref:`doc_importing_translations` in CSV format, Godot
also supports loading translation files written in the GNU gettext
format (text-based ``.po`` and compiled ``.mo`` since Godot 4.0).
In addition to importing translations in
:ref:`CSV format <doc_localization_using_spreadsheets>`, Godot also
supports loading translation files written in the GNU gettext format
(text-based ``.po`` and compiled ``.mo`` since Godot 4.0).
.. note:: For an introduction to gettext, check out
`A Quick Gettext Tutorial <https://www.labri.fr/perso/fleury/posts/programming/a-quick-gettext-tutorial.html>`_.

82
tutorials/i18n/localization_using_spreadsheets.rst Normal file
View File

@@ -0,0 +1,82 @@
.. _doc_localization_using_spreadsheets:
Localization using spreadsheets
===============================
Spreadsheets are one of the most common formats for localizing games.
In Godot, spreadsheets are supported through the CSV format. This
guide explains how to work with CSVs.
Formatting
----------
CSV files must be formatted as follows:
+--------+----------+----------+----------+
| keys | <lang1> | <lang2> | <langN> |
+========+==========+==========+==========+
| KEY1 | string | string | string |
+--------+----------+----------+----------+
| KEY2 | string | string | string |
+--------+----------+----------+----------+
| KEYN | string | string | string |
+--------+----------+----------+----------+
The "lang" tags must represent a language, which must be one of the :ref:`valid
locales <doc_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 (they are usually in
uppercase, to differentiate 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. | 「こんにちは」男は言いました |
+-------+-----------------------+------------------------+------------------------------+
The same example is shown below as a comma-separated plain text file,
which should be the result of editing the above in a spreadsheet.
When editing the plain text version, be sure to enclose with double
quotes any message that contains commas, line breaks or double quotes,
so that commas are not parsed as delimiters, line breaks don't create new
entries and double quotes are not parsed as enclosing characters. Be sure
to escape any double quotes a message may contain by preceding them with
another double quote. Alternatively, you can select another delimiter than
comma in the import options.
.. code-block:: none
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 importer
------------
Godot will treat CSV files as translations by default. It will import them
and generate one or more compressed translation resource files next to it.
Importing will also add the translation to the list of
translations to load when the game runs, specified in project.godot (or the
project settings). Godot allows loading and removing translations at
runtime as well.
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.
.. image:: img/import_csv.webp
Be sure to click **Reimport** after any change to these options.