NAME

       Template::Multilingual::Parser - Multilingual template parser

SYNOPSIS

           use Template;
           use Template::Multilingual::Parser;

           my $parser = Template::Multilingual::Parser->new();
           my $template = Template->new(PARSER => $parser);
           $template->process('example.ttml', { language => 'en'});

DESCRIPTION

       This subclass of Template Toolkit's "Template::Parser" parses multilingual templates:
       templates that contain text in several languages.

           <t>
             <en>Hello!</en>
             <fr>Bonjour !</fr>
           </t>

       Use this module directly if you have subclassed "Template", otherwise you may find it
       easier to use "Template::Multilingual".

       Language codes can be any string that matches "\w+", but we suggest sticking to ISO-639
       which provides 2-letter codes for common languages and 3-letter codes for many others.

METHODS

   new(\%params)
       The new() constructor creates and returns a reference to a new parser object. A reference
       to a hash may be supplied as a parameter to provide configuration values.

       Parser objects are typically provided as the "PARSER" option to the "Template"
       constructor.

       Configuration values are all valid "Template::Parser" superclass options, and one specific
       to this class:

       LANGUAGE_VAR
           The LANGUAGE_VAR option can be used to set the name of the template variable which
           contains the current language. Defaults to language.

             my $parser = Template::Multilingual::Parser->new({
                LANGUAGE_VAR => 'global.language',
             });

           You will need to set this variable with the current language value at request time,
           usually in your "Template" subclass' "process()" method.

   parse($text)
       parse() is called by the Template Toolkit. It parses multilingual sections from the input
       text and translates them to Template Toolkit directives. The result is then passed to the
       "Template::Parser" superclass.

   sections
       Returns a reference to an array of tokenized sections. Each section is a reference to hash
       with either a "nolang" key or a "lang" key.

       A "nolang" key denotes text outside of any multilingual sections. The value is the text
       itself.

       A "lang" key denotes text inside a multilingual section. The value is a reference to a
       hash, whose keys are language codes and values the corresponding text. For example, the
       following multilingual template:

         foo <t><fr>bonjour</fr><en>Hello</en></t> bar

       will parse to the following sections:

         [ { nolang => 'foo ' },
           {   lang => { fr => 'bonjour', en => 'hello' } },
           { nolang => ' bar' },
         ]

LANGUAGE SUBTAG HANDLING

       This module supports language subtags to express variants, e.g. "en_US" or "en-US".  Here
       are the rules used for language matching:

       •   Exact match: the current language is found in the template

             language    template                              output
             fr          <fr>foo</fr><fr_CA>bar</fr_CA>        foo
             fr_CA       <fr>foo</fr><fr_CA>bar</fr_CA>        bar

       •   Fallback to the primary language

             language    template                              output
             fr_CA       <fr>foo</fr><fr_BE>bar</fr_BE>        foo

       •   Fallback to first (in alphabetical order) other variant of the primary language

             language    template                              output
             fr          <fr_FR>foo</fr_FR><fr_BE>bar</fr_BE>  bar
             fr_CA       <fr_FR>foo</fr_FR><fr_BE>bar</fr_BE>  bar

AUTHOR

       Eric Cholet, "<cholet@logilune.com>"

BUGS

       Multilingual text sections cannot be used inside TT directives.  The following is illegal
       and will trigger a TT syntax error:

           [% title = "<t><fr>Bonjour</fr><en>Hello</en></t>" %]

       Use this instead:

           [% title = BLOCK %]<t><fr>Bonjour</fr><en>Hello</en></t>[% END %]

       The TAG_STYLE, START_TAG and END_TAG directives are supported, but the TAGS directive is
       not.

       Please report any bugs or feature requests to "bug-template-multilingual@rt.cpan.org", or
       through the web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Multilingual>.  I will be
       notified, and then you'll automatically be notified of progress on your bug as I make
       changes.

SEE ALSO

       Template::Multilingual

       ISO 639-2 Codes for the Representation of Names of Languages:
       http://www.loc.gov/standards/iso639-2/langcodes.html

COPYRIGHT & LICENSE

       Copyright 2009 Eric Cholet, All Rights Reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.