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

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

composer require phpmyadmin/twig-i18n-extension

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');

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

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

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

If you use the Twig I18n extension, you will probably need to extract the template strings at some point.

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

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->load(str_replace($tplDir . '/', '', $file->getRealPath())); } }

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.

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.