=head1 NAME

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

=head1 INHERITANCE

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

=head1 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

=head1 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 L<process()|Log::Report::Extract::Template/"Processors"> 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 C<textdomain/xx.po> file will be created.

=head1 METHODS

=head2 Constructors

=over 4

=item Log::Report::Extract::Template-E<gt>B<new>(OPTIONS)

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

=over 2

=item charset => STRING

=item domain => DOMAIN

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

=item lexicon => DIRECTORY

=item pattern => PREDEFINED|CODE

See the DETAILS section below for a detailed explenation.

=back

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<charset>()

See L<Log::Report::Extract/"Accessors">

=item $obj-E<gt>B<domain>()

=item $obj-E<gt>B<domains>()

See L<Log::Report::Extract/"Accessors">

=item $obj-E<gt>B<index>()

See L<Log::Report::Extract/"Accessors">

=item $obj-E<gt>B<pattern>()

=item $obj-E<gt>B<pots>(DOMAIN)

See L<Log::Report::Extract/"Accessors">

=back

=head2 Processors

=over 4

=item $obj-E<gt>B<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)>

=over 2

=item charset => STRING

The character encoding used in this template file.

=item pattern => PREDEFINED|CODE

Read the DETAILS section about this.

=back

=item $obj-E<gt>B<showStats>([DOMAINs])

See L<Log::Report::Extract/"Processors">

=item $obj-E<gt>B<store>(DOMAIN, FILENAME, LINENR, MSG, [MSG_PLURAL])

See L<Log::Report::Extract/"Processors">

=item $obj-E<gt>B<write>([DOMAIN])

See L<Log::Report::Extract/"Processors">

=back

=head1 DETAILS

=head2 Scan Patterns

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

=head3 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', key => value, ...) %]
   [% loc("msgid|plural", count, key => value, ...) %]
   [% INCLUDE
        title = loc('something')
    %]

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 = ...;   # specified with 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 C<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;

=head1 SEE ALSO

This module is part of Log-Report distribution version 0.99,
built on October 03, 2012. Website: F<http://perl.overmeer.net/log-report/>

=head1 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 F<http://www.perl.com/perl/misc/Artistic.html>