SYNOPSIS

  use Log::Report::Template;
  my $templater = Log::Report::Template->new(%config);
  $templater->process('template_file.tt', \%vars);

DESCRIPTION

This module extends Template, which is the core of Template Toolkit. The main addition is support for translations via the translation framework offered by Log::Report.

You add translations to a template system, by adding calls to some translation function (in this case called 'loc()'). This function performs dark magic to collect the translation from translation tables.

Please read the DETAILS section before you start using this module.

DETAILS

Textdomains

This module uses standard gettext PO-translation tables via the Log::Report::Lexicon distribution. An important role here is for the 'textdomain': the name of the set of translation tables.

For code, you say "use Log::Report '<textdomain>;" in each related module (pm file). We cannot do achieve comparible syntax with Template Toolkit: you must specify the textdomain before the templates get processed.

Your website may contain multiple separate sets of templates. For instance, a standard website implementation with some local extensions. The only way to get that to work, is by using different translation functions: one textdomain may use 'loc()', where an other uses 'L()'.

Supported syntax

Translation syntax

Let say that your translation function is called 'loc', which is the default name. Then, you can use that name as simple function:

  [% loc("msgid", key => value, ...) %]
  [% loc('msgid', key => value, ...) %]
  [% loc("msgid|plural", count, key => value, ...) %]
  [% INCLUDE
       title = loc('something')
   %]

But also as filter. Although filters and functions work differently internally in Template Toolkit, it is convenient to permit both syntaxes.

  [% | loc(key => value, ...) %]msgid[% END %]
  [% 'msgid' | loc(key => value) %]
  [% "msgid" | loc(key => value) %]

As examples

  [% loc("hi {n}", n => name) %]
  [% | loc(n => name) %]hi {n}[% END %]
  [% "hi {n}" | loc(n => name) %]

These syntaxes work exacly like translations with Log::Report for your Perl programs. Compare this with:

  __x"hi {n}", n => name;    # equivalent to
  __x("hi {n}", n => name);  # replace __x() by loc()

Translation syntax, more magic

With TT, we can add a simplificition which we cannot offer for Perl translations: TT variables are dynamic and stored in the stash which we can access. Therefore, we can lookup "accidentally" missed parameters.

  [% SET name = 'John Doe' %]
  [% loc("Hi {name}", name => name) %]  # looks silly
  [% loc("Hi {name}") %]                # uses TT stash directly

Translation into HTML

Usually, when data is passed from the program's internal to the template, it should get encoded into HTML to escape some characters. Typical TT code:

  Title&gt; [% title | html %]

When your insert is produced by the localizer, you can do this as well (set template_syntax to 'UNKNOWN' first)

  [% loc("Title> {t}", t => title) | html %]

The default TT syntax is 'HTML', which will circumvent the need to use the html filter. In that default case, you only say:

  [% loc("Title> {t}", t => title) %]
  [% loc("Title> {title}") %]  # short form, see previous section

When the title is already escaped for HTML, you can circumvent that by using tags which end on 'html':

  [% loc("Title> {t_html}", t_html => title) %]

  [% SET title_html = html(title) %]
  [% loc("Title> {title_html}") %]