Provided by: libtemplate-plugin-gettext-perl_1.0-1_all 
NAME
Template::Plugin::Gettext - Gettext Support For the Template Toolkit Version 2
SYNOPSIS
Load the plug-in in templates:
[% USE Gettext('com.textdomain.my', 'fr', 'utf-8', 'DIRECTORIES'...) %]
[% Gettext.gettext('Hello, world!') %]
[% 'Hello, world!' | gettext %]
Or alias "Gettext":
[% USE gtx = Gettext('com.textdomain.my', 'fr', 'utf-8', 'DIRECTORIES'...) %]
[% gtx.gettext('Hello, world!') %]
Use method invocations:
[% Gettext.gettext("Hello, world!") %]
[% Gettext.xgettext("Hello, {name}!", name => 'John Doe') %]
Or filters (without the prefix):
[% FILTER gettext %]
Hello, world!
[% END %]
[% 'Hello, world!' | gettext %]
[% FILTER xgettext(name => 'John Doe') %]
Hello, {name}!
[% END %]
You have a multitude of methods available:
[% gtx.gettext("Hello, user!") %]
[% gtx.xgettext("Hello, {user}!", user => 'John Doe') %]
[% gtx.ngettext("One document deleted.",
"Multiple documents deleted."),
42) %]
[% gtx.nxgettext("One document deleted.",
"{num} documents deleted."),
42,
num => 42) %]
[% gtx.npgettext("context..."
"One document deleted.",
"Multiple documents deleted."),
42) %]
[% gtx.npxgettext("context...",
"One document deleted.",
"{num} documents deleted."),
42,
num => 42) %]
DESCRIPTION
The Template::Plugin::Gettext plug-in makes the GNU gettext API
<https://www.gnu.org/software/gettext/> available for documents using the Template Toolkit
version 2 <http://template-toolkit.org/>. See
<https://github.com/gflohr/Template-Plugin-Gettext> for an overall picture and the
recommended tool-chain.
FUNCTIONS
The following methods produce translatable content:
[% gtx.gettext(STRING) %]
Retrieves the translation for STRING.
[% gtx.xgettext(STRING, PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2, ...) %]
Gets the translation for a string with placeholders and interpolates values into it.
Placeholders have the format <{PLACEHOLDER}>. For a literal left curly brace you can
use this hack:
[% gtx.xgettext("String with {LBRACE}PLACEHOLDERS{RBRACE}",
LBRACE => "{", RBRACE => "}") %]
[% gtx.pgettext(CONTEXT, STRING) %]
Retrieves the translation for STRING in context CONTEXT. You should use message
context to disambiguate identical strings that require different translations
depending on the context. See this example for an explanation:
[% gtx.gettext("State: ") %]
[% gtx.gettext("Open")] | [% gtx.gettext("Close") %]
[% gtx.gettext("Menu:") %]
[% gtx.pgettext("menu", "Open")]
[% gtx.gettext("Save")]
[% gtx.gettext("Save As")]
[% gtx.pgettext("menu", "Close")]
The strings "Open" and "Close" in line 2 are adjectives. As
menu entries they are verb forms and will have a different
translation in many languages.
In doubt: Only use contexts if one of your translators complains
about a message having multiple meanings.
[% gtx.pxgettext(CONTEXT, STRING, PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2) %]
Get the translation for STRING with placeholders in context CONTEXT. This is a
mixture of "xgettext()" and "pgettext()" above.
[% gtx.nxgettext(SINGULAR, PLURAL, COUNT, PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2)
%]
Retrieves the translation for the string with the singular form SINGULAR and the
plural from PLURAL, both possibly containing placeholders. The correct form is picked
based upon the third argument COUNT.
Example:
[% gtx.nxgettext("One document deleted",
"{num} documents deleted"),
count,
num => count) %]
In English this will produce "42 documents deleted" if the variable count has the
value 42. It will produce "One document deleted" if the variable count has the value
1.
In other languages, the rules for plural forms may be a lot simpler (for example
Chinese, which has no plural) or a lot more complicated (for example Russian with two
or Slovenian with even 3 plural forms). Using ngettext() gives your translators the
chance to provide syntactically correct translations for these cases.
[% gtx.npxgettext(CONTEXT, SINGULAR, PLURAL, COUNT, PLACEHOLDER1 => VALUE1, PLACEHOLDER2
=> VALUE2) %]
Putting it all together: For message context CONTEXT the translation for a message in
SINGULAR and PLURAL is retrieved based on the argument COUNT. Possible placeholders
are expanded.
The function is a mixture of xgettext(), ngettext(), and pgettext(), see above!
[% gtx.ngettext(SINGULAR, PLURAL, COUNT) %]
Useless function, provided for completeness. Use nxgettext() instead, so that you can
interpolate the value of COUNT!
[% gtx.npgettext(CONTEXT, SINGULAR, PLURAL, COUNT) %]
Useless function, provided for completeness. Use npxgettext() instead, so that you
can interpolate the value of COUNT!
In fact, you have also all the keywords used for "FILTERS" available but those not listed
here have such an odd ordering of arguments that they are not listed here.
FILTERS
The entire gettext API is also exposed as a filter. There are two things to note here:
• When used as filters, you don't prefix the method names. It' s "gettext" not
"Gettext.gettext" or "gtx.gettext()".
• The filters with message contexts have rather strange names, for example:
[% FILTER gettextp("greeting") %]
Hello, world!
[% END %]
or 100 % equivalent:
[% 'Hello, world!' | gettextp("greeting") %]
Why? The text between FILTER and END resp. the text in front of the pipe symbol | is
always the first argument. This plug-in therefore tries to make the first argument
the most significant one. Nobody stops you from writing the following:
[% FILTER pgettext("Hello, world!") %]
greeting
[% END %]
or again 100 % equivalent:
[% 'greeting' | pgettext("Hello, world!") %]
It produces exactly the same results as above but it looks a little bit odd, doesn't
it?
It would have been arguably better understandable to silently reorder the arguments,
when using the plug-in as a filter. But it would break extraction of your strings
with xgettext-tt2 (Locale::XGettext::TT2) because the string extractor would then
confuse the arguments.
But stay relaxed! Message contexts are rarely needed, and when you need them, you have
to live with this little weirdness.
In order to avoid confusion, those filters that would not have the translatable string
(in the singular form) where one would expect it, are not documented here.
You can use the following filters:
[% STRING | gettext %]
[% FILTER gettext %]STRING[% FILTER %]
Retrieves the translation for STRING.
[% STRING | xgettext(PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2, ...) %]
[% FILTER xgettext(PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2, ...) %]STRING[% END %]
Gets the translation for a string with placeholders and interpolates values into it.
Placeholders have the format <{PLACEHOLDER}>. For a literal left curly brace you can
use this hack:
[% "String with {LBRACE}PLACEHOLDERS{RBRACE}" | xgettext(LBRACE => "{", RBRACE => "}") %]
[% STRING | gettextp(CONTEXT) %]
[% FILTER gettextp(CONTEXT) %]STRING[% END %]
Retrieves the translation for STRING in context CONTEXT. You should use message
context to disambiguate identical strings that require different translations
depending on the context. See the docuemntation for pgettext() in "FUNCTIONS" above
for more details!
[% STRING | xgettextp(CONTEXT, STRING, PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2) %]
[% FILTER xgettextp(CONTEXT, STRING, PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2)
%]STRING[% END %]
Get the translation for STRING with placeholders in context CONTEXT. This is a
mixture of "xgettext()" and "pgettext()" above.
[% SINGULAR | nxgettext(PLURAL, COUNT, PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2) %]
[% FILTER nxgettext(PLURAL, COUNT, PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2)
%]SINGULAR[% END %]
Retrieves the translation for the string with the singular form SINGULAR and the
plural from PLURAL, both possibly containing placeholders. The correct form is picked
based upon the third argument COUNT.
Example:
[% "One document deleted" | nxgettext("{num} documents deleted"),
count,
num => count) %]
In English this will produce "42 documents deleted" if the variable count has the
value 42. It will produce "One document deleted" if the variable count has the value
1.
In other languages, the rules for plural forms may be a lot simpler (for example
Chinese, which has no plural) or a lot more complicated (for example Russian with two
or Slovenian with even 3 plural forms). Using ngettext() gives your translators the
chance to provide syntactically correct translations for these cases.
[% SINGULAR | nxgettextp(PLURAL, COUNT, CONTEXT, PLACEHOLDER1 => VALUE1, PLACEHOLDER2 =>
VALUE2) %]
[% FILTER nxgettextp(PLURAL, COUNT, CONTEXT, PLACEHOLDER1 => VALUE1, PLACEHOLDER2 =>
VALUE2) %]SINGULAR[% END %]
Putting it all together: For message context CONTEXT the translation for a message in
SINGULAR and PLURAL is retrieved based on the argument COUNT. Possible placeholders
are expanded.
The filter is a mixture of xgettext(), ngettext(), and pgettext(), see above!
[% SINGULAR | ngettext(PLURAL, COUNT) %]
[% FILTER ngettext(PLURAL, COUNT) %]SINGULAR[% END %]
Useless filter, provided for completeness. Use nxgettext() instead, so that you can
interpolate the value of COUNT!
[% SINGULAR | ngettextp[(PLURAL, COUNT, CONTEXT) %]
[% FILTER | ngettextp[(PLURAL, COUNT, CONTEXT) %]SINGULAR[% END %]
Useless filter, provided for completeness. Use nxgettextp() instead, so that you can
interpolate the value of COUNT!
[% debug_locale %]
The plug-in implicitly calls web_set_locale() (see Locale::Util) if a language was
specified in the USE statement. The function debug_locale() gives you the return
value of the call for debugging purposes. Example:
[% USE gtx = Gettext('com.mydomain.www', de') %]
Using locale [% debug_locale() %].
This way, you can determine whether setting the specified locale actually worked.
CLASS METHODS
textdomains
Returns a hash where the keys are the textdomains found in templates that invoked the
plug-in, and the values are the corresponding template file names.
The purpose of this method is to allow harvesting files that should be processed by
xgettext-tt2.
If the template is either "input text" or "input file handle", the template variable
"gettext_filename" - if existing - is assumed as the template name. Rationale: "input
text" and "input file handle" are used by the Template Toolkit as aliases, when
reading from a scalar or a file handle.
resetTextdomains
Resets the hash described above for textdomain() to its initial, empty state.
COPYRIGHT
Copyright (C) 2016-2018 Guido Flohr (http://www.guido-flohr.net/). License LGPLv3+: GNU
General Public License version 3 or later <http://gnu.org/licenses/lgpl.html>. This is
free software: you are free to change and redistribute it. There is NO WARRANTY, to the
extent permitted by law. Copyright (C) 2016-2018 Guido Flohr <guido.flohr@cantanea.com>,
all rights reserved.
SEE ALSO
Template, Template::Manual::Filters, xgettext-tt2, perl