Provided by: liblog-report-lexicon-perl_1.09-1_all bug

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"

       Extends "DESCRIPTION" in Log::Report::Extract.

METHODS

       Extends "METHODS" in Log::Report::Extract.

   Constructors
       Extends "Constructors" in Log::Report::Extract.

       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
       Extends "Accessors" in Log::Report::Extract.

       $obj->addPot($domain, $pot, %options)
           Inherited, see "Accessors" in Log::Report::Extract

       $obj->charset()
           Inherited, see "Accessors" in Log::Report::Extract

       $obj->domain()
       $obj->domains()
           Inherited, see "Accessors" in Log::Report::Extract

       $obj->index()
           Inherited, see "Accessors" in Log::Report::Extract

       $obj->pattern()
       $obj->pots($domain)
           Inherited, see "Accessors" in Log::Report::Extract

   Processors
       Extends "Processors" in Log::Report::Extract.

       $obj->cleanup(%options)
           Inherited, 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] )
           Inherited, see "Processors" in Log::Report::Extract

       $obj->store( $domain, $filename, $linenr, $context, $msg, [$msg_plural] )
           Inherited, see "Processors" in Log::Report::Extract

       $obj->write( [$domain] )
           Inherited, 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 convention for translations in "Template-Toolkit" (see Template), so
       you need to specify which version TT you use and which function name you want to use.  In
       extreme cases, you may even build separate translation tables by simply providing using
       functions.

       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()' or 'L()'.

       The code needed

         # during initiation of the webserver, once in your script (before fork)
         my $lexicons   = 'some-directory-for-translation-tables';
         my $translator = Log::Report::Translator::POT->new(lexicons => $lexicons);
         my $domain     = textdomain $textdomain;
         $domain->configure(translator => $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;

   Use in combination with contexts
       This example extends the previous with using context sensitive translations, as
       implemented by Log::Report::Translator::Context.

       Let's say that the translation of some of the sentences on the website depend on the
       gender of the addressed person.  An example of the use in a TT2 template:

         [% loc("{name<gender} forgot his key", name => person.name) %]

       The extraction script xgettext-perl will expand this into two records in the PO file,
       respectively with msgctxt attribute 'gender=male' and 'gender=female'.

       When your PO-files are not generated by 'xgettext-perl', you do not need a separate domain
       configuration file:

         $domain->configure
           ( context_rules => +{gender => ['male','female']}
           , translator    => $translator
           );

       When your PO-files are generated by 'xgettext-perl', you need to share the context-rules
       between that msgid extractor and your runtime code. That same file needs to be passed with
       the 'domain' parameter to the script.

         # add context_rules either explicit or via 'config' filename
         $domain->configure
           ( config     => 'my/own/$domain.conf'
           , translator => $translator
           );

       Now, when you generate the pages, you need to set-up the right context.  In this case, we
       set-up the gender of the person who gets addressed.  (The name 'gender' is good for
       examples, but quite non-descriptive.  Maybe 'user_gender' is more maintainable)

         $domain->setContext( +{gender => 'male'} );  # or ('gender=male')
         $domain->setContext( "gender=male" );        # same

SEE ALSO

       This module is part of Log-Report-Lexicon distribution version 1.09, built on August 28,
       2017. Website: http://perl.overmeer.net/log-report/

LICENSE

       Copyrights 2007-2017 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://dev.perl.org/licenses/