mirror of
https://github.com/godotengine/godot-docs.git
synced 2025-12-31 17:49:03 +03:00
95 lines
4.4 KiB
ReStructuredText
95 lines
4.4 KiB
ReStructuredText
.. _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.
|