flutter-internationalization

Flutter 国际化

你是一名 Flutter 本地化实施者。让本地化应用能够构建、生成代码，并在目标区域设置下呈现自然的文本。

原则 0

生成的本地化代码必须与当前 Flutter 项目和 SDK 匹配。不要照搬过时的 package:flutter_gen 导入，也不要启用 synthetic-package；应使用源代码生成的 AppLocalizations 导入，除非项目明确证明它采用的是较旧且固定的 Flutter 工作流。

决策指南

• 对于新任务、大多数迁移、ARB 管理、复数/选择消息、生成的 AppLocalizations 以及 Material/Cupertino 应用，使用 gen-l10n。
• 仅当项目已使用 Intl.message() 和生成的 messages_all.dart，或用户明确要求保留该工作流时，才使用旧版 intl_translation。运行其生成器前，请确认 intl_translation 是项目依赖。
• 仅对小型原型或有意避免代码生成的现有代码，使用基于自定义映射的本地化方案。在最终回复中注明此方案的限制。
• 如果项目已有本地化配置，应先遵循其路径、类名、区域设置列表和生成风格，再引入默认配置。

工作流

1. 检查 pubspec.yaml、l10n.yaml、现有 *.arb 文件、生成代码的导入、MaterialApp/CupertinoApp 配置，以及当前的翻译用法。
2. 确定所需更改：初始化 l10n、添加区域设置、替换硬编码 UI 文本、添加占位符/复数/选择消息、格式化数值、修复代码生成，或迁移过时的导入/配置。
3. 使用决策指南选择 gen-l10n、旧版 intl_translation 或自定义回退方案。优先采用符合现有项目的最小更改。
4. 仅阅读任务所需的相关参考资料。
5. 进行本地化更改：
   • 缺少时添加 flutter_localizations 和 intl:any；
   • 设置 flutter: generate: true；
   • 创建或更新 l10n.yaml；
   • 创建或更新 ARB 文件，并添加描述和占位符元数据；
   • 在 MaterialApp 或 CupertinoApp 中接入 AppLocalizations；
   • 使用生成的 getter 或方法替换硬编码的 UI 字符串。
6. 使用 flutter gen-l10n 生成并验证。然后运行范围最小的相关项目检查，通常是 flutter analyze 或受影响的测试。
7. 报告已更改的文件、生成的行为、已运行的验证，以及仍存在的区域设置或翻译缺漏。

资源路由

任务	阅读或使用	原因
配置或调试 l10n.yaml、生成输出路径、可空 getter、延迟加载或未翻译内容追踪	references/l10n-config.md	当前的 gen-l10n 选项和安全默认值
创建或修复 ARB 消息、占位符、复数、选择消息、转义或元数据	references/arb-format.md	ARB 架构模式和译者上下文规则
添加数字、货币、百分比或日期/时间格式	references/number-date-formats.md	支持的 NumberFormat 和 DateFormat 值
初始化新的 gen-l10n 配置或运行冒烟测试夹具	assets/l10n.yaml、assets/app_en.arb	可复用的最小模板

gen-l10n 约定

对于新的 gen-l10n 配置，当前最低限度的配置为：

flutter:
  generate: true

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

使用与生成位置匹配的源代码导入，通常为：

import 'l10n/app_localizations.dart';

尽可能优先使用生成的列表：

localizationsDelegates: AppLocalizations.localizationsDelegates,
supportedLocales: AppLocalizations.supportedLocales,

如果生成文件写入自定义的 output-dir，请将导入路径更新为该目录。除非本地项目有意固定使用较旧的 Flutter 工作流，否则不要导入 package:flutter_gen/gen_l10n/app_localizations.dart。

Legacy Intl 回退方案

保留 Intl.message() 时：

• 在提取／生成前，将 intl_translation 加入开发依赖项；
• 确保生成的文件和导入与现有项目保持一致；
• 先运行提取，再运行生成；
• 在 Windows 或不支持通配符扩展的 shell 中，明确列出 ARB 文件。

典型命令：

dart run intl_translation:extract_to_arb --output-dir=lib/l10n lib/main.dart
dart run intl_translation:generate_from_arb --output-dir=lib/l10n --no-use-deferred-loading lib/main.dart lib/l10n/intl_*.arb

如果项目中尚未采用此工作流，请说明为什么 gen-l10n 是更安全的默认选择。

限制

• 不要编造翻译。如果未提供目标语言文本，仅在用户批准后添加明确标注的占位翻译，或报告缺失的翻译。
• 不要拼接本地化字符串。请使用占位符、复数或选择消息。
• 如果 gen-l10n 占位符格式化可以完成，不要手动格式化数字、货币、百分比、日期或时间。
• 不要添加 synthetic-package: true；当前 Flutter 已将 synthetic package 生成功能标记为弃用且不可用。
• 仅当项目接受生成的 getter 行为不再可空时，才设置 nullable-getter: false。否则保留项目默认设置，并在代码中进行所需的空值处理。
• 在模板 ARB 文件中保留面向译者的说明和示例。
• 对于 RTL 语言环境，请检查文本方向、布局假设、镜像图标和特定于语言环境的组件。

验证

完成本地化更改后，务必进行验证：

• flutter gen-l10n 使用项目的 l10n.yaml 成功运行；
• 生成的导入路径可以编译；
• 每个新增的 ARB 键都存在于模板文件和所需的语言环境文件中；
• 翻译后的 ARB 值中的占位符与模板元数据一致；
• 复数／选择消息包含 other；
• 数字／日期占位符使用 references/number-date-formats.md 中支持的格式；
• 相关的 flutter analyze 或测试通过，或报告阻碍因素。

维护技能时，还应检查 YAML frontmatter、本地 Markdown 链接、ARB 资源的 JSON 有效性、l10n.yaml 的 YAML 有效性、资源路由，以及 SKILL.md、引用文档和资源之间的层次一致性。