Merge pull request #5900 from DeeJayLSP/spreadsheet_personal_space

Move localization with spreadsheets to its own page

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 <https://en.wikipedia.org/wiki/Byte_order_mark>`__.
-
-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.
+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.
+
+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.

tutorials/i18n/index.rst

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

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 <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>`_.

tutorials/i18n/localization_using_spreadsheets.rst

@@ -0,0 +1,94 @@
+.. _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.
+
+The CSV files **must** be saved with UTF-8 encoding
+without a `byte order mark <https://en.wikipedia.org/wiki/Byte_order_mark>`__.
+
+.. warning::
+
+    By default, Microsoft Excel will always save CSV files with ANSI encoding
+    rather than UTF-8. There is no built-in way to do this, but there are
+    workarounds as described
+    `here <https://stackoverflow.com/questions/4221176/excel-to-csv-with-utf8-encoding>`__.
+
+    We recommend using `LibreOffice <https://www.libreoffice.org/>`__ or Google Sheets instead.
+
+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.