NAME

Log::Report::Extract::Template - collect translatable strings from template files

INHERITANCE

Log::Report::Extract::Template
  is a Log::Report::Extract

SYNOPSIS

# First use of this module: extract msgids from various kinds
# of text-files, usually web templates.
# See script "xgettext-perl" for standard wrapper script

my $extr = Log::Report::Extract::Template->new
  ( lexicon => '/usr/share/locale'
  , domain  => 'my-web-site'
  , pattern => 'TT2-loc'
  );
$extr->process('website/page.html');  # many times
$extr->showStats;
$extr->write;

# Second use: connect to Template::Toolkit
# See DETAILS chapter below

[% loc("Greetings {name},", name => client.name) %]
[% | loc(name => client.name) %]Greetings {name}[% END %]
[% 'Greetings {name}' | loc(name => client.name) %]

DESCRIPTION

This module helps maintaining the POT files which list translatable strings from template files (or other flat text files) by updating the list of message-ids which are kept in them.

After initiation, the process() method needs to be called for each file in the domain and the existing PO files will get updated accordingly.

If no translations exist yet, one $textdomain.po file will be created as point to start. Copy that file into $textdomain/$lang.po

See documentation in the base class.

METHODS

See documentation in the base class.

Constructors

See documentation in the base class.

Log::Report::Extract::Template->new(OPTIONS)

-Option --Defined in          --Default
 charset  Log::Report::Extract  'utf-8'
 domain                         <required>
 lexicon  Log::Report::Extract  <required>
 pattern                        <undef>

charset => STRING

domain => DOMAIN

There is no syntax for specifying domains in templates (yet), so you must be explicit about the collection we are making now.

lexicon => DIRECTORY

pattern => PREDEFINED|CODE

See the DETAILS section below for a detailed explenation.

Accessors

See documentation in the base class.

$obj->charset()

See "Accessors" in Log::Report::Extract

$obj->domain()

$obj->domains()

See "Accessors" in Log::Report::Extract

$obj->index()

See "Accessors" in Log::Report::Extract

$obj->pattern()

$obj->pots(DOMAIN)

See "Accessors" in Log::Report::Extract

Processors

See documentation in the base class.

$obj->cleanup(OPTIONS)

See "Processors" in Log::Report::Extract

$obj->process(FILENAME, OPTIONS)

Update the domains mentioned in the FILENAME. All textdomains defined in the file will get updated automatically, but not written before all files where processed.

-Option --Default
 charset  'utf-8'
 pattern  <from new(pattern)>

charset => STRING

The character encoding used in this template file.

pattern => PREDEFINED|CODE

Read the DETAILS section about this.

$obj->showStats([DOMAINs])

See "Processors" in Log::Report::Extract

$obj->store(DOMAIN, FILENAME, LINENR, CONTEXT, MSG, [MSG_PLURAL])

See "Processors" in Log::Report::Extract

$obj->write([DOMAIN])

See "Processors" in Log::Report::Extract

DETAILS

Scan Patterns

Various template systems use different conventions for denoting strings to be translated.

Predefined for Template-Toolkit

There is not a single convertion for translations in Template-Toolkit (see Template), so you need to specify which version you use and which function you want to run.

For instance

pattern => 'TT2-loc'

will scan for

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

[% INCLUDE
     title = loc('something')
 %]

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

For TT1, the brackets can either be '[%...%]' or '%%...%%'. The function name is treated case-sensitive. Some people prefer 'l()'.

The code needed

... during initiation of the webserver
my $lexicons   = 'some-directory-for-translation-tables';
my $translator = Log::Report::Translator::POT->new(lexicons => $lexicons);
Log::Report->translator($textdomain => $translator);

... your standard template driver
sub handler {
   ...
   my $vars      = { ...all kinds of values... };
   $vars ->{loc} = \&translate;           # <--- this is extra

   my $output    = '';
   my $templater = Template->new(...);
   $templater->process($template_fn, $vars, \$output);
   print $output;
}

... anywhere in the same file
sub translate {
    my $textdomain = ...;   # your choice when running xgettext-perl
    my $lang       = ...;   # how do you figure that out?
    my $msg = Log::Report::Message->fromTemplateToolkit($textdomain, @_);
    $msg->toString($lang);
}

To generate the pod tables, run in the shell something like

xgettext-perl -p $lexicons --template TT2-loc \
   --domain $textdomain  $templates_dir

If you want to implement your own extractor --to avoid xgettext-perl-- you need to run something like this:

my $extr = Log::Report::Extract::Template->new
  ( lexicon => $output
  , charset => 'utf-8'
  , domain  => $domain
  , pattern => 'TT2-loc'
  );
$extr->process($_) for @filenames;
$extr->write;

SEE ALSO

This module is part of Log-Report-Lexicon distribution version 1.00, built on January 05, 2014. Website: http://perl.overmeer.net/log-report/

LICENSE

Copyrights 2007-2014 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html

cpanm Log::Report::Lexicon

perl -MCPAN -e shell
install Log::Report::Lexicon