Symfony Twig 翻译中变量占位符的正确处理方法

理解 Symfony 翻译中的变量占位符

symfony 的翻译组件提供了一种强大的方式来国际化应用程序。在 twig 模板中，我们经常需要将动态内容（如用户名、数量等）嵌入到翻译字符串中。通常，这通过两种主要方式实现：{% trans %} 块和 trans 过滤器。

以下是一个典型的 Twig 模板示例，展示了如何在翻译中使用变量占位符：

{# 使用 {% trans %} 块 #}
{% trans with {'%name%': 'Hans'} %}Hello %name%{% endtrans %}

{# 使用 trans 过滤器 #}
{{ 'Hello filter %name%'|trans({'%name%': 'Hans'}) }}

在初始阶段，当没有对应的翻译文件时，Symfony 会直接使用源字符串并替换占位符，因此上述代码将按预期输出：

Hello Hans
Hello filter Hans

这表明 Symfony 能够识别 %name% 这样的占位符，并将其替换为 with 或 trans 过滤器参数中提供的值。

占位符失效的场景与原因

当应用程序的翻译内容需要更新或提取时，我们通常会运行 Symfony 提供的命令行工具：

php bin/console translation:update --force en

此命令会扫描代码中的翻译键，并将其写入指定的翻译文件（例如，XLIFF、YAML 或 PO 格式）。例如，对于上述 Twig 模板，它可能会生成一个 XLIFF 文件（messages.en.xlf），其内容大致如下：

  
    

      
    
    
      
        Hello %name%
        __Hello %name% {# 默认或自动生成的翻译目标 #}
      
      
        Hello filter %name%
        __Hello filter %name% {# 默认或自动生成的翻译目标 #}
      
    
  

请注意 标签中的内容。translation:update 命令通常会为 生成一个带有前缀（如 __）的源字符串副本，以指示这些是需要人工翻译的。

然而，当刷新网站时，我们可能会观察到变量不再被替换，而是直接显示为占位符：

Nimo.space

智能画布式AI工作台

下载

__Hello %name%
__Hello filter %name%

出现这个问题的原因在于，Symfony 在处理翻译文件中的字符串时，尤其是在使用 ICU 消息格式（International Components for Unicode）作为其翻译后端时，对占位符的语法有特定的要求。虽然 Twig 模板中 %name% 这样的占位符在传递给翻译组件时会被识别，但一旦进入翻译文件（如 XLIFF），如果 target 字符串本身包含 %name%，并且 Symfony 的翻译器期望 ICU 格式，那么它将不再将其视为可替换的变量。ICU 消息格式使用 {variableName} 这种花括号语法来定义占位符。

解决方案：采用 ICU 消息格式占位符

要解决这个问题，我们需要在翻译文件（如 XLIFF）的 标签中，将占位符从 %name% 修改为 ICU 消息格式所要求的 {name}。

根据 Symfony 官方文档关于消息占位符的说明，当使用 ICU 消息格式时，翻译文件中的占位符应使用花括号 {} 包裹。

因此，我们需要手动编辑生成的 XLIFF 文件，将 标签中的占位符进行修正：

  
    

      
    
    
      
        Hello %name%
        __Hello {name} {# 修正后的占位符 #}
      
      
        Hello filter %name%
        __Hello filter {name} {# 修正后的占位符 #}
      
    
  

重要提示：

• 即使 Twig 模板中仍然使用 %name%，只要传递给 trans 函数或过滤器的数据键是 name (不带百分号)，Symfony 翻译器在处理翻译文件中的 ICU 格式占位符 {name} 时，就能正确匹配并替换。
• 通常，translation:update 命令不会自动将 %name% 转换为 {name}。这需要开发者在翻译完成后，手动检查并修正翻译文件中的占位符。

实际操作与注意事项

1. 手动编辑翻译文件: 在运行 translation:update 命令生成或更新翻译文件后，务必检查并手动修改 target 标签中的占位符，使其符合 ICU 消息格式 {variableName}。
2. 清理缓存: 修改翻译文件后，为了确保 Symfony 能够加载最新的翻译内容，请务必清除缓存：

   php bin/console cache:clear

3. 理解翻译格式配置: Symfony 默认使用 XLIFF 格式，并且其翻译组件支持 ICU 消息格式。如果你在 config/packages/framework.yaml 中对 translator 部分有自定义配置，例如 default_format，请确保你理解其对占位符解析的影响。
4. 一致性: 在整个项目中，保持占位符命名的一致性至关重要。例如，如果在 Twig 中使用 with {'%user%': 'John'}，那么在翻译文件中对应的占位符应为 {user}。

总结

在 Symfony 应用中处理 Twig 模板的翻译与变量占位符时，一个常见的陷阱是翻译文件（特别是 XLIFF）中的占位符语法与 Symfony 翻译器所期望的 ICU 消息格式不匹配。虽然 Twig 模板能够识别 %name% 形式的占位符，但在翻译文件中，为了确保变量能够被正确替换，必须使用 ICU 格式的 {variableName} 占位符。通过手动修正翻译文件中的 标签，将 %name% 替换为 {name}，并清除缓存，即可解决变量占位符失效的问题，实现流畅且专业的国际化体验。