Localizing Extensions

If you create a module, feather, or theme, it's recommended that you pass all user-facing text strings to Chyrp Lite's localization helper functions so that your extension can be translated to different languages with ease.

PHP Functions

__($text, $domain)

This helper function passes your text string through the translation engine. The return value is the translated string if a translation file has been loaded for your domain, otherwise your original string will be returned to you. $domain is the non-camelized folder name of your module or feather. If no domain is supplied, a translation will be searched for in the core "chyrp" domain.

_p($single, $plural, $number, $domain)

This helper function passes your text string through the translation engine and based on the value of $number decides if a singular or plural variation of the string is appropriate. The return value is one of: translated singular string or translated plural string (if a translation file has been loaded for your domain), original singular string, original plural string.

_f($string, $args, $domain)

This helper function passes your text string through the translation engine and additionally does sprintf() formatting using a single value or an array of arguments supplied as $args. The return value is the translated and formatted string if a translation file has been loaded for your domain, otherwise your original string will be formatted and returned to you.

Twig Filters

Localization in Twig is implemented using the filter system.

{{ "string" | translate }}

This filter passes your text string through the translation engine. The return value is the translated string if a translation file has been loaded for your domain, otherwise your original string will be returned to you.

If you are creating a blog theme, you do not need to supply a domain name to the filter; this will be handled transparently by the Twig runtime. However if you are creating administration pages for your module, it is necessary to provide the domain by supplying it to the filter as an argument: translate("domain").

{{ "string" | translate_plural("plural", number, "domain") }}

This filter passes your text string through the translation engine and based on the value of number decides if a singular or plural variation of the string is appropriate. The return value is one of: translated singular string or translated plural string (if a translation file has been loaded for your domain), original singular string, original plural string.

{{ "string" | format(value) }}

This filter does sprintf()formatting using a single supplied value. Twig does not have a direct counterpart to the _f() helper function but equivalent functionality is possible by stacking filters together, for example:

{{ "foo %s baz" | translate | format("bar") }}

This Twig statement will return:

foo bar baz

To ensure the word "bar" is also translated, do the following:

{{ "foo %s baz" | translate | format("bar" | translate) }}