Types/LocalisedString - Revision history

BilkaBot: Removed old prototype docs

2024-10-25T14:32:28Z

Removed old prototype docs

← Older revision		Revision as of 14:32, 25 October 2024
Line 2:		Line 2:

	</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>		</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>



	~~Localised strings are a way to support translation of in-game text. They offer a language-independent code representation of the text that should be shown to players.~~

	~~A localised string 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.~~

	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 settings and prototype stages, 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.

	There are two special flags for the localised string, indicated by the key being a particular string. First, if the key is the empty string (`""`), then all parameters will be concatenated (after processing, if any are localised strings themselves). Second, if the key is a question mark (`"?"`), then the first valid parameter will be used. A parameter can be invalid if its name doesn't match any string template. If no parameters are valid, the last one is returned. This is useful to implement a fallback for missing locale templates.

	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 ==~~
	~~For a player using the English translation, this will print "No ammo". For a player using 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]]

BilkaBot: Updated styling of prototype doc migration note

2023-09-21T10:42:32Z

Updated styling of prototype doc migration note

← Older revision		Revision as of 10:42, 21 September 2023
Line 1:		Line 1:
	'''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]		<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]

	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><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>

BilkaBot: Protected "Types/LocalisedString": Migrated prototype doc to separate website ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

2023-08-16T17:51:41Z

Protected "Types/LocalisedString": Migrated prototype doc to separate website ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

← Older revision		Revision as of 17:51, 16 August 2023
(No difference)

BilkaBot: Migrated prototype doc to separate website

2023-08-16T17:51:41Z

Migrated prototype doc to separate website

← Older revision		Revision as of 17:51, 16 August 2023
Line 1:		Line 1:
			'''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]

			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].



	Localised strings are a way to support translation of in-game text. They offer a language-independent code representation of the text that should be shown to players.		Localised strings are a way to support translation of in-game text. They offer a language-independent code representation of the text that should be shown to players.

Bilka: 1.1.73: fallback locale (copied from migrated prototype docs)

2023-08-14T08:03:17Z

1.1.73: fallback locale (copied from migrated prototype docs)

← Older revision		Revision as of 08:03, 14 August 2023
Line 3:		Line 3:
	A localised string 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.		A localised string 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.

	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 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 settings and prototype stages, 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.		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.		There are two special flags for the localised string, indicated by the key being a particular string. First, if the key is the empty string (`""`), then all parameters will be concatenated (after processing, if any are localised strings themselves). Second, if the key is a question mark (`"?"`), then the first valid parameter will be used. A parameter can be invalid if its name doesn't match any string template. If no parameters are valid, the last one is returned. This is useful to implement a fallback for missing locale templates.

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

Bilka: remove inconsistently applied formatting of key, shorten "why" for locale string cause otherwise the whole mp/determinism thing would also need to be explained (may be done in the future, but not here). Display to players is already covered by examples

2023-01-18T16:39:39Z

remove inconsistently applied formatting of key, shorten "why" for locale string cause otherwise the whole mp/determinism thing would also need to be explained (may be done in the future, but not here). Display to players is already covered by examples

← Older revision		Revision as of 16:39, 18 January 2023
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~~.		Localised strings are a way to support translation of in-game text. They offer a language-independent code representation of the text that should be shown to players.

	~~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.		A localised string 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.

	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 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.		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.
Line 12:		Line 12:

	== Examples ==		== Examples ==
	In the English translation, this will print "No ammo"~~; in~~ the Czech translation, it will print "Bez munice":		For a player using the English translation, this will print "No ammo". For a player using the Czech translation, it will print "Bez munice":
	<syntaxhighlight lang="lua">game.player.print({"description.no-ammo"})</syntaxhighlight>		<syntaxhighlight lang="lua">game.player.print({"description.no-ammo"})</syntaxhighlight>
	The description.no-ammo template contains no placeholders, so no further parameters are necessary.		The description.no-ammo template contains no placeholders, so no further parameters are necessary.

Honktown: Added second paragraph, an explanation of what the localised string means in the more general context.

2023-01-07T05:43:56Z

Added second paragraph, an explanation of what the localised string means in the more general context.

← Older revision		Revision as of 05:43, 7 January 2023
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.		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.

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

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

Bilka: direct booleans are also converted

2021-11-11T16:14:10Z

direct booleans are also converted

← Older revision		Revision as of 16:14, 11 November 2021
Line 7:		Line 7:
	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.		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 which will be converted to its textual representation.		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 ==		== Examples ==

Bilka: recursion, key size and parameter count limits

2021-02-15T09:46:50Z

recursion, key size and parameter count limits

← Older revision		Revision as of 09:46, 15 February 2021
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.		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.

	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).		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.		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.		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.
Line 24:		Line 24:

	== See also ==		== See also ==
	* ~~http~~://lua-api.factorio.com/latest/Concepts.html#LocalisedString		* [https://lua-api.factorio.com/latest/Concepts.html#LocalisedString Control stage doc]
	* [[Tutorial:Localisation]]		* [[Tutorial:Localisation]]

Bilka: parantheses

2020-11-16T16:23:24Z

parantheses

← Older revision		Revision as of 16:23, 16 November 2020
Line 11:		Line 11:
	== Examples ==		== Examples ==
	In the English translation, this will print "No ammo"; in the Czech translation, it will print "Bez munice":		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>		<syntaxhighlight lang="lua">game.player.print({"description.no-ammo"})</syntaxhighlight>
	The description.no-ammo template contains no placeholders, so no further parameters are necessary.		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":		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>		<syntaxhighlight lang="lua">game.player.print({"description.durability", 5, 9})</syntaxhighlight>

	This will print "hello" in all translations:		This will print "hello" in all translations:
	<syntaxhighlight lang="lua">game.player.print{"", "hello"}</syntaxhighlight>		<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.		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>		<syntaxhighlight lang="lua">game.print({"", {"item-name.iron-plate"}, ": ", 60})</syntaxhighlight>

	== See also ==		== See also ==
	* http://lua-api.factorio.com/latest/Concepts.html#LocalisedString		* http://lua-api.factorio.com/latest/Concepts.html#LocalisedString
	* [[Tutorial:Localisation]]		* [[Tutorial:Localisation]]