Skip to content

Latest commit

 

History

History
156 lines (108 loc) · 4.49 KB

i18n.rst

File metadata and controls

156 lines (108 loc) · 4.49 KB
Raw

The i18n Extension

Configuration

The i18n extension adds gettext support to Twig. It defines one tag, trans.

You need to register this extension before using the trans block:

$twig->addExtension(new Twig_Extensions_Extension_I18n());

Note that you must configure the gettext extension before rendering any internationalized template. Here is a simple configuration example from the PHP documentation:

// Set language to French
putenv('LC_ALL=fr_FR');
setlocale(LC_ALL, 'fr_FR');

// Specify the location of the translation tables
bindtextdomain('myAppPhp', 'includes/locale');
bind_textdomain_codeset('myAppPhp', 'UTF-8');

// Choose domain
textdomain('myAppPhp');

Caution!

The i18n extension only works if the PHP gettext extension is enabled.

Usage

Use the trans block to mark parts in the template as translatable:

{% trans "Hello World!" %}

{% trans string_var %}

{% trans %}
    Hello World!
{% endtrans %}

In a translatable string, you can embed variables:

{% trans %}
    Hello {{ name }}!
{% endtrans %}

During the gettext lookup these placeholders are converted. {{ name }} becomes %name% so the gettext msgid for this string would be Hello %name%!.

Note

{% trans "Hello {{ name }}!" %} is not a valid statement.

If you need to apply filters to the variables, you first need to assign the result to a variable:

{% set name = name|capitalize %}

{% trans %}
    Hello {{ name }}!
{% endtrans %}

To pluralize a translatable string, use the plural block:

{% trans %}
    Hey {{ name }}, I have one apple.
{% plural apple_count %}
    Hey {{ name }}, I have {{ count }} apples.
{% endtrans %}

The plural tag should provide the count used to select the right string. Within the translatable string, the special count variable always contain the count value (here the value of apple_count).

Within an expression or in a tag, you can use the trans filter to translate simple strings or variables:

{{ var|default(default_value|trans) }}

Complex Translations within an Expression or Tag

Translations can be done with both the trans tag and the trans filter. The filter is less powerful as it only works for simple variables or strings. For more complex scenario, like pluralization, you can use a two-step strategy:

{# assign the translation to a temporary variable #}
{% set default_value %}
    {% trans %}
      Hey {{ name }}, I have one apple.
    {% plural apple_count %}
      Hey {{ name }}, I have {{ count }} apples.
    {% endtrans %}
{% endset %}

{# use the temporary variable within an expression #}
{{ var|default(default_value|trans) }}

Extracting Template Strings

If you use the Twig I18n extension, you will probably need to extract the template strings at some point. Unfortunately, the xgettext utility does not understand Twig templates natively. But there is a simple workaround: as Twig converts templates to PHP files, you can use xgettext on the template cache instead.

Create a script that forces the generation of the cache for all your templates. Here is a simple example to get you started:

$tplDir = dirname(__FILE__).'/templates';
$tmpDir = '/tmp/cache/';
$loader = new Twig_Loader_Filesystem($tplDir);

// force auto-reload to always have the latest version of the template
$twig = new Twig_Environment($loader, array(
    'cache' => $tmpDir,
    'auto_reload' => true
));
$twig->addExtension(new Twig_Extensions_Extension_I18n());
// configure Twig the way you want

// iterate over all your templates
foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator($tplDir), RecursiveIteratorIterator::LEAVES_ONLY) as $file)
{
  // force compilation
  $twig->loadTemplate(str_replace($tplDir.'/', '', $file));
}

Use the standard xgettext utility as you would have done with plain PHP code:

xgettext --default-domain=messages -p ./locale --from-code=UTF-8 -n --omit-header -L PHP /tmp/cache/*.php