Symfony Twig 模板中带变量翻译的正确姿势与常见陷阱
Symfony 翻译机制概述
symfony 框架提供了强大的国际化（i18n）和本地化（l10n）支持，允许开发者轻松地将应用程序翻译成多种语言。其核心是 translation 组件，它与 twig 模板引擎紧密集成，通过 trans 标签和 trans 过滤器提供翻译功能。在处理包含变量的动态文本时，symfony 通常依赖于 icu 消息格式（icu messageformat），这是一种功能丰富的文本格式化标准，支持占位符、复数规则、选择规则等高级功能。
在 Twig 模板中，我们通常会这样使用带变量的翻译：
{# 使用 trans 标签 #}
{% trans with {'%name%': 'Hans'} %}Hello %name%{% endtrans %}
{# 使用 trans 过滤器 #}
{{ 'Hello filter %name%'|trans({'%name%': 'Hans'}) }}以上代码在未经翻译文件处理时，能够正确输出：
Hello Hans Hello filter Hans
问题现象：变量替换失效
当开发者使用 Symfony CLI 的 translation:update 命令来提取和更新翻译文件时，可能会遇到一个常见的问题。例如，执行以下命令：
php bin/console translation:update --force en
该命令会扫描项目中的翻译键，并将其添加到指定的翻译文件中。如果你的翻译格式配置为 XLIFF（通常是默认或推荐格式），它会生成一个类似 messages.en.xlf 的文件。
初始生成的 XLIFF 文件可能看起来像这样：
<?xml version="1.0" encoding="utf-8"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2">
<file source-language="en" target-language="en" datatype="plaintext" original="file.ext">
<header>
<tool tool-id="symfony" tool-name="Symfony"/>
</header>
<body>
<trans-unit id="SzX5ua9" resname="Hello %name%">
<source>Hello %name%</source>
<target>__Hello %name%</target> {# 这里的 __Hello %name% 是由 update 命令自动添加的前缀，用于标识未翻译的文本 #}
</trans-unit>
<trans-unit id="6l2Ebbm" resname="Hello filter %name%">
<source>Hello filter %name%</source>
<target>__Hello filter %name%</target>
</trans-unit>
</body>
</file>
</xliff>此时，当你刷新页面时，会发现变量 %name% 不再被替换，输出结果变成了：
__Hello %name% __Hello filter %name%
这表明翻译系统识别了翻译键，但未能正确处理其中的变量占位符。
原因分析：ICU 消息格式与占位符规范
问题的根源在于 ICU 消息格式对占位符的严格要求。尽管在 Twig 模板中，我们习惯于使用 %name% 这样的占位符，但在翻译文件（特别是 XLIFF、YAML 或 PHP 格式）的目标文本（zuojiankuohaophpcntarget> 标签或值）中，ICU 消息格式期望的占位符形式是 {name}。
当 translation:update 命令生成或更新 XLIFF 文件时，它会从 Twig 模板的 source 文本中提取 %name%，并将其原样放置到 <source> 和 <target> 标签中（如果目标文本为空，它会复制源文本并添加前缀）。然而，翻译组件在解析 <target> 标签的内容时，会尝试将其作为 ICU 消息格式的字符串进行处理。如果它发现 %name% 而非 {name}，它就不会将其识别为可替换的变量，而是将其视为普通文本。
解决方案：修正翻译文件中的占位符
要解决这个问题，你需要手动编辑翻译文件，将 <target> 标签中的占位符从 %name% 修改为 {name}。
以之前的 XLIFF 文件为例，正确的修改方式如下：
<?xml version="1.0" encoding="utf-8"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2">
<file source-language="en" target-language="en" datatype="plaintext" original="file.ext">
<header>
<tool tool-id="symfony" tool-name="Symfony"/>
</header>
<body>
<trans-unit id="SzX5ua9" resname="Hello %name%">
<source>Hello %name%</source>
<target>__Hello {name}</target> {# 将 %name% 改为 {name} #}
</trans-unit>
<trans-unit id="6l2Ebbm" resname="Hello filter %name%">
<source>Hello filter %name%</source>
<target>__Hello filter {name}</target> {# 将 %name% 改为 {name} #}
</trans-unit>
</body>
</file>
</xliff>保存修改后的翻译文件后，再次刷新页面，你会发现变量 %name% 现在能够被正确替换，输出结果恢复正常：
__Hello Hans __Hello filter Hans
请注意，__ 前缀是 translation:update 命令在目标语言与源语言相同时，为了标识未翻译或需要验证的文本而自动添加的。在实际的国际化工作中，你需要将 __Hello {name} 替换为实际的目标语言翻译，例如：
<target>你好 {name}</target> {# 假设目标语言是中文 #}最佳实践与注意事项
- 统一占位符格式: 始终记住，在翻译文件的目标文本中，使用 {placeholderName} 格式来定义变量占位符，这是 ICU 消息格式的标准。
- translation:update 的行为: translation:update 命令的主要作用是提取翻译键并初始化翻译文件。它不会自动将 Twig 模板中的 %name% 转换为 XLIFF 目标文本中的 {name}。因此，在每次更新翻译文件后，如果涉及到带变量的翻译，你需要手动检查并修正占位符格式。
-
翻译文件格式: 无论你使用 XLIFF、YAML 还是 PHP 作为翻译文件格式，这个规则都适用。例如，在 YAML 文件中，你也会写成 Hello {name}。
# messages.en.yaml Hello %name%: 'Hello {name}' Hello filter %name%: 'Hello filter {name}'登录后复制 - 清晰的变量命名: 在 Twig 模板和翻译文件中使用清晰、一致的变量名，以便于理解和维护。
- 持续集成/部署中的翻译: 在 CI/CD 流程中，确保翻译文件的更新和验证是自动化的一部分。可以考虑编写脚本来自动检查或修正占位符格式，尽管手动审核翻译内容仍然是必要的。
- 测试翻译: 在开发和部署过程中，务必测试不同语言下的翻译功能，特别是带变量的翻译，以确保所有内容都正确显示。
总结
在 Symfony 应用中处理带变量的 Twig 模板翻译时，理解 ICU 消息格式对占位符的要求至关重要。虽然 Twig 模板中可以使用 %name% 这样的占位符，但在 XLIFF、YAML 等翻译文件的目标文本中，必须使用 {name} 格式才能确保变量能够被正确替换。通过手动修正翻译文件中的占位符，可以有效解决 translation:update 命令后变量替换失效的问题，从而实现完善的国际化支持。
以上就是Symfony Twig 模板中带变量翻译的正确姿势与常见陷阱的详细内容，更多请关注php中文网其它相关文章！
每个人都需要一台速度更快、更稳定的 PC。随着时间的推移，垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是，许多工具可以让 Windows 保持平稳运行。
445
收藏
