{trans}

Writes the text a key has in the _lang/ catalog of the request's locale, with plural forms and substitutions.

Output control Single tags

Syntax 

{trans 'key'}
{trans 'key', count=$n}
{trans 'key', name=$value, other=$value}

Parameters

key
The key in _lang/<locale>.json. A key no catalog knows is written as itself.

Options

count
Picks the plural form of a text with | between its forms, and replaces %d in it.
name
Any other name: its value replaces :name in the text. The names are read raw, so even content= or data= is a substitution here.

Description

{trans 'cart.title'} looks the key up in the translation catalog of the request's locale and writes its text. A catalog is a flat JSON object in _lang/<locale>.json - _lang/en.json, _lang/nl.json. The catalogs are looked up from the page's directory up to the application root and then _common, the most specific winning; for a locale nl_NL the files nl_NL.json, nl-NL.json and nl.json all count. A key no catalog knows is written as the key itself, so a missing translation shows rather than disappearing.

The locale is $padLocale. With $padLocales listing several, a ?lang= value, the padLang cookie or the browser's Accept-Language picks among them.

Plurals and substitutions

A text with forms separated by | is plural: two forms are one and other, three are zero, one and other. count= picks the form and replaces %d in it. Every other name=value replaces :name in the text. The items are read raw, as {attrs} reads them, so a substitution may be called anything.

Escaping

The catalog's text is the application's own and is written as it stands, markup included. A substitution is data: it is written as {$x} writes a field, sanitized - and so is a key that no catalog knows. The trans pipe does the same for a value: {echo 'cart.title' | trans}. A {trans} without a key is a strict error.

Examples

Keys from the catalog

The text of each key in _lang/en.json - markup in the catalog stays markup, an unknown key is written as itself.

Templateexamples/trans/1-key.pad 
<h3>{trans 'trans.cart.title'}</h3>
<p><button type="button">{trans 'trans.cart.checkout'}</button></p>
<p>{trans 'trans.cart.missing'}</p>
Resultopen alone

Your shopping cart

trans.cart.missing

Plural forms

count= picks one of the three forms - zero, one, other - and replaces %d.

Templateexamples/trans/2-plural.pad 
<ul>
  {sequence '0..3', name='n'}<li>{trans 'trans.cart.items', count=$n}</li>{/sequence}
</ul>
Resultopen alone
  • Your cart is empty
  • One item in your cart
  • 2 items in your cart
  • 3 items in your cart

Substitutions

Each name= replaces :name; a value is escaped like a field.

Templateexamples/trans/3-substitute.pad 
{set $visitor = 'Ana <script>'}
<p>{trans 'trans.greeting', name=$visitor, place='Utrecht'}</p>
Resultopen alone

Hello Ana <script>, welcome back to Utrecht.

See also

  • {echo} Evaluates an expression and prints the result - the general output tag, and the one to put in front of a pipe.
  • {markdown} Renders its content, or the value of its parameter, as Markdown and writes the HTML.