Template:Localization/doc

This template is used to dynamically display predefined text (which is stored via localization/register), mainly within templates, depending on the Terraria language wiki it is used on. It is the core template of the effort of standardizing template code across language wikis and preventing outdated templates. See Help:I18n & l10n for Templates for more information.

Use l10n as a shortcut.

Basic concept
In a template, all English texts and other language-specific strings (e.g. category names) are stored in an "l10n database" at the top of the template, i.e. their inline mentions are replaced by a variable pointing to their database entry in the l10n database. This facilitates storing translations of one string in the database and choosing between them upon template call, depending on the wiki's language.

The database is set up using l10n/register. It assigns every string a unique two-level identifier consisting of namespace and key. The namespace is usually the template's name and the key a descriptive "name" of the string.

Upon retrieving the stored strings (which is done using this template), their namespace and key have to be specified. The differentiation between which translation to choose is handled by lang, which determines the wiki's language automatically. If there is no string available for the specified namespace–key combination in the respective language, the English version will be used.

Usage
("long" mode, see below)

Namespace.
 * Parameter 1

Key.
 * Parameter 2

Language. This can be used to display the stored value of a specific language. By default, this is what lang returns.
 * Parameter 3 (optional)

Placeholders for formatting. They will be replaced in the output by a string that is the same for every language. Placeholders can also be defined recursively. See the following example:
 * All named parameters surrounded by  characters

A:

B:

C:

Result:

"Long" mode
The function and usage of "Long" mode are exactly the same, but it use lua instead of #replace: for replacement.Therefore it doesn't have the string length limit of and is much slower when there is less then 2 placeholders. But, when there are many placeholders(> 3) or the l10n string is too long for normal mode, use "long" mode will be great.

Register localization info
The l10n database is declared by l10n/register. It is possible to either have it load automatically or register it manually. In the end, both methods require a manual definition of the database – the only difference is that with autoload, this is not done in the template source code itself but in a separate template.

Manual registration
Use in the same template. Make sure to place it before any l10n call, ideally at the very top of the code.

Autoload
Since the database is only setting variables, it is not mandatory to include it in the same template. Instead, it can be moved to a separate subtemplate which is then transcluded at the beginning of the base template. l10n has a functionality that will try to automatically transclude ("autoload") such an outsourced l10n database by transcluding  when needed. For example, for foo, l10n will try to transclude.

This way is recommended because it reduces the number of l10n/register transclusions and improves performance.

Example
Take Template:Achievement as an example:

Register localization info (the l10n database) first. This can be done either in Template:Achievement/l10n (for the autoload method) or at the top of Template:Achievement itself.

Simply add more languages in the same manner if needed. Make sure to keep the alphabetical order of the language codes, with English always at the top.

Then, in the template code, use l10n to retrieve a string for the current language from the l10n database, e.g.  (which would return   on the English wiki and   on the French wiki). See the source code of achievement for details regarding this example.

Resulting output:

Escape and Unescape
Usually, l10n string will be parsed before placeholders replacement, take the code below for example:

It will get

In some cases, we need the parsing occurred after placeholders replacement, e.g. we want to output singular form or plural form depand on input value, but the code below won't work: <-- doesn't work -->

Thanks to ParserPower extension, we can escape the l10n string to prevent it from being parsed, and l10n will auto unescape it after placeholders replacement to let it be parsed.For the example above, we can achieve the goal like this:

By this way, we can use magic words, parse functions, and templates in l10n strings. This can help simplify the i18n template itself and improve performance.

NOTE: Mediawiki does not allow template loop, so in escaped l10n strings you can NOT use templates which use l10n. e.g. the code below will cause error: <-- cause error -->

There are some tricks to circumvent this limitation, but generally you should avoid using l10n templates in escaped l10n strings.