语言切换按钮点下去，首页的标题变了，商品详情页还是中文，底部导航栏一半中文一半英文——这种“改一半”的场面，做过出海项目的人应该都不陌生。第一次遇到时我以为是热重载没生效，重启一遍照样如此，最后才发现是自己把翻译文本缓存在了initState里。这类问题在 Flutter 多语言（国际化）里特别典型：框架本身不难，难的是你选择哪套资源管理方式，以及切换语言时它到底刷新了哪一层。
这篇聊的是 Flutter 多语言的第二套方案：用 GetX 的Translations托管翻译表。它不依赖代码生成，写完一个 Dart 的 Map 就能跑，语言切换走Get.updateLocale，改完文件热重载立刻生效，产品经理和翻译同学甚至可以直接编辑 Dart 文件。相比 intl 那套 arb 加代码生成的流程，它轻得多。但它也有明显的短板——没有类型安全、没有 ICU 复数规则、日期数字格式还得靠别人。所以这篇不会只说“怎么用”，更多是讲“什么时候用它、它会在哪里坑你、坑了之后怎么查”。无论你是刚接触 Flutter 国际化的新手，还是已经在项目里跑了一年多语言、想换一套更轻的方案的老手，下面这些内容应该都能直接拿去用。
1. 为什么在第二个方案里把翻译表交给 GetX 托管
1.1 第一套 intl 方案真正的重心在哪
先得说清楚“方案一”长什么样，不然没法解释“方案二”省掉了什么。Flutter 生态里最正统的做法是 intl 加flutter_localizations：每种语言一个.arb文件，里面是 JSON 风格的键值对，然后通过flutter gen-l10n或者第三方工具生成一个AppLocalizations类，代码里通过AppLocalizations.of(context).homeTitle这种带类型的属性去取文案。
这套方案的核心优势是类型安全。你写错一个属性名，编译期直接报红，不用等到跑起来才发现。它还有一套完整的 ICU 消息语法，能处理复数（一匹马 vs 三匹马）、性别、以及各种语言的复杂语法变体。日期和数字格式化也是它自带的强项，DateFormat.yMd('zh')一句话就能按地区习惯输出。
但代价也很实在。每加一种语言，你得新增一个 arb 文件、跑一次生成命令、有时候还得重启 IDE 才能让新生成的类被索引到。热重载在这条链路上经常不灵，改一个标点符号都得重新编译。更麻烦的是，arb 文件对非开发人员不友好——它不是“打开就能改”的格式，还需要理解占位符的转义规则。当项目里要接入十几种语言、翻译同学有自己的节奏时，这套流程的摩擦成本会迅速放大。
1.2 GetX 方案真正省掉的是哪几段链路
GetX 的国际化把上面那几段全砍了。它只要求你写一个类继承Translations，实现一个 getter 返回Map<String, Map<String, String>>——外层 key 是语言标识，内层是“键到译文”的映射。然后在GetMaterialApp里挂上这个类，代码里用'home_title'.tr取值。没有生成步骤、没有外部文件格式、没有编译期等待，改完保存，热重载一按立刻看到效果。
省掉的具体是三段：第一段是资源到代码的生成，arb 编译成类这一步没了，Map 就是代码；第二段是语言注册的配置，arb 方案要维护supportedLocales和文件清单，GetX 方案里语言就是 Map 的一个 key，加一行就多一种语言；第三段是取值的上下文依赖，AppLocalizations.of(context)需要 BuildContext，而.tr是 String 的扩展方法，不依赖 context，在工具类、Controller、甚至纯 Dart 函数里都能直接调用。
最后这一点在 GetX 项目里价值很高。业务逻辑里经常需要拼一条提示语，比如“订单 {id} 已取消”，如果用 context 方案，你得把 context 一路传进 Controller，写起来很难受。用.tr就没这个问题，'order_cancelled'.trParams({'id': id})在任何地方都能写。这也是我后来在新项目里默认选 GetX 方案的主要原因——不是因为它“更好”，而是因为它跟响应式状态管理的思路一致，不让 UI 层的东西泄漏到逻辑层。
2. Translations 的键值结构：两层 Map 不是目录树
2.1 keys 的返回类型决定了你不能随便嵌套
先把最基础的结构写清楚。Translations抽象类要求实现的 getter 是Map<String, Map<String, String>>，只有两层，且内层的值必须是String。这个类型约束意味着你不能写成三层来模拟“模块分层”，比如{'zh_CN': {'home': {'title': '首页'}}}是过不了编译的。
很多从 JSON 本地化文件迁过来的人会在这一步卡住，因为 JSON 方案里层级嵌套是很常见的组织手段。GetX 的结构决定了你只能用扁平化加前缀的方式做分组：
final zhHome = <String, String>{ 'home_tab_index': '首页', 'home_tab_category': '分类', 'home_search_hint': '搜索商品', 'home_empty_tip': '暂无内容', };前缀home_承担了原本嵌套层级的作用，同时它还顺带解决了另一个问题：键的重名。两个模块都叫title的话，扁平结构下必然冲突，加了前缀之后天然隔离。这是我建议所有团队都强制执行的规则，后面 2.3 会细讲。
外层 key 的格式也需要留意。GetX 查找翻译时会先取Get.locale的languageCode_countryCode形式（比如zh_CN），找不到再退一步找纯languageCode（zh）。所以你外层可以写'zh_CN': {...}也可以写'zh': {...}，前者精确、后者兜底更广。我的习惯是主语言用带地区的完整标识，同时留一份不带地区的兜底，比如简体中文写zh_CN，繁体的台湾地区版本写zh_TW，再补一个zh指向简体，避免某些设备上报的语言标识不带地区时整站变成英文。这个细节在模拟器上测不出来，真机上却很容易中招。
2.2 按模块拆文件再合并的工程写法
翻译表全部塞进一个文件是最常见的做法，也是最容易烂掉的做法。项目跑到第三个月，那个文件轻松破两千行，所有人都在同一个文件里加键，Git 冲突天天有。正确的拆法是把每种语言拆成若干模块文件，再在Translations实现类里用扩展运算符合并。
先建语言目录结构，每种语言一个文件夹，里面按业务模块切分：
lib/i18n/ app_translations.dart zh/ common.dart home.dart order.dart en/ common.dart home.dart order.dart每个模块文件导出一个Map<String, String>常量，然后在app_translations.dart里做合并：
import 'zh/common.dart'; import 'zh/home.dart'; import 'zh/order.dart'; import 'en/common.dart' as en_common; final _zh = <String, String>{ ...zhCommon, ...zhHome, ...zhOrder, }; final _en = <String, String>{ ...enCommon, ...enHome, ...enOrder, }; class AppTranslations extends Translations { @override Map<String, Map<String, String>> get keys => { 'zh_CN': _zh, 'zh': _zh, 'en_US': _en, 'en': _en, }; }注意这里_zh和'zh'、'zh_CN'共用了同一个 Map 实例，不会复制数据，内存上没有额外开销。合并顺序决定了同名键谁覆盖谁，后面的覆盖前面的。我把common放最前面，业务模块放后面，这样模块里如果真的需要覆盖公共文案（比如订单模块里“确认”有特殊含义），有办法做到，但不会误伤。
拆文件带来一个额外好处：多人协作时冲突面积可控。做首页的人和做订单的人基本不会碰同一个文件，合并请求的冲突概率大幅下降。这一点在团队超过三个人之后感受特别明显。
2.3 键名命名规则与真实踩坑
键名这套东西看着是小事，实际上是多语言方案能不能长期维护的分水岭。我踩过几次坑之后，给自己定了三条硬规则，至今没破过。
第一条，前缀必须是模块名，不能是页面名。页面会重构，模块不会。曾经有个键叫detail_buy_now，后来详情页拆成了两个，这个键到底是哪个页面的？“加入购物车”和“立即购买”到底归哪个模块？最后没人敢动它，硬生生留了个僵尸键。改成order_buy_now就清楚了——它属于订单行为，不管页面上叫什么。
第二条，键名里不要包含具体文案的语义。反例是login_button_text_blue、home_title_welcome_back。文案是会改的，改完之后键名就跟内容对不上了，后来的人看到welcome_back会以为这是登录回来的提示，实际上它早就被改成了“你好”。键名应该表达位置和用途，不表达内容：login_submit、home_greeting。
第三条，带占位符的键，占位符名要和业务字段一致。比如订单号就用{orderId}，别用{0}或者{value}。因为后期如果要做键值对的自动校验脚本，占位符名对不上业务字段就没法做静态检查。这个规则一开始觉得无所谓，等到要做“翻译完整性检查”的时候就知道值了。
还有一个高频坑：键名大小写和分隔符不统一。有人写homeTitle，有人写home_title，有人写HomeTitle。这在 GetX 里不会报错——找不到就是找不到，直接返回键名字符串本身，界面上就会出现一坨homeTitle这样的英文，测出来才发现。所以团队里必须统一成下划线小写，并且在提交前做一次全量扫描。
3. 切换语言的完整链路：从点击到界面刷新
3.1 Get.updateLocale 背后发生了什么
切换语言这行代码只有一句Get.updateLocale(Locale('en', 'US'))，但它内部做的事比看起来多。GetX 会把新的 locale 写入全局状态，然后触发一次强制重建，最终会让挂载在GetMaterialApp下方的整棵 widget 树重新走一遍 build。也就是说，你不需要手动 setState，也不需要给每个页面套 Obx，只要.tr是写在 build 方法里的，它就会拿到新语言下的译文。
这里有个很多人误解的点：.tr不是响应式的数据源，它只是一次普通的同步查找。真正让它“跟着变”的是整树重建。所以如果你把.tr的结果存在变量里、存在 Controller 的属性里、或者放在initState里算好，重建时这些地方都不会重新执行，界面上就永远停在上一次的语言。这是“切换只变一半”最常见的根因，比任何框架 bug 都常见。
重建的粒度是整个 App，听起来像性能问题，实际不用太担心。这个动作是用户主动触发的低频操作，一次重建的开销在现代设备上完全可以忽略。而且路由栈不会丢，你正在浏览的页面还在，GetXController的实例也不会被销毁重建，只有 widget 层的 build 走一遍。但要注意：如果你在 Controller 的onInit里做过跟语言相关的事情，比如预加载某个语言的提示文案，它不会重跑。这类逻辑得改成在 build 里取，或者监听 locale 变化手动触发。
3.2 冷启动恢复上次选择的最小实现
用户上次选了英文，下次打开 App 又变回中文，这是体验上很致命的一个问题。解决办法很直接：切换的时候把语言标识写进本地存储，启动的时候读出来当作初始 locale。
main函数里在runApp之前拿到存储值，最简单的方式是用shared_preferences：
Future<void> main() async { WidgetsFlutterBinding.ensureInitialized(); final prefs = await SharedPreferences.getInstance(); final savedCode = prefs.getString('app_locale_code'); final initialLocale = switch (savedCode) { 'en' => const Locale('en', 'US'), 'zh' => const Locale('zh', 'CN'), _ => null, }; runApp(AppBootstrap(initialLocale: initialLocale)); }注意这里_分支返回null，而不是直接返回中文。返回null的意思是“交给系统决定”，GetX 会根据设备语言自动匹配，如果用户手机是英文系统，首启就是英文，这比强行锁死中文要合理得多。只有在设备语言完全不在支持列表里时，才会落到fallbackLocale。
然后在GetMaterialApp上把initialLocale传进locale参数。这里有个必须提醒的点：locale参数只在首帧起作用，后续切换不要再去改它。有些人为了“保险”，切换语言时既调Get.updateLocale又 setState 改locale参数，结果两套数据源打架，表现是切换后闪一下又弹回旧语言。统一走Get.updateLocale一条路就行。
写入侧配合一个工具方法，把“存”和“切”绑在一起，避免某处漏存：
Future<void> changeLocale(String code) async { final locale = code == 'en' ? const Locale('en', 'US') : const Locale('zh', 'CN'); final prefs = await SharedPreferences.getInstance(); await prefs.setString('app_locale_code', code); Get.updateLocale(locale); }顺序上我习惯先存再切。反过来的话，如果写存储时抛异常（比如权限问题），界面已经切过去了但没存下来，用户重启又回去了，更难查。
3.3 点了没反应或只变一半的排查顺序
这个排查表是我自己整理出来贴在项目 wiki 上的，按命中率从高到低排，遇到问题从上往下试，基本三步之内解决。
| 现象 | 最可能的原因 | 处理方式 |
|---|---|---|
| 全站完全不变 | .tr写在 build 之外，或被静态字段缓存 | 把取值挪回 build 方法内 |
| 部分页面不变 | 页面里用了const硬编码，或文案存进了 Controller | 删掉缓存，改成 build 内取值 |
| 只有系统组件是英文 | 缺GlobalMaterialLocalizations等 delegate | 补 delegates 和supportedLocales |
| 重启后回到原语言 | 没持久化，或首帧 locale 写死 | 补冷启动恢复逻辑 |
| 部分键显示成键名本身 | 该 key 在当前语言的 Map 里缺失 | 对齐各语言键集合 |
第一行“全站完全不变”还有一种隐蔽情况：Get.updateLocale被调用了，但传进去的Locale参数在keys里匹配不到。比如你传Locale('en')，而 Map 里只有'en_US'，GetX 会先找en，找不到再找en_US吗？实际查找顺序是从精确到宽泛，你传的 locale 越简略，能匹配到的候选就越少。所以传 locale 时最好跟 Map 里的 key 完全一致，我一般直接在切换方法里写死对应的Locale常量，不让它有机会猜。
第二行“部分页面不变”还有一种变体：页面用了AutomaticKeepAliveClientMixin或者放在PageView里，切语言时 widget 没有走 build。这种要么手动触发一次重建，要么把 keep alive 去掉。我当时排查了快两个小时才发现是 keep alive 的问题，因为日志里.tr明明被调用了，但调用的是旧实例的 build。
4. tr 全家桶：参数、复数与那些用不了的地方
4.1 占位符参数的正确姿势
带变量的文案是绕不开的，trParams就是干这个的。翻译表里用花括号写占位符：
final zhOrder = <String, String>{ 'order_cancelled_with_id': '订单 {orderId} 已取消', 'order_delivered_in_days': '预计 {days} 天后送达', 'welcome_user': '欢迎你，{name}', }; // 使用 'order_cancelled_with_id'.trParams({'orderId': 'A1024'});这里有几个容易翻车的细节。第一，占位符的替换是纯字符串匹配，不做转义。如果你的变量值里本身就带花括号，或者带$符号，替换之后可能出现意料之外的文本。用户昵称这类自由输入的内容直接拼进翻译里是有风险的，尤其是在一些会把用户输入当模板渲染的场景。稳妥做法是对用户输入做一次过滤，或者干脆不在翻译里拼用户内容，改用两段文本拼接。
第二，中英文的占位符位置可能不同，不要试图用字符串拼接解决语序问题。比如英文是“{days} days until delivery”，中文是“预计 {days} 天后送达”，变量在句子里的位置完全不一样。这就是为什么必须用占位符而不是'预计 ' + days + ' 天后送达'——拼接方案在英文语境下直接崩。
第三，占位符漏传不会报错。如果翻译表里写了{orderId}但调用时没传这个键，GetX 不会抛异常，界面上就会原样显示{orderId}这段文本。这个表现挺蠢的，但至少能肉眼发现。所以带占位符的文案一定要在真机上点一遍，别只测主流程。
4.2 trPlural 的适用范围到此为止
GetX 提供了trPlural，用法是在翻译表里准备单数和复数两个键，调用时传入数量：
final zhCart = <String, String>{ 'cart_item_count_1': '购物车里有 {count} 件商品', 'cart_item_count_2': '购物车里有 {count} 件商品', }; final enCart = <String, String>{ 'cart_item_count_1': '1 item in cart', 'cart_item_count_2': '{count} items in cart', }; 'cart_item_count'.trPlural('count', count, [count.toString()]);它解决的是最基础的“单数 vs 复数”二分。对英语、中文、日语这类语言够用——中文其实压根不需要复数变化，日语也是。但遇到有复杂复数规则的语言就不行了。有些语言有四种甚至六种复数形式（少量、一些、许多、其他），每种形式对应不同的数字区间和尾数判断，这套规则在 intl 的 ICU 语法里有完整支持，GetX 的二分实现完全覆盖不了。
我的处理方式是：如果产品确定只做中英日韩这类语言，trPlural可以放心用；如果后续可能接入多复数规则的语言，从一开始就别用它，改用 intl 的Intl.plural单独处理这一小部分文案。混用不可怕，可怕的是先用简单方案铺满全站、上线前才发现要重做。这个判断最好在立项时就跟产品对齐，别等到发版前一周才发现。
还有一个坑：trPlural的数量参数和占位符参数是分开传的，数量参数只用来判断走哪个键，不会自动替换进文本。上面例子里count既作为判断依据，又在参数列表里手工塞了一次，忘了塞就会出现“购物车里有 {count} 件商品”这种界面。这个设计挺反直觉的，第一次用基本都会漏。
4.3 把 tr 的结果存进变量是自找麻烦
这是我在项目里反复纠正队友的一个习惯。很多人为了“性能”，会在 build 里先把文案取出来存成局部变量，甚至提到类字段上：
// 反例：切语言不会更新 class _HomePageState extends State<HomePage> { final String title = 'home_title'.tr; @override Widget build(BuildContext context) { return Text(title); } }这段代码在首次渲染时是对的，切语言之后完全没反应，因为title在 State 创建时就定死了。更隐蔽的是放在initState里：
// 反例：同样不更新 late final String hint; @override void initState() { super.initState(); hint = 'home_search_hint'.tr; }这种写法在代码审查里特别容易被放过，因为看起来只是“提前算了一下”，逻辑上没问题。但只要涉及多语言，任何在 build 之外求值的.tr都是定时炸弹。我的建议很粗暴：在项目里全局搜索.tr，凡是出现在 build 方法体之外的，一律改掉，别管它当时看起来有没有问题。
真要说性能，.tr本身就是一次 Map 查找加一次字符串替换，开销小到可以忽略。为了省这点开销换来一个多语言失效的 bug，怎么算都不划算。如果某段文案确实计算成本高（比如需要格式化日期），缓存也应该缓存在跟 locale 绑定的地方，locale 变了就让缓存失效。
5. GetX 与 intl 不是二选一：混合使用的边界
5.1 哪些文案必须留在 localizationsDelegates 里
这里要先纠正一个常见误解：用了 GetX 的Translations，不代表可以把flutter_localizations整个删掉。框架自带的组件文案不归 GetX 管。
具体是哪些？文本输入框长按弹出的“剪切/复制/粘贴”菜单、日期选择器的月份名和星期名、返回按钮的无障碍朗读文本、showDatePicker里的“取消/确定”、iOS 上滑动返回的系统提示……这些全是 Flutter 框架内置的 Material 和 Cupertino 组件自己维护的文案，它们只认Localizations，不认.tr。
所以GetMaterialApp上必须保留这三个 delegate：
GetMaterialApp( translations: AppTranslations(), locale: initialLocale, fallbackLocale: const Locale('en', 'US'), localizationsDelegates: const [ GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate, GlobalCupertinoLocalizations.delegate, ], supportedLocales: const [ Locale('zh', 'CN'), Locale('en', 'US'), ], home: const HomePage(), );supportedLocales也要跟keys里的语言保持一致。如果漏了某个语言，那个语言下的系统组件文案会退回默认语言，表现就是“App 自己的文案是英文，但日期选择器还是中文”，非常割裂。这个问题的排查成本不低，因为大部分人只测自己写的页面，不会去点开日期选择器看。
5.2 两套资源的职责划分表
混合使用的关键是把边界划清楚，我的划分原则是“谁的组件谁负责”：
| 文案来源 | 归属 | 维护方式 |
|---|---|---|
| 业务页面、弹窗、Toast | GetXTranslations | 业务代码里维护，翻译同学可直接改 |
| 日期选择器、文本框菜单 | Flutter 内置 delegates | 框架自带，无需自己写 |
| 日期格式（如“2024年3月5日”） | intlDateFormat | 用 locale 参数控制 |
| 数字千分位、货币符号 | intlNumberFormat | 同上 |
| 复杂复数规则 | intlIntl.plural | 单独封装一层 |
日期格式化这块特别值得说一下。GetX 的Translations只负责静态文本，不负责格式化。你要输出“2024年3月5日”这种跟语言强相关的日期，必须用 intl：
final formatted = DateFormat.yMMMMd(Get.locale.toString()).format(date);这里有个坑：intl 的日期格式化需要先初始化对应语言的数据，否则某些语言下会抛异常或者退回英文格式。初始化放在main里：
await initializeDateFormatting('zh_CN', null); await initializeDateFormatting('en_US', null);不做这一步，英文环境可能正常（默认内置），中文环境可能报LocaleDataException。这个异常在 debug 模式下才明显，release 包有时会静默退回英文格式，线上才发现日期变成“March 5, 2024”，而周围的文案全是中文。
6. 上线前的收尾：缺失键、包体积与自查清单
6.1 在 debug 下拦截缺失的键
GetX 找不到 key 时的行为是原样返回 key 字符串。这个设计在开发期是有用的——你一眼就能看到某个地方没翻译。但在测试和线上，它就变成了一个“看起来像英文但其实不是”的文本，很容易被当成正常内容放过。
我的做法是加一个薄薄的包装，在 debug 模式下把缺失的键打出来：
extension TranslateSafe on String { String trSafe() { final result = tr; if (kDebugMode && result == this) { debugPrint('[i18n] missing key: $this'); } return result; } }这个包装有个已知的误报：如果某个键的译文恰好跟键名一模一样（比如键叫ok，英文译文也是ok），就会被误判成缺失。这种情况很少，可以接受。真遇到了就把这类键加进白名单。
更彻底的做法是在 CI 里跑一个脚本，把各语言的 Map 键集合取出来做差集，输出“中文有但英文没有”的键列表。这个脚本不难写，几十行 Dart 就行，但它能在提测前把大部分漏翻问题拦住。我上一个项目里，这个脚本第一次跑就输出了三十多个缺失键，全是开发过程中顺手加的文案没同步到另一种语言。人工点页面根本点不出来。
6.2 多语言包对包体和内存的真实影响
有人担心把所有语言的 Map 都打进包里会让体积膨胀。实测算一下：一条文案平均 40 个字符，一种语言 2000 条，UTF-8 编码下大概 80KB。支持五种语言就是 400KB 左右，压缩进 AAB 之后更少。这个量级在现代应用里基本可以忽略，远比不上几张图片的零头。
但如果语言数量上到二十种以上，就值得考虑按需加载了。思路是把各语言的 Map 从主包里拆出来，做成运行时可取的资源，启动时只加载当前语言和兜底语言。代价是首屏可能有一瞬间的延迟，而且拆出来的资源需要自己管理缓存和失效。我的建议是：语言数量在十种以内，直接全量内置，别折腾；超过十种再评估，而且要先量一下当前包体的实际构成，别凭感觉优化。
内存方面，Map 是常驻的，而且字符串在 Dart 里是常量池管理的，同一份字符串不会重复占内存。真正需要注意的是不要在代码里用拼接生成大量临时字符串，比如在 build 里反复做'prefix_${value}'.tr这种动态键名。动态键名本身是可行的，但它会让翻译表里的键集合变得不可静态分析，前面说的缺失键检查脚本就失效了。能用静态键就尽量用静态键，这是我一直坚持的原则。
最后分享一个我用了很久的自查清单，每次上线前过一遍，基本能避掉大部分多语言相关的线上问题：
- 全局搜索
.tr，确认没有出现在 build 方法之外的位置 - 确认
GetMaterialApp上的三个Global*Delegates都在 - 确认
supportedLocales跟keys的语言列表完全对齐 - 在真机上把系统语言切成目标语言，冷启动一次，检查首屏
- 点开日期选择器、长按输入框，看系统组件文案是否跟随
- 跑一次键集合差集脚本，确认没有单边缺失的键
- 检查所有带占位符的文案，确认参数都传了
这套东西不是凭空想出来的，每一条背后都有一个或大或小的线上事故。多语言这块的问题特点是“开发期几乎遇不到，上线后必然遇到”，因为开发和测试大多只用一种语言。所以宁可多花半天做这几项检查，也别指望用户帮你发现。
