Templa...Parser(3pm)

💖 Templa...Parser(3pm) — Template::Multilingual::Parser 💖

okay so bestie, this is a page from the User Contributed Perl Documentation, it lives in section 3pm, and it's literally all about the multilingual template parser. sit down, grab a strawberry, we're doing this 🍓

---

✨ NAME ✨

Template::Multilingual::Parser — the multilingual template parser. that's it, that's the name, iconic.

---

🌈 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'});

look at that. four lines and you're already multilingual, no cap 👑

---

🦋 DESCRIPTION 🦋

so this module is a subclass of Template Toolkit's Template::Parser, and what it does is parse multilingual templates — templates that contain text in several languages. like, the whole point:

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

use this module directly if you've subclassed Template. otherwise, ngl, you'll probably find it easier to just use Template::Multilingual. your call bestie 💅

language codes can be any string that matches \w+, but we suggest sticking to ISO-639, which gives you 2-letter codes for the common languages and 3-letter codes for a whole bunch of others. slay.

---

🎀 METHODS 🎀

new(\%params)

the new() constructor creates and returns a reference to a brand new parser object. you can hand it a reference to a hash as a parameter to feed it configuration values. it's giving very main character energy ✨

parser objects are typically provided as the PARSER option to the Template constructor. iykyk.

configuration values are all valid Template::Parser superclass options, plus one that's specific to this class:

• LANGUAGE_VAR — this option sets the name of the template variable that holds the current language. defaults to language. periodt.

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

you'll need to set this variable with the current language value at request time — usually in your Template subclass' process() method. don't forget, bestie, or it'll be giving chaos 😭

parse($text)

parse() gets called by the Template Toolkit. it parses the multilingual sections out of the input text and translates them into Template Toolkit directives. then that result gets passed along to the Template::Parser superclass. teamwork makes the dream work 🫶

sections

returns a reference to an array of tokenized sections. each section is a reference to a hash with either a nolang key or a lang key. very demure, very mindful.

• a nolang key means the text is outside of any multilingual sections. the value is the text itself.
• a lang key means the text is inside a multilingual section. the value is a reference to a hash, whose keys are language codes and whose values are the corresponding text.

for example, this multilingual template:

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

will parse to these 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, and they are lowkey elegant:

• Exact match: the current language is found in the template. chef's kiss 👩‍🍳

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>" — shoutout to the author, an absolute legend 💜

---

💀 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. not me being picky, that's just how it is 🙈

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>. the author will be notified, and then you'll automatically be notified of progress on your bug as changes get made. closed loop communication, we love to see it 🎀

---

⭐ 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. free as in freedom, bestie 🦋

---

and that's the whole page!! 💖 this one shipped as perl v5.34.0, dated 2022-06-17, under the title Templa...Parser(3pm) — go forth and be multilingual, you absolute icon ✨💅🌈