.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Log::Report::Extract::Template 3pm"
.TH Log::Report::Extract::Template 3pm "2018-04-16" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::Report::Extract::Template \- collect translatable strings from template files
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 2
\& Log::Report::Extract::Template
\&   is a Log::Report::Extract
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& # 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 => \*(Aq/usr/share/locale\*(Aq
\&   , domain  => \*(Aqmy\-web\-site\*(Aq
\&   , pattern => \*(AqTT2\-loc\*(Aq
\&   );
\& $extr\->process(\*(Aqwebsite/page.html\*(Aq);  # 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 %]
\& [% \*(AqGreetings {name}\*(Aq | loc(name => client.name) %]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module helps maintaining the \s-1POT\s0 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.
.PP
After initiation, the \fIprocess()\fR method needs to be called for each file
in the domain  and the existing \s-1PO\s0 files will get updated accordingly.
.PP
If no translations exist yet, one \f(CW\*(C`$textdomain.po\*(C'\fR file will be
created as point to start.  Copy that file into \f(CW\*(C`$textdomain/$lang.po\*(C'\fR
.PP
Extends \*(L"\s-1DESCRIPTION\*(R"\s0 in Log::Report::Extract.
.SH "METHODS"
.IX Header "METHODS"
Extends \*(L"\s-1METHODS\*(R"\s0 in Log::Report::Extract.
.SS "Constructors"
.IX Subsection "Constructors"
Extends \*(L"Constructors\*(R" in Log::Report::Extract.
.IP "Log::Report::Extract::Template\->\fBnew\fR(%options)" 4
.IX Item "Log::Report::Extract::Template->new(%options)"
.Vb 5
\& \-Option \-\-Defined in          \-\-Default
\&  charset  Log::Report::Extract  \*(Aqutf\-8\*(Aq
\&  domain                         <required>
\&  lexicon  Log::Report::Extract  <required>
\&  pattern                        <undef>
.Ve
.RS 4
.IP "charset => \s-1STRING\s0" 2
.IX Item "charset => STRING"
.PD 0
.IP "domain => \s-1DOMAIN\s0" 2
.IX Item "domain => DOMAIN"
.PD
There is no syntax for specifying domains in templates (yet), so you
must be explicit about the collection we are making now.
.IP "lexicon => \s-1DIRECTORY\s0" 2
.IX Item "lexicon => DIRECTORY"
.PD 0
.IP "pattern => PREDEFINED|CODE" 2
.IX Item "pattern => PREDEFINED|CODE"
.PD
See the \s-1DETAILS\s0 section below for a detailed explenation.
.RE
.RS 4
.RE
.SS "Accessors"
.IX Subsection "Accessors"
Extends \*(L"Accessors\*(R" in Log::Report::Extract.
.ie n .IP "$obj\->\fBaddPot\fR($domain, $pot, %options)" 4
.el .IP "\f(CW$obj\fR\->\fBaddPot\fR($domain, \f(CW$pot\fR, \f(CW%options\fR)" 4
.IX Item "$obj->addPot($domain, $pot, %options)"
Inherited, see \*(L"Accessors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBcharset\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBcharset\fR()" 4
.IX Item "$obj->charset()"
Inherited, see \*(L"Accessors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBdomain\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBdomain\fR()" 4
.IX Item "$obj->domain()"
.PD 0
.ie n .IP "$obj\->\fBdomains\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBdomains\fR()" 4
.IX Item "$obj->domains()"
.PD
Inherited, see \*(L"Accessors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBindex\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBindex\fR()" 4
.IX Item "$obj->index()"
Inherited, see \*(L"Accessors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBpattern\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBpattern\fR()" 4
.IX Item "$obj->pattern()"
.PD 0
.ie n .IP "$obj\->\fBpots\fR($domain)" 4
.el .IP "\f(CW$obj\fR\->\fBpots\fR($domain)" 4
.IX Item "$obj->pots($domain)"
.PD
Inherited, see \*(L"Accessors\*(R" in Log::Report::Extract
.SS "Processors"
.IX Subsection "Processors"
Extends \*(L"Processors\*(R" in Log::Report::Extract.
.ie n .IP "$obj\->\fBcleanup\fR(%options)" 4
.el .IP "\f(CW$obj\fR\->\fBcleanup\fR(%options)" 4
.IX Item "$obj->cleanup(%options)"
Inherited, see \*(L"Processors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBprocess\fR($filename, %options)" 4
.el .IP "\f(CW$obj\fR\->\fBprocess\fR($filename, \f(CW%options\fR)" 4
.IX Item "$obj->process($filename, %options)"
Update the domains mentioned in the \f(CW$filename\fR.  All textdomains defined
in the file will get updated automatically, but not written before
all files where processed.
.Sp
.Vb 3
\& \-Option \-\-Default
\&  charset  \*(Aqutf\-8\*(Aq
\&  pattern  <from new(pattern)>
.Ve
.RS 4
.IP "charset => \s-1STRING\s0" 2
.IX Item "charset => STRING"
The character encoding used in this template file.
.IP "pattern => PREDEFINED|CODE" 2
.IX Item "pattern => PREDEFINED|CODE"
Read the \s-1DETAILS\s0 section about this.
.RE
.RS 4
.RE
.ie n .IP "$obj\->\fBshowStats\fR( [$domains] )" 4
.el .IP "\f(CW$obj\fR\->\fBshowStats\fR( [$domains] )" 4
.IX Item "$obj->showStats( [$domains] )"
Inherited, see \*(L"Processors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBstore\fR( $domain, $filename, $linenr, $context, $msg, [$msg_plural] )" 4
.el .IP "\f(CW$obj\fR\->\fBstore\fR( \f(CW$domain\fR, \f(CW$filename\fR, \f(CW$linenr\fR, \f(CW$context\fR, \f(CW$msg\fR, [$msg_plural] )" 4
.IX Item "$obj->store( $domain, $filename, $linenr, $context, $msg, [$msg_plural] )"
Inherited, see \*(L"Processors\*(R" in Log::Report::Extract
.ie n .IP "$obj\->\fBwrite\fR( [$domain] )" 4
.el .IP "\f(CW$obj\fR\->\fBwrite\fR( [$domain] )" 4
.IX Item "$obj->write( [$domain] )"
Inherited, see \*(L"Processors\*(R" in Log::Report::Extract
.SH "DETAILS"
.IX Header "DETAILS"
.SS "Scan Patterns"
.IX Subsection "Scan Patterns"
Various template systems use different conventions for denoting strings
to be translated.
.PP
\fIPredefined for Template-Toolkit\fR
.IX Subsection "Predefined for Template-Toolkit"
.PP
There is not a single convention for translations in \f(CW\*(C`Template\-Toolkit\*(C'\fR
(see Template), so you need to specify which version \s-1TT\s0 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.
.PP
For instance
.PP
.Vb 1
\&   pattern => \*(AqTT2\-loc\*(Aq
.Ve
.PP
will scan for
.PP
.Vb 3
\&  [% loc("msgid", key => value, ...) %]
\&  [% loc(\*(Aqmsgid\*(Aq, key => value, ...) %]
\&  [% loc("msgid|plural", count, key => value, ...) %]
\& 
\&  [% INCLUDE
\&       title = loc(\*(Aqsomething\*(Aq)
\&   %]
\& 
\&  [% | loc(n => name) %]hi {n}[% END %]
\&  [% \*(Aqhi {n}\*(Aq | loc(n => name) %]
.Ve
.PP
For \s-1TT1,\s0 the brackets can either be '[%...%]' or '%%...%%'.  The function
name is treated case-sensitive.  Some people prefer 'l()' or 'L()'.
.PP
The code needed
.PP
.Vb 5
\&  # during initiation of the webserver, once in your script (before fork)
\&  my $lexicons   = \*(Aqsome\-directory\-for\-translation\-tables\*(Aq;
\&  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}  = \e&translate;           # <\-\-\- this is extra
\&
\&     my $output    = \*(Aq\*(Aq;
\&     my $templater = Template\->new(...);
\&     $templater\->process($template_fn, $vars, \e$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);
\&  }
.Ve
.PP
To generate the pod tables, run in the shell something like
.PP
.Vb 2
\&  xgettext\-perl \-p $lexicons \-\-template TT2\-loc \e
\&      \-\-domain $textdomain  $templates_dir
.Ve
.PP
If you want to implement your own extractor \-\-to avoid \f(CW\*(C`xgettext\-perl\*(C'\fR\-\-
you need to run something like this:
.PP
.Vb 8
\&  my $extr = Log::Report::Extract::Template\->new
\&    ( lexicon => $output
\&    , charset => \*(Aqutf\-8\*(Aq
\&    , domain  => $domain
\&    , pattern => \*(AqTT2\-loc\*(Aq
\&    );
\&  $extr\->process($_) for @filenames;
\&  $extr\->write;
.Ve
.SS "Use in combination with contexts"
.IX Subsection "Use in combination with contexts"
This example extends the previous with using context sensitive translations,
as implemented by Log::Report::Translator::Context.
.PP
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 \s-1TT2\s0
template:
.PP
.Vb 1
\&  [% loc("{name<gender} forgot his key", name => person.name) %]
.Ve
.PP
The extraction script \fIxgettext-perl\fR will expand this into two records
in the \s-1PO\s0 file, respectively with msgctxt attribute 'gender=male' and
\&'gender=female'.
.PP
When your PO-files are not generated by 'xgettext\-perl', you do not need
a separate domain configuration file:
.PP
.Vb 4
\&  $domain\->configure
\&    ( context_rules => +{gender => [\*(Aqmale\*(Aq,\*(Aqfemale\*(Aq]}
\&    , translator    => $translator
\&    );
.Ve
.PP
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.
.PP
.Vb 5
\&  # add context_rules either explicit or via \*(Aqconfig\*(Aq filename
\&  $domain\->configure
\&    ( config     => \*(Aqmy/own/$domain.conf\*(Aq
\&    , translator => $translator
\&    );
.Ve
.PP
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)
.PP
.Vb 2
\&  $domain\->setContext( +{gender => \*(Aqmale\*(Aq} );  # or (\*(Aqgender=male\*(Aq)
\&  $domain\->setContext( "gender=male" );        # same
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Log-Report-Lexicon distribution version 1.11,
built on March 22, 2018. Website: \fIhttp://perl.overmeer.net/CPAN/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2007\-2018 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://dev.perl.org/licenses/\fR