TYPO3 v12.xlf文件本地化失效问题排查求助

数据老陈

2026-8-1

TYPO3 12.1.3 多语言翻译（XLF文件）不生效排查方案

检查XLF文件命名与路径
确保de.locallang.xlf和主文件locallang.xlf存放在站点包的Resources/Private/Language/目录下，命名严格遵循[语言代码].locallang.xlf格式（比如德语用de，不要写成de_DE）。同时确认主文件locallang.xlf的<source>是英文默认文本，de.locallang.xlf的<target>对应德语翻译内容。
验证<f:translate>标签参数
调用翻译时必须指定正确的extensionName（即你的站点包扩展名，比如my_sitepackage），否则TYPO3可能会去核心或其他扩展中查找翻译，导致无法匹配你的站点包XLF文件。示例代码：
```
<f:translate key="welcome" extensionName="my_sitepackage" />
```
确认站点语言配置的代码一致性
在站点管理（Site Management）中，德语语言的「ISO code」必须设置为de，与XLF文件的前缀完全一致。如果站点配置的是de-DE而文件是de.locallang.xlf，TYPO3将无法找到对应的翻译文件。
清除系统缓存
TYPO3会缓存翻译内容，修改XLF文件或语言配置后，必须清除全部缓存（包括翻译缓存）。可以通过后端的「Flush System Cache」按钮操作，或使用命令行：
```
typo3 cache:flush
```

检查XLF文件的XML结构
确保XLF文件遵循XLIFF 1.2规范，根元素命名空间正确，每个trans-unit的id与模板中key完全匹配，无拼写错误。示例结构：

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
  <file source-language="en" target-language="de" datatype="plaintext" original="messages">
    <body>
      <trans-unit id="welcome">
        <source>Welcome</source>
        <target>Willkommen</target>
      </trans-unit>
    </body>
  </file>
</xliff>

检查Composer配置（若使用Composer安装）
若站点包通过Composer安装，确认composer.json中的extra.typo3/cms配置正确，确保语言文件被TYPO3识别：
```
"extra": {
  "typo3/cms": {
    "extension-key": "my_sitepackage",
    "web-dir": "public"
  }
}
```