Flutter集成Easy Localization报Localization key not found如何解决

数据老陈

2026-8-28

问题根因

出现[Easy Localization] [WARNING] Localization key not found警告，本质是插件无法读取到对应key的翻译内容，结合你贴的代码，问题出在以下几点：

翻译文件不匹配：你配置了en_US、it_IT、fr_FR三个支持语言，但仅提供了一份法语内容的JSON。assets/translations目录下必须存在和语言码严格对应的三个文件：en-US.json、it-IT.json、fr-FR.json，文件名和代码中Locale传入的语言、地区码必须完全一致，缺文件、文件名写错都会导致对应语言加载失败。
CodegenLoader配置无效：你手动指定了assetLoader: CodegenLoader()，这个加载器不会直接读取assets目录下的JSON文件，只会读取通过生成命令输出的Dart格式翻译代码。如果你没执行过代码生成、没加对应的生成依赖、没导入生成的文件，加载器根本拿不到任何翻译内容，无论JSON写的是否正确都会报key找不到。
资产未注册：如果你本来不想用CodegenLoader只是误写了这个参数，那你大概率没在pubspec.yaml里注册翻译目录，默认的资源加载器根本访问不到你写的JSON文件。
初始化逻辑未执行：你把所有初始化逻辑放在了一个自定义的function异步函数里，如果没有在App启动入口的main()函数里调用这个方法，插件全程不会完成初始化，自然无法加载翻译。

修复步骤

按顺序排查操作即可解决：

选定加载模式并完成对应配置
- 选默认JSON资产加载（配置简单，适合小项目）：直接删掉assetLoader: CodegenLoader()这行，打开pubspec.yaml在flutter -> assets节点下注册翻译目录：
```
flutter:
  assets:
    - assets/translations/
```
- 选CodegenLoader加载（性能更好，key有代码提示，适合中大型项目）：先在dev_dependencies下添加easy_localization_generator、build_runner依赖，然后在项目根目录执行两条生成命令：
```
flutter pub run easy_localization:generate -S assets/translations -O lib/gen
flutter pub run easy_localization:generate -S assets/translations -O lib/gen -f keys -o locale_keys.g.dart
```
  命令执行完成后确认lib/gen目录下生成了codegen_loader.g.dart和locale_keys.g.dart两个文件，在main.dart中导入codegen_loader.g.dart，否则CodegenLoader类会找不到定义。
补全所有翻译文件
在assets/translations目录下新建三个和语言码严格匹配的JSON文件，每个文件都要包含你用到的所有翻译key：
- en-US.json 存英文翻译
- fr-FR.json 存你贴的法语翻译内容
- it-IT.json 存意大利语翻译
  三个文件的key必须完全一致，如果某个语言缺key，插件回退到备用语言en-US时如果也找不到对应key，就会触发警告。写完JSON可以用格式化工具校验下语法，避免尾逗号、引号不配对这类格式错误导致文件解析失败。

修正启动入口逻辑
把你写的自定义初始化函数改成标准的main启动函数，确保App启动时第一时间执行插件初始化：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await EasyLocalization.ensureInitialized();
  runApp(
    EasyLocalization(
      supportedLocales: const [Locale('en', 'US'), Locale('it', 'IT'), Locale('fr', 'FR')],
      path: 'assets/translations',
      fallbackLocale: const Locale('en', 'US'),
      // 用默认加载就删掉下面这行，用CodegenLoader就保留
      assetLoader: CodegenLoader(),
      child: const MyLangApp(),
    ),
  );
}

清理冗余代码
你在LanguageScreen里写的'choose_a_language'.tr().toString()属于冗余写法，tr()本身就返回String类型，直接写'choose_a_language'.tr()即可，不会影响功能但没必要。
清除缓存重新运行
所有配置改完后执行flutter clean清除旧构建缓存，再重新运行App即可。

快速排查技巧：如果切换语言后打印context.locale能看到语言码已经正确切换，但还是报key找不到，100%是对应语言的JSON文件里缺这个key，或者JSON语法错误导致文件解析失败。

内容的提问来源于stack exchange，提问作者Giovanni