Development Guides Home >> Guide to Template Toolkit

Guide to Template Toolkit - Localization in Template Toolkit

Introduction

Use localization in Template Toolkit files to produce dynamic interfaces in multiple languages. Localization refers to the translation of text from one language to multiple other languages, as well as the addition of cultural adaptations to make a product usable globally.

cPanel & WHM uses the locale system to localize phrases. For more information, read our Guide to Locales documentation.

Note:

Before you write text for localized user interfaces, we strongly recommend that you review our Best Practices documentation.

Localized text in Template Toolkit

Localized phrases in Template Toolkit files use the following syntax:

[% locale.maketext('Your localized phrase goes here.') %]

The template passes everything between the single quotes ('') through the locale system as a single localized phrase. To reuse phrases as often as possible, which significantly lowers translation costs, we recommend that you divide sentences into separate locale.maketext calls whenever possible.

You must call the locale.maketext function inside of brackets and percent signs ( [% %] ).
The localization system has specific requirements for special characters and other formatting conventions .
- To use an apostrophe in the text, use a single curly quote ( ’ ) rather than a third single straight quote ( ' ):
```
  [% locale.maketext(‘Real life? You couldn't handle real life.’) %]
```
- To use quotes in the text, use a double curly quote ( “ ” ) rather than double straight quotes ( "" ):
```
[% locale.maketext('“Curse your sudden but inevitable betrayal!”') %]
```
- You cannot include HTML in locale.maketext strings.

Variables

To pass variables into localized phrases, use the following syntax:

[% locale.maketext('The system set up your email address [_1] on your domain [_2].', email, domain) %]

This template code passes the phrase through the locale system, and then replaces the variables ([_1] and [_2]) with the variables' values (email and domain, respectively).

If the email value is user@example.com and the domain value is example.com, the template displays the following text, localized for the authenticated user:

The system set up your email address user@example.com on your domain example.com.

For more information about variables in localized phrases, read CPAN's Locale::Maketext::Utils documentation.

Conditionals

To display different localized phrases based on a variable's value, use IF and ELSE conditions:

[% IF country_name %]
   [% locale.maketext('This computer's location appears to be: [_1] ([_2]).', country_name, country_code) %]
[% ELSE %]
   [% locale.maketext('The system failed to look up the IP address's geographical origin because of an error: [_1]', country_lookup_error) %]
[% END %]

Line 1 and 2 set an IF condition that displays a string if the country_name variable exists and has a value.
Line 3 and 4 set up an ELSE condition that displays an alternate string if the first condition's requirements are not met.
Line 5 ends the conditional statement.