Twig扩展库中的i18n国际化扩展详解

Twig扩展库中的i18n国际化扩展详解

Twig-extensions 项目地址: https://gitcode.com/gh_mirrors/twi/Twig-extensions

什么是Twig i18n扩展

Twig i18n扩展是为Twig模板引擎提供的国际化支持模块，它基于PHP的gettext功能实现，允许开发者在模板中直接处理多语言内容。这个扩展特别适合需要支持多种语言的Web应用程序开发。

安装与配置

基本安装

首先需要确保PHP环境中已启用gettext扩展，这是使用i18n扩展的前提条件。可以通过phpinfo()检查或询问服务器管理员确认。

扩展注册

在Twig环境中添加i18n扩展非常简单：

use Twig\Extensions\I18nExtension;
$twig->addExtension(new I18nExtension());

gettext配置

在使用国际化模板前，必须正确配置gettext环境：

// 设置语言为法语
putenv('LC_ALL=fr_FR');
setlocale(LC_ALL, 'fr_FR');

// 指定翻译文件位置
bindtextdomain('myAppPhp', 'includes/locale');
bind_textdomain_codeset('myAppPhp', 'UTF-8');

// 选择域名
textdomain('myAppPhp');

核心功能与使用

基本翻译

使用trans标签标记需要翻译的内容：

{% trans "Hello World!" %}

{% trans string_var %}

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

变量嵌入

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

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

注意：变量会被转换为gettext格式，{{ name }}会变成%name%，因此翻译文件中对应的msgid应为Hello %name%!。

变量处理

如果需要先对变量进行处理，可以先赋值：

{% set name = name|capitalize %}
{% trans %}
    Hello {{ name }}!
{% endtrans %}

安全注意事项

嵌入的变量不会自动转义，必须手动处理：

{% set safe_var = unsafe_var|e %}
{% trans %}
    Escaped: {{ safe_var }}
{% endtrans %}

高级功能

复数处理

使用plural标签处理复数形式：

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

count变量会自动包含计数值(这里是apple_count的值)。

翻译注释

为翻译人员添加说明：

{% trans %}
    Hey {{ name }}, I have one apple.
{% plural apple_count %}
    Hey {{ name }}, I have {{ count }} apples.
{% notes %}
    用户菜单显示，长度应小于30字符
{% endtrans %}

翻译过滤器

在表达式或标签中使用trans过滤器：

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

翻译字符串提取

使用Poedit 2

Poedit 2专业版原生支持从Twig文件中提取字符串，无需额外配置。

使用xgettext或Poedit 1

对于不支持Twig的工具，可以通过以下步骤提取：

1. 创建脚本预编译所有模板
2. 从缓存目录提取翻译字符串

示例提取命令：

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

最佳实践

1. 统一编码：始终使用UTF-8编码处理翻译文件
2. 变量命名：使用有意义的变量名，方便翻译人员理解上下文
3. 注释清晰：为复杂字符串提供充分的翻译说明
4. 安全第一：始终对用户提供的变量进行转义处理
5. 测试覆盖：为各种语言环境编写测试用例

通过合理使用Twig i18n扩展，开发者可以轻松构建支持多语言的Web应用，同时保持模板的清晰和可维护性。

Twig-extensions 项目地址: https://gitcode.com/gh_mirrors/twi/Twig-extensions