README.rst

Twig i18n Extension

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

Code status

Installation

This library can be installed via Composer running the following from the command line:

composer require phpmyadmin/twig-i18n-extension

Configuration

You need to register this extension before using the trans block

use PhpMyAdmin\Twig\Extensions\I18nExtension;

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

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

To add notes for translators, use the notes block:

{% trans %}
    Hey {{ name }}, I have one apple.
{% plural apple_count %}
    Hey {{ name }}, I have {{ count }} apples.
{% notes %}
    This is shown in the user menu. This string should be shorter than 30 chars
{% endtrans %}

You can use notes with or without plural. Once you get your templates compiled you should configure the gettext parser to get something like this: xgettext --add-comments=notes

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.

Using Poedit 2

Poedit 2 has native support for extracting from Twig files and no extra setup is necessary (Pro version).

Using xgettext or Poedit 1

Unfortunately, the xgettext utility does not understand Twig templates natively and neither do tools based on it such as free versions of Poedit. 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

use Twig\Environment;
use Twig\Loader\FilesystemLoader;
use PhpMyAdmin\Twig\Extensions\I18nExtension;

$tplDir = __DIR__ . '/templates';
$tmpDir = '/tmp/cache/';
$loader = new FilesystemLoader($tplDir);

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

// iterate over all your templates
foreach (new RecursiveIteratorIterator(new RecursiveDirectoryIterator($tplDir), RecursiveIteratorIterator::LEAVES_ONLY) as $file)
{
    // force compilation
    if ($file->isFile()) {
        $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

Another workaround is to use Twig Gettext Extractor and extract the template strings right from Poedit.

History

This project was forked in 2019 by the phpMyAdmin team, since it was abandoned by the Twig project but was still in use for phpMyAdmin.

If you find this work useful, or have a pull request to contribute, please find us on Github.