METHODS

Constructors

$class->new( %options )

Create a new translator object. You may pass the %options as HASH or PAIRS. By convension, all basic Template Toolkit options are in capitals. Read Template::Config about what they mean. Extension options provided by this module 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'

translate_to

undef

modifiers => ARRAY
Add a list of modifiers to the default set. Modifiers are part of the formatting process, when values get inserted in the translated string. Read Formatter value modifiers.
processing_errors => 'NATIVE'|'EXCEPTION'
The Template Toolkit infrastructure handles errors carefully: undef is returned and you need to call error() to collect it.
template_syntax => 'UNKNOWN'|'HTML'
Linked to String::Print::new(encode_for): the output of the translation is HTML encoded unless the inserted value name ends on _html. Read Translation into HTML
translate_to => LANGUAGE
Globally set the output language of template processing. Usually, this is derived from the logged-in user setting or browser setting. See translateTo().

Attributes

$obj->formatter

Get the String::Print object which formats the messages.

$obj->translateTo( [$language] )

Handling text domains

$obj->addTextdomain( %options )

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.

» Example:
  my $domain = $templater->addTextdomain(
    name     => 'my-project',
    function => 'loc',   # default
  );
$obj->domain( $name )

Returns the textdomain with the specified $name.

$obj->domains

Returns a LIST with all defined textdomains, unsorted.

$obj->extract( %options )

Extract message ids from the templates, and register them to the lexicon. Read section Extracting PO-files how to use this method.

Show statistics will be show when the Log::Report more is VERBOSE or DEBUG.

Option Default

charset

'UTF-8'

filename_match

qr/\.tt2?$/

filenames

undef

write_tables

<true>

charset => CHARSET
filename_match => RegEx
Process all files from the INCLUDE_PATH directories which match this regular expression.
filenames => FILENAME|ARRAY
By default, all filenames from the INCLUDE_PATH directories which match the filename_match are processed, but you may explicitly create a subset by hand.
write_tables => BOOLEAN
When false, the po-files will not get updated.

Template filters

Some common activities in templates are harder when translation is needed. A few TT filters are provided to easy the process.

Formatter value modifiers

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.

Template (Toolkit) base-class

The details of the following functions can be found in the Template manual page. They are included here for reference only.

$obj->error

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.

$obj->process( $template, [\%vars, $output, \%options] )

Process the $template into $output, filling in the %vars.