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%][%FILTERgettext%]STRING[%FILTER%]
Retrieves the translation for STRING.
[%STRING|xgettext(PLACEHOLDER1=>VALUE1,PLACEHOLDER2=>VALUE2,...)%][%FILTERxgettext(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)%][%FILTERgettextp(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)%][%FILTERxgettextp(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)%][%FILTERnxgettext(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)%][%FILTERnxgettextp(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)%][%FILTERngettext(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.
Install Now
PNG Icons
SVG Icons
