NAME

SYNOPSIS

    [% 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

FUNCTIONS

[% 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.

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

SEE ALSO