README

i18n 扩展向 Twig 添加了 gettext 支持。它定义了一个标签，trans。

代码状态

安装

可以通过在命令行中运行以下命令通过 Composer 安装此库

composer require phpmyadmin/twig-i18n-extension

配置

在开始使用 trans 块之前，您需要注册此扩展

use PhpMyAdmin\Twig\Extensions\I18nExtension;

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

注意：在渲染任何国际化模板之前，您必须配置 gettext 扩展。以下是一个简单的 PHP 文档 中的配置示例

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

注意！

i18n 扩展仅在 PHP gettext 扩展被启用时才能工作。

使用方法

使用 trans 块来标记模板中的可翻译部分

{% trans "Hello World!" %}

{% trans string_var %}

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

在可翻译字符串中，您可以嵌入变量

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

在 gettext 查找过程中，这些占位符将被转换。 {{ name }} 变为 %name%，因此此字符串的 gettext msgid 将是 Hello %name%!。

注意

{% trans "Hello {{ name }}!" %} 不是一个有效的语句。

如果您需要应用过滤器到变量，您首先需要将结果分配给一个变量

{% set name = name|capitalize %}

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

要使可翻译字符串复数化，请使用 plural 块

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

plural 标签应提供用于选择正确字符串的 count。在可翻译字符串中，特殊的 count 变量始终包含计数值（此处为 apple_count 的值）。

要为翻译者添加注释，请使用 notes 块

{% 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 %}

您可以使用或不需要 plural 来使用 notes。一旦您的模板编译完成，您应该配置 gettext 解析器以获得类似以下内容：xgettext --add-comments=notes

在表达式或标签中，您可以使用 trans 过滤器来翻译简单的字符串或变量

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

表达式或标签中的复杂翻译

可以使用 trans 标签和 trans 过滤器来进行翻译。过滤器的功能较弱，因为它只能用于简单的变量或字符串。对于更复杂的情况，如复数化，您可以使用两步策略

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

提取模板字符串

如果您使用 Twig I18n 扩展，您可能需要在某个时候提取模板字符串。

使用 Poedit 2

Poedit 2 原生支持从 Twig 文件中提取，无需额外设置（Pro 版本）。

使用 xgettext 或 Poedit 1

不幸的是，xgettext 工具不能原生理解 Twig 模板，基于它的工具（如 Poedit 的免费版本）也不能。但有一个简单的解决方案：因为 Twig 将模板转换为 PHP 文件，所以您可以在模板缓存上使用 xgettext。

创建一个脚本，强制为所有模板生成缓存。以下是一个简单的示例来帮助您入门

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

使用标准 xgettext 工具，就像您使用纯 PHP 代码一样

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

另一个解决方案是使用 Twig Gettext Extractor 并直接从 Poedit 提取模板字符串。

历史

该项目于2019年由phpMyAdmin团队分叉，因为虽然它已被 Twig 项目 放弃，但仍然在phpMyAdmin中使用。

如果您觉得这项工作很有用，或者有pull request想要贡献，请在我们 Github 上找到我们。