Types/LocalisedString: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(Added second paragraph, an explanation of what the localised string means in the more general context.)
(Removed old prototype docs)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Localised strings are a way to support translation of in-game text. It is an array where the first element is the ''key'' and the remaining elements are parameters that will be substituted for placeholders in the template designated by the key.
<div class="stub"><p>'''The prototype docs have moved to a new website with an improved format.''' This documentation page can now be found here: [https://lua-api.factorio.com/latest/types/LocalisedString.html https://lua-api.factorio.com/latest/types/LocalisedString.html]


When presented to a player, what appears to ''each'' player is determined by their Language (as chosen by game setting). As Language is set per-player, and Factorio must reach the same results for every player, a localised string offers a player-independent '''code''' representation. The Factorio API Docs provide the means to expose a translation, during gameplay, to everyone. Stated a different way, any place a translation is visible is not available for code to access "as it appears to be", because it would result in different outcomes for different players. The localised string provides an abstract representation, preventing inconsistencies.
</p><p>This wiki page is no longer updated and '''will be removed at some point in the future''', so please update your browser bookmarks or other links that sent you here. If you'd like to contribute to the new docs, you can leave your feedback [https://forums.factorio.com/viewforum.php?f=233 on the forums].</p></div>
 
The ''key'' identifies the string template. For example, "gui-alert-tooltip.attack" (for the template "__1__ objects are being damaged"; see the file data/core/locale/en.cfg). In the data stage, this key cannot be longer than 200 characters.
 
The template can contain placeholders such as __1__ or __2__. These will be replaced by the respective parameter in the LocalisedString. The parameters themselves can be other localised strings, which will be processed recursively in the same fashion. Localised strings cannot be recursed deeper than 20 levels and cannot have more than 20 parameters.
 
As a special case, when the key is just the empty string, all the parameters will be concatenated (after processing, if any are localised strings). If there is only one parameter, it will be used as is.
 
Furthermore, when an API function expects a localised string, it will also accept a regular string (i.e. not a table) which will not be translated, or a number or boolean which will be converted to its textual representation.
 
== Examples ==
In the English translation, this will print "No ammo"; in the Czech translation, it will print "Bez munice":
<syntaxhighlight lang="lua">game.player.print({"description.no-ammo"})</syntaxhighlight>
The description.no-ammo template contains no placeholders, so no further parameters are necessary.
 
In the English translation, this will print "Durability: 5/9"; in the Japanese one, it will print "耐久度: 5/9":
<syntaxhighlight lang="lua">game.player.print({"description.durability", 5, 9})</syntaxhighlight>
 
This will print "hello" in all translations:
<syntaxhighlight lang="lua">game.player.print({"", "hello"})</syntaxhighlight>
 
This will print "Iron plate: 60" in the English translation and "Eisenplatte: 60" in the German translation.
<syntaxhighlight lang="lua">game.print({"", {"item-name.iron-plate"}, ": ", 60})</syntaxhighlight>
 
== See also ==
* [https://lua-api.factorio.com/latest/Concepts.html#LocalisedString Control stage doc]
* [[Tutorial:Localisation]]

Latest revision as of 14:32, 25 October 2024

The prototype docs have moved to a new website with an improved format. This documentation page can now be found here: https://lua-api.factorio.com/latest/types/LocalisedString.html

This wiki page is no longer updated and will be removed at some point in the future, so please update your browser bookmarks or other links that sent you here. If you'd like to contribute to the new docs, you can leave your feedback on the forums.

Retrieved from "https://wiki.factorio.com/index.php?title=Types/LocalisedString&oldid=202715"