NAME

Log::Report::Extract::Template - Collect translatable strings from templates

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 with all files which changed since last processing and the existing PO files will get updated accordingly. If no translations exist yet, one textdomain/xx.po file will be created.

METHODS

Constructors

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|REGEX

See the DETAILS section below for a detailed explenation.

Accessors

$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

$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|REGEX

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.

Your own regular expression

If you do not have a format which is predefined, then you can pass-in your own regular expression. Be sure it captures three components: the beginning of the markup, the msgid to be included in the translation table, and the ending of the markup.

Example:

   pattern => qr/(<")(.*?)(">)/

This would match

   <"Hello, World">

The markup compenents must contain all allowed white-spacing, to be able to produce the correct line-numbers. Enclosing single and double quotes aroung the msgid will get removed, if still present after the match.

This example is simplifying too much: your syntax should support parameters and messages which can be in singular or plural form. The next section shows a sufficiently powerful syntax.

Predefined for Template::Toolkit

There is not a single convertion for translations in Template::Toolkit, 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|plural", count, key => value, ...) %]

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);

   ... your 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 = ...;   # specified with xgettext-perl
       my $lang       = ...;   # how do you figure that out?
       $translator->TemplateToolkit($textdomain, $lang, @_);
   }

   ... to generate the pod tables, run in the shell something like
   xgettext-perl -p $lexicons --template TT2-loc \
      --domain $textdomain  templates/

SEE ALSO

This module is part of Log-Report distribution version 0.96, built on August 31, 2012. Website: http://perl.overmeer.net/log-report/

LICENSE

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

perl -MCPAN -e shell
install Log::Report