SYNOPSIS

 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;

 # See script  xgettext-perl

See SYNOPSIS in Log::Report::Extract

DESCRIPTION

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

After initiation, the process() method needs to be called for all files which changed since last processing, 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 DESCRIPTION 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 $fill_in     = { ...all kinds of values... };
      $fill_in->{loc} = \&translate;           # <--- this is extra

      my $output      = '';
      my $templater   = Template->new(...);
      $templater->process($template_fn, $fill_in, \$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;