Template::Multilingual::Parser(3pm)

Template::Multilingual::Parser3pm

Multilingual template parser

Usage

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

Overview

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

Releases

10 releases since Debian 4.0 (Etch); the text changed 5 times.

  1. 4.0
  2. 5.0
  3. 6.0–8
  4. 9–10
  5. 11
  6. 12–13

Author

Eric Cholet, "<[email protected]>"

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 "[email protected]", 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.

From libtemplate-multilingual-perl 1.00-3 in Debian 13 (Trixie). Parsed by carta from the page's man source.