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 = is included in the string!

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

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