Internationalisation functions

The i:() template function allows templates to be internationalised.

function i(text)

Translates a string, with text from the template category.

In almost all cases, the argument to the function will be a literal string, for example i("Some text"). Using values from the view should only be used when they are translatable strings from other plugins, and in this case, using a custom category is preferred.

Text is interpolated with NAME().

If the function has blocks, then the string is interpolated with values from the blocks, with insertion points marked with {}. See below for syntax.

function i:category(text)

As i(), except the category is explicitly specified in the function name.

For example, i:example("Hello world") translates the text using the strings from the example category.

Example

This example shows simple usage of the i() template function, interpolating values from the view.

<p> i("Dear {},") { user.name } </p>
<p> i("This is an example notification.") </p>
<p> i("There are {count} and they are {}.")
        {itemColour} count{count}
</p>

Interpolations

When the i() function has blocks, the translated string is interpolated, inserting values in the block into the output.

The insertion points are marked with {}, where the brackets contain the name of the block (and optionally a plural format). The empty string is the anonymous block, or a name for a named block.

The string

  "Hello {},"

would insert the anonymous block before the comma, and

  "Hello {}, today is {dayName}."

would also insert the dayName named block in the string.

See the example above.

Plurals

Because each language has different plural rules, the translated strings must contain all the logic for pluralisation. These are implemented using the ICU PluralFormat within the enclosing {}.

A plural format is the block name, the literal string ‘plural’, and then the plural format, as a comma separated list. If the block is the anonymous block, there is nothing proceeding the first comma. For example,

  i("I have {} {,plural,other{items} one{item}}") { count }

would output the following strings, depending on the value of count within the view:

`count`	Output
0	I have 0 items
1	I have 1 item
2	I have 2 items

In the view, the value must be a number, otherwise it is treated as zero.

The plural format is one or more options, each separated by spaces. The options are:

  option{text}

where option is one of ‘zero’, ‘one’, ‘two’, ‘few’, ‘many’ or ‘other’, or a literal count specified a =N where N is a number. The definition of the named options is language specific, using the Unicode plural rules.

You must include the other option in all plural formats.