Create a new translator object. You may pass the options as HASH or PAIRS. By convension, all Template Toolkit options are in capitals. Read Template::Config about what they mean. Extension options are all in lower-case.
In a web-environment, you want to start this before your webserver starts forking.
Option | Default |
---|---|
modifiers | [] |
processing_errors | 'NATIVE' |
template_syntax | 'HTML' |
Create a new Log::Report::Template::Textdomain object. See its new method for the options.
Additional facts about the options: you may specify only_in_directory
as a path. Those directories must be in the INCLUDE_PATH as well.
The (domain) name
must be unique, and the function
not yet in use.
Extract message ids from the templates, and register them to the lexicon.
Option | Default |
---|---|
charset | 'UTF-8' |
filename_match | qr/\.tt2?$/ |
filenames |
|
show_stats | <false> |
write_tables | <true> |
Some common activities in templates are harder when translation is needed. A few TT filters are provided to easy the process.
A typical example of an HTML component which needs translation is
<tr><td>Price:</td><td>20 £</td></tr>
Both the price text as value need to be translated. In plain perl (with Log::Report) you would write
__x"Price: {price £}", price => $product->price # or __x"Price: {p.price £}", p => $product;
In HTML, there seems to be the need for two separate translations, may in the program code. This module (actually String::Print) can be trained to convert money during translation, because '£' is a modifier. The translation for Dutch (via a PO table) could be
"Prijs: {p.price €}"
SO: we want to get both table fields in one translation. Try this:
<tr>[% loc("Price:\t{p.price £}" | cols %]</tr>
In the translation table, you have to place the tabs (backslash-t) as well.
There are two main forms of cols
. The first form is the containerizer:
pass 'cols' a list of container names. The fields in the input string
(as separated by tabs) are wrapped in the named container. The last
container name will be reused for all remaining columns. By default,
everything is wrapped in 'td' containers.
"a\tb\tc" | cols <td>a</td><td>b</td><td>c</td> "a\tb\tc" | cols('td') same "a\tb\tc" | cols('th', 'td') <th>a</th><td>b</td><td>c</td> "a" | cols('div') <div>a</div> loc("a") | cols('div') <div>xxxx</div>
The second form has one pattern, which contains (at least one) '$1' replacement positions. Missing columns for positional parameters will be left blank.
"a\tb\tc" | cols('#$3#$1#') #c#a# "a" | cols('#$3#$1#') ##a# loc("a") | cols('#$3#$1#') #mies#aap#
Some translations will produce more than one line of text. Add '<br>' after each of them.
[% loc('intro-text') | br %] [% | br %][% intro_text %][% END %]
Modifiers simplify the display of values. Read the section about modifiers in String::Print. Here, only some examples are shown.
You can achieve the same transformation with TT vmethods, or with the perl code which drives your website. The advantange is that you can translate them. And they are quite readible.
%-10s
, %2.4f
, etcExactly like format of the perl's internal printf()
(which is
actually being called to do the formatting)
Examples:
# pi in two decimals [% loc("π = {pi %.2f}", pi => 3.14157) %] # show int, no fraction. filesize is a template variable [% loc("file size {size %d}", size => filesize + 0.5) %]
Convert a file size into a nice human readible format.
Examples:
# filesize and fn are passed as variables to the templater [% loc("downloaded {size BYTES} {fn}\n", size => fs, fn => fn) %] # may produce: " 0 B", "25 MB", "1.5 GB", etc
Accept various time syntaxes as value, and translate them into standard formats: year only, date in YYYY-MM-DD, time as 'HH::MM::SS', and various DateTime formats:
Examples:
# shows 'Copyright 2017' [% loc("Copyright {today YEAR}", today => '2017-06-26') %]
# shows 'Created: 2017-06-26' [% loc("Created: {now DATE}", now => '2017-06-26 00:24:15') %] # shows 'Night: 00:24:15' [% loc("Night: {now TIME}", now => '2017-06-26 00:24:15') %] # shows 'Mon Jun 26 00:28:50 CEST 2017' [% loc("Stamp: {now DT(ASC)}", now => 1498429696) %]
When a parameter has no value or is an empty string, the word or string will take its place.
[% loc("visitors: {count //0}", count => 3) %] [% loc("published: {date DT//'not yet'}", date => '') %] [% loc("copyright: {year//2017 YEAR}", year => '2018') %] [% loc("price: {price//5 EUR}", price => product.price %] [% loc("price: {price EUR//unknown}", price => 3 %]
The details of the following functions can be found in the Template manual page. They are included here for reference only.
If the 'processing_errors' option is 'NATIVE' (default), you have to collect the error like this:
$tt->process($template_fn, $vars, ...) or die $tt->error;
When the 'procesing_errors' option is set to 'EXCEPTION', the error is translated into a Log::Report::Exception:
use Log::Report; try { $tt->process($template_fn, $vars, ...) }; print $@->wasFatal if $@;
In the latter solution, the try() is probably only on the level of the highest level: the request handler which catches all kinds of serious errors at once.
Process the $template
into $output
, filling in the %vars
.