Symfony 7 默认不加载自定义 Loader，因其 translator 服务仅注册内置加载器，自定义类需显式打标签 translation.loader 并实现 Symfony\Contracts\Translation\LoaderInterface，且 load() 必须返回 Catalogue 实例。
为什么 Symfony 7 默认不加载自定义 Loader？
Symfony 7 的 translator 服务默认只注册了内置加载器（如 XliffFileLoader、YamlFileLoader），任何自定义 Loader 都不会自动被识别——哪怕你把它放进 src/Translation/ 目录并实现了 LoaderInterface。它只是个普通类，没注册就等于不存在。
常见错误现象：Call to undefined method Symfony\Component\Translation\Loader\MyCustomLoader::load() 或更隐蔽的 Unable to load resource "messages.custom.php"，其实根本不是文件路径问题，而是 loader 根本没注册进 translator。
- 必须通过服务标签
translation.loader显式声明 - 标签需带
alias属性，这个 alias 就是addLoader('alias', new MyCustomLoader())中用的键名 - loader 类必须实现
Symfony\Contracts\Translation\LoaderInterface（不是旧版的LoaderInterface）
如何正确注册一个 CSV 加载器（以 CsvFileLoader 为例）
假设你要支持 messages.fr.csv 这类文件，且想用 csv 作为 loader alias。别直接复制旧文档里的 Loader/CsvFileLoader.php —— Symfony 7 要求严格类型和接口契约。
先写 loader 类：
namespace App\Translation;
<p>use Symfony\Contracts\Translation\LoaderInterface;
use Symfony\Component\Translation\Exception\InvalidResourceException;
use Symfony\Component\Translation\Loader\ArrayLoader;</p><p>class CsvFileLoader implements LoaderInterface
{
public function load(string $resource, string $locale, string $domain = 'messages'): \Symfony\Component\Translation\Catalogue
{
if (!is_file($resource)) {
throw new InvalidResourceException(sprintf('The file "%s" does not exist.', $resource));
}</p><pre class="brush:php;toolbar:false;"> $rows = array_map('str_getcsv', file($resource, FILE_IGNORE_NEW_LINES));
$messages = [];
foreach ($rows as $row) {
if (2 === count($row)) {
[$key, $value] = $row;
$messages[trim($key)] = trim($value);
}
}
return (new ArrayLoader())->load($messages, $locale, $domain);
}}
再在 config/services.yaml 中注册并打标签：
services:
App\Translation\CsvFileLoader:
tags:
- { name: 'translation.loader', alias: 'csv' }最后，在 config/packages/translation.yaml 中启用该格式路径（可选，但推荐）：
framework:
translator:
paths:
- '%kernel.project_dir%/translations'此时，messages.fr.csv 放进 translations/ 目录就能被自动发现并加载——前提是文件名符合 domain.locale.loader 规则（例如 messages.fr.csv → domain=messages, locale=fr, loader=csv）。
自定义 Loader 里最容易忽略的兼容性细节
Symfony 7 的 LoaderInterface::load() 方法签名强制要求返回 Catalogue 实例，不能返回数组或原始内容。很多老教程直接 return $messages，这会导致运行时类型错误。
- 务必用
ArrayLoader包装原始数据后再返回Catalogue，如示例中所示 -
$domain参数必须透传给底层 loader，否则翻译会绑定到错误 domain（比如你扩展的是admindomain，但没传过去，结果全进了messages） - 抛异常要用
Symfony\Component\Translation\Exception\*下的具体类，不要用RuntimeException—— 否则 translator 无法区分是资源错误还是逻辑错误 - 如果 loader 需要依赖其他服务（如缓存、数据库连接），记得在构造函数中声明，并确保服务已正确定义
调试 loader 是否生效的三个快速检查点
当你改完代码却看不到效果，按顺序查这三项，90% 的问题当场定位：
- 运行
bin/console debug:container --tag=translation.loader，确认你的类出现在列表里，且alias值与你期望一致 - 检查
translations/messages.fr.csv文件权限是否可读，Windows 用户特别注意换行符是否为\n（不是\r\n），否则str_getcsv()可能解析失败 - 清空缓存：
bin/console cache:clear—— Symfony 7 的 translation 缓存是强绑定 loader 注册状态的，缓存不清理，新 loader 永远不会被调用
loader 的逻辑本身可以很简单，但注册链路和类型契约必须严丝合缝；漏掉任何一个环节，它就只是个躺在代码里的“死类”。
