Template:Localization

From Terraria Wiki
Jump to navigation Jump to search
Template-info.svg Documentation The documentation below is transcluded from Template:Localization/doc. (edit | history)

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 (Note that this is not related to the MediaWiki Namespace concept.) 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

{{ l10n | <namespace> | <key> | <lang> (optional) }}

{{ l10n/long | <namespace> | <key> | <lang> (optional) }} ("long" mode, see below)

Parameter 1

Namespace.

Parameter 2

Key.

Parameter 3 (optional)

Language. This can be used to display the stored value of a specific language. By default, this is what {{lang}} returns.

All named parameters surrounded by $ characters

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:

{{l10n/register|test|en
|abc=input: $x$
|mn=abc$d$e$f$g
|t = zzz
}}
A: {{l10n|test|abc|$x$=xyz}}

B: {{l10n|test|mn|$d$=kkkk|$f$=jjjj}}

C: {{l10n|test|abc|$x$={{l10n|test|mn|$d$=x|$f$=y}} }}

Result:

A: input: xyz

B: abckkkkejjjjg

C: input: abcxeyg

"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 only needs to be loaded once per page, and not with every transclusion of the template on the page. So it can be moved to a separate /l10n subtemplate. {{l10n}} has a functionality that will try to automatically transclude ("autoload") such an outsourced l10n database by transcluding Template:<namespace>/l10n when needed. For example, for {{l10n|foo|bar}}, {{l10n}} will try to transclude Template:foo/l10n.

This method is recommended. It reduces the number of {{l10n/register}} transclusions and improves performance, especially if a template is used more than once on a page. With the other method, the l10n database of a template that is used 20 times on the same page would be loaded 20 times as well, even though only the first one is necessary. Loading the database 19 more times is redundant.

Example

Take Template:Error as an example:

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

<!-- en version -->
{{l10n/register|error|en
|intro=!!Error:\_
|cate=Pages with template errors
|cate_from=Pages with errors from $from$
}}
<!-- ru version -->
{{l10n/register|error|ru
|cate=Страницы с ошибками в работе шаблонов
}}
<!-- ... more languages if needed. -->

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. {{l10n|error|cate}} (which would return Pages with template errors on the English wiki and Страницы с ошибками в работе шаблонов on the Russian wiki). See the source code of {{error}} for details regarding this example.

Escape and Unescape

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

{{l10n/register|test|en
|p=$INPUT$ to lower is {{lc:$INPUT$}}
}}
{{l10n|test|p|$INPUT$=ALLCAP}}

It will get ALLCAP to lower is $input$

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 -->
{{l10n/register|test|en
|p=$INPUT$ {{plural:$INPUT$|item|items}}
}}
{{l10n|test|p|$INPUT$=1}}

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:

{{l10n/register|test|en
|p=<esc>$INPUT$ {{plural:$INPUT$|item|items}}</esc>
}}
{{l10n|test|p|$INPUT$=1}}

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 -->
{{l10n/register|test|en
|p= <esc>{{coin|$INPUT$}}</esc>
}}
{{l10n|test|p|$INPUT$=1}}

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