Tutorial:Localisation

Mods should define human readable names for prototypes that they add. They can also define descriptions for items or custom strings for usage in GUIs etc. This is called localisation.

Format

Translations are stored as .cfg files, with the following format:

welcome-message=Hello world
[category]
title=Category related title

Any whitespace after or before = is included in the key or string, so title =Category related title will give an unknown key error if you are looking for the title key, since it is the title  key.

These files are located within the language suffix of the language in the locale folder of the mod, so as an English example __mod__/locale/en/any_name_here.cfg. There can be more than 1 file per language, all of them will be read.

Usage

Localising simple strings

The simplest localisation is of items, entities etc. If we say the item is iron-plate, the game will then search all loaded locale files for item-name.iron-plate and item-description.iron-plate, which in the locale file looks like this:

[item-name]
iron-plate=Iron plate
[item-description]
iron-plate=A plate made of iron.

If found in the locale, the label is set to this string. If not found, the game will instead show: Unknown key: "item-name.iron-plate"

In script, the localised string is formatted as {"category.name"}, so game.print({"item-name.iron-plate"}) prints Iron plate.

Localising with parameters

For more complex strings, localisation parameters can be used. For instance we want to show Time left: 10 minutes.

So a key with a placeholder is defined, which is replaced by the first parameter after the locale key.:

time-left=Time left: __1__ minutes.

So it is used like this:

game.print({"time-left", 10})

It also works with multiple parameters:

game.print({"time-left", 10, 45})

time-left=Time left: __1__ minutes and __2__ seconds.

Which results in Time left: 10 minutes and 45 seconds.

Built-in parameters

For some situations, we use localisation to show control schemes. For instance we want to say:

technology-prompt=Use T to open the technology screen

However the player may have rebound the key, but we can’t figure out which key as it would not be deterministic. So instead we use the built-in replacement functionality

technology-prompt=Use __CONTROL__open-technology-gui__ to open the technology screen.

We can also use this for items and entities etc.:

big-iron-plate=Big __ITEM__iron-plate__

Plurals

Pluralization can be used in any string that uses a parameter (e.g. __1__) that is numeric, so something like an amount of minutes. It can be used multiple times per string.

format-days=__1__ __plural_for_parameter_1_{1=day|rest=days}__

This results in "1 day" and "2 days" / "500 days" etc.

The number after __plural_for_parameter_ denotes which parameter is used to determine the plural. This is the parameter 1 in the above example. Anything inside the {} is used to make the plural. Each plural form is separated by a |. The text in front of the = determines for what the plural form is used. Options for this are:

• a simple number, e.g. "1".
• Multiple numbers, e.g. "2,3,4".
• What the number ends with, e.g. "ends in 11" or "ends in 1"
• Multiple ends with, e.g. "ends in 1,ends in 2,ends in 12".
• "rest" to give the default plural.

Plural forms may be empty or contain other keys such as __1__ or spaces. This allow rather large plural forms:

__plural_for_parameter_1_{1=__1__ player is|rest=__1__ players are}__ connecting

The system chooses the first fitting plural that it encounters when multiple would fit:

__plural_for_parameter_1_{ends in 12=option 1|ends in 2=option 2|rest=option 1}__

This will result in "option 1" for e.g. 12 and in "option 2" for e.g. 22 and in "option 3" for numbers not ending with 2.

Concatenating localised strings

The special locale key: "" is used to concatenate, as the table format does not support concatenation:

game.print({"", {"item-name.iron-plate"}, ": ", 60})

Will result in: Iron plate: 60