NAME

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

INHERITANCE

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

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

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 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->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, 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 $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;

SEE ALSO

       This  module  is  part  of  Log-Report  distribution  version  0.998, built on October 22, 2013. Website:
       http://perl.overmeer.net/log-report/

LICENSE

       Copyrights 2007-2013 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

perl v5.18.1                                       2013-10-22                Log::Report::Extract::Template(3pm)