diff --git a/tutorials/assets_pipeline/importing_translations.rst b/tutorials/assets_pipeline/importing_translations.rst index a6b75ad01..8b443172d 100644 --- a/tutorials/assets_pipeline/importing_translations.rst +++ b/tutorials/assets_pipeline/importing_translations.rst @@ -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 `__. +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 | | | | -+========+==========+==========+==========+ -| 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 ` 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. diff --git a/tutorials/i18n/index.rst b/tutorials/i18n/index.rst index 51dba86df..5ed8c6c18 100644 --- a/tutorials/i18n/index.rst +++ b/tutorials/i18n/index.rst @@ -8,6 +8,7 @@ Internationalization :name: toc-learn-features-i18n internationalizing_games + localization_using_spreadsheets localization_using_gettext locales pseudolocalization diff --git a/tutorials/i18n/localization_using_gettext.rst b/tutorials/i18n/localization_using_gettext.rst index fadd3648b..ada91e2f0 100644 --- a/tutorials/i18n/localization_using_gettext.rst +++ b/tutorials/i18n/localization_using_gettext.rst @@ -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 `, 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 `_. diff --git a/tutorials/i18n/localization_using_spreadsheets.rst b/tutorials/i18n/localization_using_spreadsheets.rst new file mode 100644 index 000000000..7530fde5c --- /dev/null +++ b/tutorials/i18n/localization_using_spreadsheets.rst @@ -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 | | | | ++========+==========+==========+==========+ +| 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 ` 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.