use Log::Report::Template; my $templater = Log::Report::Template->new(%config); $templater->addTextdomain(name => "Tic", lexicon => ...); $templater->process('template_file.tt', \%vars);
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 (by default called 'loc()') to your template text. That function will perform dark magic to collect the translation from translation tables, and fill in values. For instance:
<div>Price: [% price %]</div> # no translation <div>[% loc("Price: {price}") %]</div> # translation optional
It's quite a lot of work to make your templates translatable. Please read the DETAILS section before you start using this module.
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()'.
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()
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
Sometimes, computation of objects is expensive: you never know. So, you may try to avoid repeated computation. In the follow example, "soldOn" is collected/computed twice:
[% IF product.soldOn %] <td>[% loc("Sold on {product.soldOn DATE}")</td> [% END %]
The performance is predictable optimal with:
[% sold_on = product.soldOn; IF sold_on %] <td>[% loc("Sold on {sold_on DATE}")</td> [% END %]
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> [% 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}") %]
You may define a textdomain without doing any translations (yet) However, when you start translating, you will need to maintain translation tables which are in PO-format. PO-files can be maintained with a wide variety of tools, for instance poedit, Pootle, virtaal, GTranslator, Lokalize, or Webtranslateit.
Start with desiging a domain structure. Probably, you want to create a separate domain for the templates (external texts in many languages) and your Perl program (internal texts with few languages).
Pick a lexicon directory, which is also inside your version control setup, for instance your GIT repository. Some po-editors can work together with various version control systems.
Now, start using this module. There are two ways: either by creating it as object, or by extension.
### As object # Somewhere in your code use Log::Report::Template; my $templater = Log::Report::Template->new(%config); $templater->addTextdomain(...); $templater->process('template_file.tt', \%vars); # runtime $templater->extract(...); # rarely, "off-line"
Some way or another, you want to be able to share the creation of the templater and configuration of the textdomain between the run-time use and the irregular (off-line) extraction of msgids.
The alternative is via extension:
### By extension # Somewhere in your code: use My::Template; my $templater = My::Template->new; $templater->process('template_file.tt', \%vars); # File lib/My/Template.pm package My::Template; use parent 'Log::Report::Template'; sub init($) { my ($self, $args) = @_; # add %config into %$args $self->SUPER::init($args); $self->addTextdomain(...); $self; } 1;
The second solution requires a little bit of experience with OO, but is easier to maintain and to share.
The first time you run extract(), you will see a file being created
in $lexicon/$textdomain-$charset.po
. That file will be left empty:
copy it to start a new translation.
There are many ways to structure PO-files. Which structure used, is
detected automatically by Log::Report::Lexicon. My personal preference
is $lexicon/$textdomain/$language-$charset.po
. On Unix-like systems,
you would do:
# Start a new language mkdir mylexicon/mydomain cp mylexicon/mydomain-utf8.po mylexicon/mydomain/nl_NL-utf8.po # fill the nl_NL-utf8.po file with the translation poedit mylexicon/mydomain/nl_NL-utf8.po # add the file to your version control system git add mylexicon/mydomain/nl_NL-utf8.po
Now, when your program sets the locale to 'nl-NL', it should start translating to Dutch. If it doesn't, it is not always easy to figure-out what is wrong...
You have to call extract() when msgids have changed or added, to have the PO-tables updated. The language specific tables will get updated automatically... look for msgids which are 'fuzzy' (need update)
You may also use the external program xgettext-perl
, which is
shipped with the Log::Report::Lexicon distribution.
PO-files are quite large. You can reduce the translation table size by creating a binary "MO"-file for each of them. Log::Report::Lexicon will prefer mo files, if it encounters them, but generation is not (yet) organized via Log::Report components. Search for "msgfmt" as separate tool or CPAN module.