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 functions so that your extension can be translated to different languages with ease.

Localization Functions

Localization is implemented in PHP using helper functions, and in Twig using the filter system.

Helper 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.

_w($formatting, $when)

This helper function formats and internationalizes a date/time value. A non-numeric when value will be converted using strtotime(). The return value is formatted according to DateTimeInterface formatting rules and internationalized using the IntlDateFormatter class, if available - otherwise date() will be used for a non-internationalized result.

Twig Filters

{{ "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 the supplied value or multiple comma-separated values. 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) }}

{{ "timestamp" | time("format") }}

This filter returns a <time> HTML element containing an internationalized time representation. The timestamp can be numeric or textual, in which case it will be converted using strtotime(). The desired visible time representation is supplied using format and formatted according to DateTimeInterface formatting rules.