---
name: "Template::Multilingual::Parser"
section: "3pm"
platform: "linux"
package: "libtemplate-multilingual-perl"
version: "1.00-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Template::Multilingual::Parser"
---

# Template::Multilingual::Parser(3pm)

Multilingual template parser

## 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.