+Translations
+------------
+
+Texts can be translated client-side with the help of `minetest.translate` and translation files.
+
+### Translating a string
+Two functions are provided to translate strings: `minetest.translate` and `minetest.get_translator`.
+
+* `minetest.get_translator(textdomain)` is a simple wrapper around `minetest.translate`, and
+ `minetest.get_translator(textdomain)(str, ...)` is equivalent to `minetest.translate(textdomain, str, ...)`.
+ It is intended to be used in the following way, so that it avoids verbose repetitions of `minetest.translate`:
+
+ local S = minetest.get_translator(textdomain)
+ S(str, ...)
+
+ As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead.
+
+* `minetest.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 `minetest.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 = minetest.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 `minetest.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
+`minetest.colorize` which are only concatenation under the hood as well.
+
+### Translation file format
+A translation file has the suffix `.[lang].tr`, where `[lang]` is the language it corresponds to.
+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 translation. 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 `minetest.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 `minetest.translate`, but is in translation files.
+* `@n` acts as a literal newline as well.
+