Translations¶

Texts can be translated client-side with the help of core.translate and translation files.

Translating a string¶

Two functions are provided to translate strings: core.translate and core.get_translator.

core.get_translator(textdomain) is a simple wrapper around core.translate, and core.get_translator(textdomain)(str, ...) is equivalent to core.translate(textdomain, str, ...). It is intended to be used in the following way, so that it avoids verbose repetitions of core.translate:
```
  local S = core.get_translator(textdomain)
  S(str, ...)
```

As an extra commodity, if textdomain is nil, it is assumed to be "" instead.

core.translate(textdomain, str, ...) translates the string str with the given textdomain for disambiguation. The textdomain must match the textdomain specified in the translation file in order to get the string translated. This can be used so that a string is translated differently in different contexts. It is advised to use the name of the mod as textdomain whenever possible, to avoid clashes with other mods. This function must be given a number of arguments equal to the number of arguments the translated string expects. Arguments are literal strings -- they will not be translated, so if you want them to be, they need to come as outputs of core.translate as well.

For instance, suppose we want to translate "@1 Wool" with "@1" being replaced by the translation of "Red". We can do the following:

  local S = core.get_translator()
  S("@1 Wool", S("Red"))

This will be displayed as "Red Wool" on old clients and on clients that do not have localization enabled. However, if we have for instance a translation file named wool.fr.tr containing the following:

  @1 Wool=Laine @1
  Red=Rouge

this will be displayed as "Laine Rouge" on clients with a French locale.

Operations on translated strings¶

The output of core.translate is a string, with escape sequences adding additional information to that string so that it can be translated on the different clients. In particular, you can't expect operations like string.length to work on them like you would expect them to, or string.gsub to work in the expected manner. However, string concatenation will still work as expected (note that you should only use this for things like formspecs; do not translate sentences by breaking them into parts; arguments should be used instead), and operations such as core.colorize which are also concatenation.

Translation file format¶

A translation file has the suffix .[lang].tr, where [lang] is the language it corresponds to. It must be put into the locale subdirectory of the mod. The file should be a text file, with the following format:

Lines beginning with # textdomain: (the space is significant) can be used to specify the text domain of all following translations in the file.
All other empty lines or lines beginning with # are ignored.
Other lines should be in the format original=translated. Both original and translated can contain escape sequences beginning with @ to insert arguments, literal @, = or newline (See [Escapes] below). There must be no extraneous whitespace around the = or at the beginning or the end of the line.

Escapes¶

Strings that need to be translated can contain several escapes, preceded by @.

@@ acts as a literal @.
@n, where n is a digit between 1 and 9, is an argument for the translated string that will be inlined when translated. Due to how translations are implemented, the original translation string must have its arguments in increasing order, without gaps or repetitions, starting from 1.
@= acts as a literal =. It is not required in strings given to core.translate, but is in translation files to avoid being confused with the = separating the original from the translation.
@\n (where the \n is a literal newline) acts as a literal newline. As with @=, this escape is not required in strings given to core.translate, but is in translation files.
@n acts as a literal newline as well.

Server side translations¶

On some specific cases, server translation could be useful. For example, filter a list on labels and send results to client. A method is supplied to achieve that:

core.get_translated_string(lang_code, string): Translates string using translations for lang_code language. It gives the same result as if the string was translated by the client.

The lang_code to use for a given player can be retrieved from the table returned by core.get_player_information(name).

IMPORTANT: This functionality should only be used for sorting, filtering or similar purposes. You do not need to use this to get translated strings to show up on the client.