Templa...ingual(3pm)

💖 NAME 💖

Template::Multilingual — multilingual templates for Template Toolkit, bestie. Yes, your templates can speak multiple languages now and honestly? It's giving globalization era. 🌍✨

---

🌈 SYNOPSIS 🌈

So this class is a subclass of Template Toolkit's Template class, and what it does is support multilingual templates — templates that contain text in several languages at once. Iconic behaviour, truly.

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

Then you just tell it which language to use when processing the template:

use Template::Multilingual;

my $template = Template::Multilingual->new();
$template->language('en');
$template->process('example.ttml');

And ooh, plot twist, you can also hand it the name of the template variable that's gonna hold the language:

my $template = Template::Multilingual->new(LANGUAGE_VAR => 'foo');
$template->process('example.ttml', { foo => 'en' });

---

🎀 METHODS 🎀

✨ new(\%params)

The new() constructor creates a new template object and returns a reference to it. You can pass a reference to a hash as a parameter to give it configuration values. Classic.

Configuration values are all the valid Template superclass options, plus one that's specific to this class. Main character option energy:

💅 LANGUAGE_VAR

The LANGUAGE_VAR option sets the name of the template variable that contains the current language. Very much "you name it, we find it".

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

Heads up bestie: if this option is set, your code is responsible for setting that variable's value to the current language when you process the template. Calling language() will have no effect. Like, zero. None. Don't do it and expect anything. 😭

If this option is not set, it defaults to language. Simple as that.

✨ language($lcode)

Specify the language to be used when processing the template. Any string that matches \w+ is fine, but we suggest sticking to ISO-639, which provides 2-letter codes for common languages and 3-letter codes for many others. It's the standard, it's the vibe, use it. 🦋

✨ process

Used exactly as the original Template Toolkit process method. No notes, same energy.

Be sure to call language before calling process. Order matters, bestie. This is not a drill. 🔥

---

🌸 LANGUAGE SUBTAG HANDLING 🌸

This module supports language subtags to express variants, e.g. en_US or en-US. Slay. 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 — it's giving "I got you, close enough" 🫶

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 — alphabetical, not chronological, not vibes-based. The alphabet decides. 📚

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>. Legend. Respect the author. 💜

---

💀 BUGS 💀

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

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

Use this instead, bestie, this is the way:

[% 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. (Sad but true. We don't make the rules. 😭)

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. Group chat but for bugs. 🍓

---

🦋 SEE ALSO 🦋

• If you are already using your own Template subclass, you may find it easier to use Template::Multilingual::Parser instead. Lowkey a glow-up.
• 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. Periodt. ✨

---

Okay that's the whole page, bestie, you made it to the end, so proud of you. 🥹 This one's from perl v5.34.0, dated 2022-06-17, and it lives in the Template::Multilingual manual page (section 3pm) of the User Contributed Perl Documentation. Go forth and translate everything. 🌈💅🫶