前兩年我把一個(gè)基于 Flutter 的老項(xiàng)目往 OpenHarmony 上遷移時(shí)心里最沒底的不是容器適配也不是 PlatformView 能不能用反而是看起來最不起眼的多語言國際化。原因很簡單OpenHarmony 的 locale 解析、字體回退、資源產(chǎn)物和 Android/iOS 都不一樣照著老經(jīng)驗(yàn)寫出來的國際化代碼在鴻蒙設(shè)備上經(jīng)常出現(xiàn)“英文正常、中文變方塊”“系統(tǒng)切語言 App 不響應(yīng)”“日期格式多出一個(gè)時(shí)區(qū)偏差”這類詭異問題。這篇文章以我手上的“萬能游戲庫 App”為例完整梳理一遍在 Flutter for OpenHarmony 上做多語言國際化的落地過程從 ARB 文件怎么寫、gen-l10n 怎么配到 MaterialApp 里怎么動(dòng)態(tài)切語言、怎么和原生側(cè)通信再到實(shí)際調(diào)試中踩過的一堆坑。不管你手頭是游戲庫、工具類還是內(nèi)容社區(qū)類的 App只要你的 Flutter 項(xiàng)目需要跑到鴻蒙設(shè)備上這條鏈路基本都是通用的。文章不會(huì)只貼結(jié)論我會(huì)把每一步為什么這么做講清楚方便你根據(jù)自己項(xiàng)目的實(shí)際情況調(diào)整。1. 為什么 OpenHarmony 上的 Flutter 國際化不能直接照搬 Android/iOS 的經(jīng)驗(yàn)先說一個(gè)很多人容易忽略的事實(shí)Flutter 的國際化機(jī)制本身是跨平臺(tái)統(tǒng)一的但“讀取系統(tǒng)語言”“加載字體”“打包 emoji/日期符號(hào)數(shù)據(jù)”這些能力每一層都依賴底層平臺(tái)的具體實(shí)現(xiàn)。OpenHarmony 對(duì) Flutter 的適配層flutter_ohos在幾個(gè)關(guān)鍵點(diǎn)上和 Android 有差異如果你只是把以前 Android/iOS 項(xiàng)目的國際化代碼原樣搬過來大概率會(huì)在鴻蒙設(shè)備上翻車。1.1 locale 解析順序和語言標(biāo)簽差異Flutter 在啟動(dòng)時(shí)會(huì)通過PlatformDispatcher.instance.locales拿到系統(tǒng)當(dāng)前的語言列表然后交給MaterialApp的localeResolutionCallback去做匹配。在 Android 上系統(tǒng)返回的語言標(biāo)簽通常是zh-CN、en-US這種 BCP 47 格式但在 OpenHarmony 上不同廠商定制系統(tǒng)返回的標(biāo)簽格式并不完全統(tǒng)一我見過zh-Hans-CN、zh-CN、zh-Hans混著來的情況。這里有個(gè)隱蔽的坑如果你在代碼里直接比較字符串比如locale.toString() zh_CN那在標(biāo)簽格式不一致時(shí)就會(huì)匹配失敗。正確的做法是永遠(yuǎn)基于languageCode和scriptCode做判斷而不是比字符串。比如判斷是否中文應(yīng)該看locale.languageCode zh簡體/繁體的區(qū)分再看locale.scriptCode或locale.countryCode。另一個(gè)差異是 locale 的解析時(shí)機(jī)。在 Android 上如果系統(tǒng)語言中途改變Flutter 的didChangeLocales回調(diào)會(huì)及時(shí)觸發(fā)但在部分 OpenHarmony 設(shè)備上這個(gè)回調(diào)觸發(fā)時(shí)機(jī)偏晚甚至需要重啟 App 才能生效。這個(gè)問題我在后面的動(dòng)態(tài)切換章節(jié)會(huì)專門講應(yīng)對(duì)方案。1.2 資源打包裁剪帶來的“隱形缺數(shù)據(jù)”O(jiān)penHarmony 的 HAP 打包機(jī)制會(huì)把資源做壓縮和裁剪這和 Android 的 AAB/APK 資源合并邏輯不一樣。Flutter 的flutter_localizations和intl依賴了一份完整的 locale 數(shù)據(jù)包括日期符號(hào)、數(shù)字分隔符、貨幣格式等這些數(shù)據(jù)在 Android 上通常會(huì)被完整打包但在鴻蒙的 HAP 產(chǎn)物里有概率被裁剪掉部分語言數(shù)據(jù)。我實(shí)際遇到的情況是App 里切到法語、阿拉伯語時(shí)日期格式化直接拋LocaleDataException報(bào)錯(cuò)信息大概意思是“找不到該 locale 的日期符號(hào)數(shù)據(jù)”。排查后發(fā)現(xiàn)不是intl依賴沒加而是 HAP 打包時(shí)把用不到的語言數(shù)據(jù)過濾了。針對(duì)這個(gè)問題比較穩(wěn)妥的做法是在pubspec.yaml里顯式聲明你需要的語言資源并且不依賴intl的隱式加載所有日期/數(shù)字格式化都自己傳入 locale 參數(shù)。1.3 字體回退鏈完全不同OpenHarmony 系統(tǒng)默認(rèn)字體是 HarmonyOS Sans中英文混排時(shí)它有自己的回退優(yōu)先級(jí)。但 Flutter 層如果給某個(gè)Text組件顯式指定了 fontFamily比如只指定了某個(gè)西文字體那中文字符在鴻蒙上可能直接渲染成豆腐塊因?yàn)?Flutter 的字體回退機(jī)制不會(huì)像系統(tǒng)原生那樣自動(dòng)去系統(tǒng)字體里找中文字形。這個(gè)問題的排查難度在于同樣的代碼在 Android 上完全正常因?yàn)?Android 的字體回退鏈覆蓋廣換到鴻蒙上就變成“某些頁面中文全沒了”。我在第五章會(huì)給出具體的 fontFamilyFallback 配置方案這里先提醒一句在 OpenHarmony 上做國際化字體策略一定要單獨(dú)測不能依賴“Android 上沒問題”的經(jīng)驗(yàn)。1.4 為什么選 gen-l10n 而不是第三方方案現(xiàn)在 Flutter 社區(qū)里有不少國際化方案比如easy_localization、i18n_extension還有各種自己手寫Localizations類的做法。我的結(jié)論很明確新項(xiàng)目或者準(zhǔn)備長期維護(hù)的項(xiàng)目直接用官方gen-l10n就好。官方方案的類型安全做得最徹底。ARB 文件里定義的每一個(gè) key生成代碼后都會(huì)有對(duì)應(yīng)的強(qiáng)類型方法寫錯(cuò) key 名編譯期就報(bào)錯(cuò)而不是運(yùn)行時(shí)顯示一個(gè)缺失文案的 key 字符串。更關(guān)鍵的是gen-l10n生成的AppLocalizations和flutter_localizations是官方同一個(gè)技術(shù)棧兩者在 locale 匹配、日期符號(hào)加載上的協(xié)作最順暢。第三方方案在鴻蒙適配時(shí)一旦出問題你基本找不到人能幫你排查。2. 工程初始化與 l10n 配置細(xì)節(jié)確定了用官方 gen-l10n 之后接下來就是把工程底子打好。這個(gè)階段配置錯(cuò)了后面寫再多 ARB 文件都是白費(fèi)所以我建議你把這個(gè)章節(jié)當(dāng)成“照著抄就行”的 checklist 來看。2.1 環(huán)境準(zhǔn)備Flutter SDK 與 OpenHarmony SDK 的搭配先在開發(fā)機(jī)上裝好支持 OpenHarmony 的 Flutter SDK。目前社區(qū)主流的做法是從 OpenHarmony 官方 Gitee 倉庫拉 flutter_flutter 的 OpenHarmony 分支然后配合 DevEco Studio 一起使用。需要注意版本匹配不同的 OpenHarmony API 版本對(duì)應(yīng)不同的 Flutter 分支裝錯(cuò)版本會(huì)導(dǎo)致編譯階段直接報(bào)錯(cuò)。日常開發(fā)和調(diào)試我推薦在 DevEco Studio 里啟動(dòng)鴻蒙模擬器跑 Flutter 項(xiàng)目。模擬器版本選擇上優(yōu)先選 API 9 以上的系統(tǒng)鏡像因?yàn)樘系溺R像對(duì) Flutter engine 的支持不完整容易出現(xiàn)頁面白屏或渲染異常容易被誤判成國際化代碼的問題。2.2 依賴聲明與 pubspec 配置國際化相關(guān)的依賴其實(shí)只有兩個(gè)別多裝。在pubspec.yaml里加上dependencies: flutter: sdk: flutter flutter_localizations: sdk: flutter intl: any flutter: generate: truegenerate: true這個(gè)配置是關(guān)鍵。打開它之后每次flutter run或flutter build都會(huì)自動(dòng)觸發(fā)代碼生成你不需要手動(dòng)跑 gen-l10n 命令。但有一點(diǎn)要注意如果你在 IDE 里開啟了熱重載改完 ARB 文件后通常需要手動(dòng)執(zhí)行一次flutter gen-l10n才能看到效果這個(gè)我在常見問題章節(jié)會(huì)細(xì)說。intl的版本這里寫了any官方推薦是intl: ^0.19.0或更高版本但我建議不要鎖死小版本因?yàn)閒lutter_localizations內(nèi)部對(duì)intl有版本約束鎖得太死容易在pub get時(shí)產(chǎn)生依賴沖突。2.3 l10n.yaml 配置文件逐項(xiàng)講解在項(xiàng)目根目錄新建l10n.yaml這是 gen-l10n 的核心配置。我用的配置長這樣arb-dir: lib/l10n template-arb-file: app_zh.arb output-localization-file: app_localizations.dart output-class: AppLocalizations output-dir: lib/generated nullable-getter: false synthetic-package: false untranslated-messages-file: untranslated.json每一項(xiàng)的作用我拆開講arb-dir存放 ARB 文件的目錄建議固定在lib/l10n方便統(tǒng)一管理。template-arb-file模板文件也就是你所有文案的“主語言”。我用中文app_zh.arb作為模板因?yàn)槲业闹髁τ脩羰侵形挠脩糁髡Z言文案最全其他語言文件以它為基準(zhǔn)做翻譯。output-class和output-localization-file生成出來的類名和文件名這里定義了AppLocalizations后面代碼里到處要用到它。nullable-getter: false生成AppLocalizations.of(context)時(shí)返回非空類型。默認(rèn)如果沒找到匹配的 locale 會(huì)返回 null你在業(yè)務(wù)代碼里就得到處做空判斷改成 false 后找不到 locale 時(shí)會(huì)自動(dòng) fallback 到模板語言代碼會(huì)干凈很多。前提是你必須把supportedLocales配置好。synthetic-package: false把生成代碼輸出到真實(shí)目錄而不是虛擬包。這樣做的意義是生成代碼可以被 IDE 索引跳轉(zhuǎn)定義時(shí)能看到具體實(shí)現(xiàn)排查問題方便得多。untranslated-messages-file導(dǎo)出未翻譯的文案清單方便你在 CI 流程里檢查遺漏。2.4 ARB 文件目錄結(jié)構(gòu)與最小示例在lib/l10n目錄下我會(huì)放置這樣幾個(gè)文件lib/l10n/ app_zh.arb app_en.arbapp_zh.arb最小內(nèi)容示例{ locale: zh, appTitle: 游戲庫, tabHome: 首頁, tabMine: 我的, downloadCount: {count} 次下載, downloadCount: { placeholders: { count: { type: int } } } }這里locale是必須的gen-l10n 靠它識(shí)別語言文件名里的zh會(huì)和它做校驗(yàn)不一致會(huì)報(bào)錯(cuò)。downloadCount這種帶占位符的字符串必須在對(duì)應(yīng)的 metadata 里聲明placeholders的類型否則生成代碼時(shí)沒法確定參數(shù)類型是 int 還是 String。3. ARB 文件編寫與代碼生成實(shí)戰(zhàn)配置好工程后真正花時(shí)間的其實(shí)是 ARB 文件本身的編寫。很多人覺得翻譯文案很簡單寫起來才發(fā)現(xiàn)“同一句話在不同語言里語序不一樣”“單復(fù)數(shù)形式完全不同”“日期格式一換語言就亂掉”這些才是國際化工作的真正難點(diǎn)。3.1 占位符與復(fù)數(shù)最容易翻車的兩件事先說占位符。中文里“5 次下載”和英文里 “5 downloads” 結(jié)構(gòu)差不多但換成“該游戲支持 2 人聯(lián)機(jī)”中文是“數(shù)字 單位 動(dòng)作”某些語言里可能是“動(dòng)作 數(shù)字 單位”。所以千萬不要在代碼里寫$count downloads這種字符串拼接而是把整句話放到 ARB 文件里讓翻譯人員決定語序。這個(gè)原則叫“完整句子優(yōu)先”是國際化里最基礎(chǔ)也最重要的一條。復(fù)數(shù)問題則更隱蔽。英文有單數(shù)/復(fù)數(shù)兩套形式中文有“零、一、二、多”多套量詞邏輯俄語還有更復(fù)雜的復(fù)數(shù)規(guī)則。gen-l10n 通過 ICU MessageFormat 語法來處理一個(gè)典型的例子playCount: {count, plural, 0{暫無下載} 1{下載 1 次} other{下載 {count} 次}}生成代碼后你會(huì)發(fā)現(xiàn)playCount方法的簽名里直接接收一個(gè)count參數(shù)會(huì)自動(dòng)根據(jù)傳入的數(shù)字做匹配。在中文文案里0、1、other三段可能看起來是重復(fù)的但還是建議全部寫出來因?yàn)橛⑽陌姹菊娴男枰獑螐?fù)數(shù)之分。3.2 日期和時(shí)間格式化必須顯式傳 localeARB 文件里不建議直接寫“2024年1月5日”這種硬編碼的日期文案因?yàn)椴煌Z言環(huán)境下格式完全不一樣。正確做法是在生成代碼里用DateFormat配合AppLocalizations的 locale 參數(shù)做格式化。我通常的做法是給日期字符串定義成帶占位符的模板然后傳入格式化好的日期字符串String getDateText(String formattedDate) { return l10n.dateLabel(formattedDate); }而formattedDate本身在業(yè)務(wù)層用DateFormat.yMMMd().format(DateTime.now())生成這個(gè)DateFormat會(huì)從Localizations.localeOf(context)自動(dòng)讀取當(dāng)前語言。這樣換語言時(shí)日期顯示格式會(huì)自動(dòng)跟隨變化而不需要為每種語言手工維護(hù)一套“幾月幾號(hào)”的翻譯。3.3 生成代碼的產(chǎn)物與使用方式在lib/l10n目錄下準(zhǔn)備好app_zh.arb和app_en.arb后執(zhí)行flutter gen-l10n生成的代碼默認(rèn)在lib/generated/下核心文件是app_localizations.dart它導(dǎo)出了AppLocalizations類和AppLocalizations.delegate。調(diào)用文案的方式有兩種一種是傳統(tǒng)寫法AppLocalizations.of(context)!.appTitle另一種是 gen-l10n 附帶生成的擴(kuò)展屬性context.l10n.appTitle。我推薦后者寫法更簡潔也不容易忘記空判斷。有一點(diǎn)要特別提醒生成目錄里的代碼是自動(dòng)生成的不要手工改動(dòng)。哪怕你只是想臨時(shí)改一個(gè)單詞也應(yīng)該回到 ARB 文件里改重新執(zhí)行生成命令。否則下次生成時(shí)你的手改會(huì)被直接覆蓋造成“改了但沒生效”的困惑。3.4 用 part 組織生成的代碼時(shí)的注意事項(xiàng)如果你的項(xiàng)目已經(jīng)在用part指令做模塊化組織比如想把AppLocalizations的擴(kuò)展方法拆到其他文件里這部分要格外小心。gen-l10n 默認(rèn)生成的app_localizations.dart是獨(dú)立庫它不會(huì)主動(dòng)參與你的 part 體系。如果你確實(shí)需要把相關(guān)代碼納入 part 結(jié)構(gòu)我的建議是不要試圖修改生成文件的頭部來適配part of而是單獨(dú)寫一個(gè)擴(kuò)展文件通過extension AppLocalizationsX on BuildContext的方式做二次封裝這樣既能保持生成代碼純凈又能讓業(yè)務(wù)代碼統(tǒng)一走你的封裝入口。將來升級(jí) Flutter SDK 導(dǎo)致生成代碼結(jié)構(gòu)變化時(shí)你的封裝層不受影響。4. MaterialApp 加載語言與動(dòng)態(tài)切換方案ARB 文件寫好了生成代碼也出來了接下來就是把它接到MaterialApp上并實(shí)現(xiàn)運(yùn)行時(shí)的語言切換。這個(gè)章節(jié)是整個(gè)國際化方案里最容易出各種“奇奇怪怪問題”的地方尤其是動(dòng)態(tài)切換時(shí)頁面狀態(tài)丟失、原生控件語言不跟隨這類我會(huì)一個(gè)個(gè)講。4.1 注冊(cè)四個(gè) delegates一個(gè)都不能少在MaterialApp里配置localizationsDelegates新手經(jīng)常會(huì)漏掉。標(biāo)準(zhǔn)配置如下MaterialApp( locale: _locale, supportedLocales: const [ Locale(zh), Locale(en), ], localizationsDelegates: const [ AppLocalizations.delegate, GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate, GlobalCupertinoLocalizations.delegate, ], )這四個(gè) delegate 各有分工AppLocalizations.delegate加載你自己定義的業(yè)務(wù)文案GlobalMaterialLocalizations.delegate負(fù)責(zé) Material 組件內(nèi)置文案比如日期選擇器、對(duì)話框按鈕的“確定/取消”GlobalWidgetsLocalizations.delegate負(fù)責(zé) widget 層的語義文案最后一個(gè)GlobalCupertinoLocalizations.delegate經(jīng)常被忽略但如果你用了Cupertino系列組件或者某些 Material 組件內(nèi)部依賴了 Cupertino 的本地化文案漏掉它就會(huì)在運(yùn)行時(shí)收到 “Localizations not found” 的報(bào)錯(cuò)。4.2 首幀語言匹配本地偏好優(yōu)先系統(tǒng)語言兜底很多 App 要求“用戶手動(dòng)切換語言后App 始終記住用戶選擇而不是跟隨系統(tǒng)語言變化”。這個(gè)邏輯要在localeResolutionCallback里實(shí)現(xiàn)而不是簡單地把locale設(shè)成系統(tǒng)語言。我的做法是啟動(dòng)時(shí)先讀本地緩存的語言偏好如果有就返回用戶偏好沒有就把系統(tǒng)語言作為默認(rèn)。這段邏輯寫成代碼大致是localeResolutionCallback: (locale, supportedLocales) { final savedLang _prefs.getString(app_language); if (savedLang ! null) { return Locale(savedLang); } for (final supported in supportedLocales) { if (supported.languageCode locale?.languageCode) { return supported; } } return const Locale(zh); }這里有一個(gè)細(xì)節(jié)supportedLocales列表里我寫的是Locale(zh)和Locale(en)沒有寫具體的國家地區(qū)。這樣zh能同時(shí)匹配zh_CN、zh_TW、zh_HKen能匹配所有英語地區(qū)。如果你在列表里寫了Locale(zh, CN)那繁體中文地區(qū)的用戶就不會(huì)匹配到中文會(huì)直接掉到 fallback 英語這個(gè)坑很容易踩。4.3 動(dòng)態(tài)切換語言用全局狀態(tài)驅(qū)動(dòng) MaterialApp 重建實(shí)現(xiàn)語言熱切換的關(guān)鍵思路是讓MaterialApp的locale參數(shù)變成響應(yīng)式的切換語言時(shí)更新全局狀態(tài)從而觸發(fā)整棵 widget 樹重建語言相關(guān)的配置。我用的是一個(gè)簡單的ChangeNotifier不引入重量級(jí)狀態(tài)管理庫也有很好效果class LocaleProvider extends ChangeNotifier { Locale _locale const Locale(zh); Locale get locale _locale; Futurevoid setLocale(Locale locale) async { _locale locale; notifyListeners(); await _saveToPrefs(locale.languageCode); } }然后在main.dart里把MaterialApp包進(jìn)ListenableBuilderListenableBuilder( listenable: _localeProvider, builder: (context, _) { return MaterialApp( locale: _localeProvider.locale, ... ); }, )這樣的好處是切換語言只觸發(fā)MaterialApp層級(jí)的 rebuild底層已構(gòu)建好的路由棧不會(huì)銷毀。也就是說用戶在“游戲詳情頁”切完語言頁面只是刷新文案點(diǎn)擊返回能回到原來的列表位置不會(huì)跳回首頁。如果你用的是Cubit或Bloc這類狀態(tài)管理庫思路完全一樣只需要把ChangeNotifier換成語境對(duì)應(yīng)的狀態(tài)類關(guān)鍵是保證locale變化能驅(qū)動(dòng)MaterialApp的locale參數(shù)更新。4.4 語言切換后與原生側(cè)通信EventChannel 的正確用法游戲庫 App 里難免有原生控件場景比如登錄頁嵌了鴻蒙原生的驗(yàn)證碼組件、分享面板調(diào)用的是系統(tǒng)服務(wù)。這些原生界面里如果寫死了中文或英文就會(huì)和 Flutter 層切換語言后文案不一致。我的做法是切換語言后通過EventChannel主動(dòng)通知鴻蒙原生側(cè)。具體來說在 Flutter 端const _languageChannel EventChannel(com.example.app/language); _languageChannel.receiveBroadcastStream().listen((event) { // 接收原生側(cè)發(fā)來的語言狀態(tài) });而在切換語言的方法里const _methodChannel MethodChannel(com.example.app/language); await _methodChannel.invokeMethod(setLanguage, {lang: _locale.languageCode});原生側(cè)收到setLanguage后同步更新所有原生頁面的本地化文案。這里要注意的是 EventChannel 和 MethodChannel 的分工Flutter 主動(dòng)通知原生用 MethodChannel 更直接原生主動(dòng)推送狀態(tài)變化給 Flutter 才用 EventChannel。別搞反了否則調(diào)試時(shí)很難定位是通信時(shí)機(jī)問題還是參數(shù)傳遞問題。4.5 切換語言后的頁面狀態(tài)保持語言切換后常見的兩個(gè)狀態(tài)問題我實(shí)測踩過并解決了第一個(gè)是TabBar索引跳回第一頁。原因是很多 App 的TabBarView在語言切換時(shí)因?yàn)镸aterialApprebuild 導(dǎo)致整個(gè) tab 頁面樹重建。解決辦法是讓 tab 索引狀態(tài)不要依賴DefaultTabController而是顯式用一個(gè)ValueNotifierint保存索引傳給TabBar和TabBarView這樣 rebuild 時(shí)索引不會(huì)丟。第二個(gè)是用戶已滾動(dòng)到很長的列表位置丟失。比如游戲列表頁切語言后回到頂部體驗(yàn)很差。這個(gè)問題本質(zhì)上不是國際化的問題而是你切換語言時(shí)把整個(gè)列表頁的ScrollController狀態(tài)也一起重建了。解決辦法是不要把列表頁的滾動(dòng)位置狀態(tài)放在build方法里創(chuàng)建的局部變量中應(yīng)該提升到頁面 State 的成員變量或者用PageStorageKey保存滾動(dòng)位置。5. 針對(duì) OpenHarmony 的落地細(xì)節(jié)與調(diào)試技巧前幾章的內(nèi)容在 Android 和 iOS 上也基本適用但這一章我要專門講只有在鴻蒙設(shè)備上才會(huì)遇到的問題。如果你手上暫時(shí)沒有 OpenHarmony 設(shè)備建議先把這章收藏等真機(jī)調(diào)試時(shí)回來看。5.1 DevEco 模擬器上的系統(tǒng)語言設(shè)置差異我在鴻蒙模擬器上做首輪測試時(shí)發(fā)現(xiàn)系統(tǒng)設(shè)置里的語言列表不一定包含你 App 聲明的所有語言。比如某些廠商定制系統(tǒng)語言列表里只有簡體中文、英文、繁體中文等少數(shù)幾個(gè)選項(xiàng)。如果你的 supportedLocales 里聲明了日語、韓語但系統(tǒng)設(shè)置里根本沒有日語選項(xiàng)那么即使用戶是日語使用者他也無法在系統(tǒng)層面切到日語你的 App 在首幀時(shí)會(huì)直接落到 fallback。針對(duì)這種情況有兩個(gè)應(yīng)對(duì)策略一是把用戶手動(dòng)切換語言的功能放在 App 內(nèi)部不依賴系統(tǒng)設(shè)置二是在localeResolutionCallback里打印調(diào)試日志確認(rèn)設(shè)備實(shí)際回傳的 locale 到底是什么。調(diào)試時(shí)可別只看模擬器界面的語言選擇要在代碼里debugPrint(PlatformDispatcher.instance.locales)看到真值才靠譜。5.2 字體回退配置HarmonyOS Sans 與 fontFamilyFallback前面提到了鴻蒙字體回退的問題這里給具體方案。如果你在 App 里使用了自定義字體尤其是一套只有拉丁字符的英文字體必須給它配置中文回退。在TextStyle里有一種寫法TextStyle( fontFamily: MyLatinFont, fontFamilyFallback: [HarmonyOS Sans, sans-serif], )這樣在顯示中文時(shí)Flutter 會(huì)優(yōu)先走fontFamily發(fā)現(xiàn)沒有對(duì)應(yīng)字形就回退到fontFamilyFallback列表里的字體。在鴻蒙上把HarmonyOS Sans放第一位通常是對(duì)的即使你的設(shè)備上沒有顯式注冊(cè)該字體系統(tǒng)也會(huì)在回退過程里處理。還有一點(diǎn)容易被忽略全局設(shè)置ThemeData里的fontFamily會(huì)影響所有文本如果你的全局字體只設(shè)置了英文字體那所有中文都會(huì)出問題。排查思路是先看單個(gè) Text 是否顯式指定了字體再看全局 Theme 是否指定了不合適的字體最后才是系統(tǒng)層面的字體缺失。5.3 Impeller 渲染引擎與文本測量問題Flutter 在 OpenHarmony 上的渲染后端目前還是以 Skia 為主但官方也一直在推進(jìn) Impeller 的適配工作。我實(shí)測下來在鴻蒙設(shè)備上開啟 Impeller 后某些中英文混排的長文本換行位置會(huì)和 Skia 后端不同具體的表現(xiàn)是同一個(gè)字符串同一屏寬度下?lián)Q行位置變了可能導(dǎo)致部分布局出現(xiàn)輕微遮擋。這個(gè)問題在國際化場景下容易放大因?yàn)闅W美語言的文本普遍比中文長。如果你的布局是按中文長度設(shè)計(jì)的切到英文后文本溢出再疊加渲染后端差異排查起來會(huì)非常頭疼。我的建議是在鴻蒙設(shè)備上做語言切換測試時(shí)至少要跑一遍所有長文案場景英文、德文這種長單詞語言特別容易暴露溢出問題。不要因?yàn)槭恰巴粋€(gè) Flutter 版本”就忽略渲染后端的差異。5.4 包體控制語言數(shù)據(jù)按需加載與裁剪flutter_localizations會(huì)引入大量語言的日期、數(shù)字符號(hào)數(shù)據(jù)如果全量打包對(duì)鴻蒙 HAP 的包體影響不小。游戲庫這類中大型 App 對(duì)包體敏感所以我會(huì)做兩個(gè)裁剪操作第一在l10n.yaml里通過supportedLocales或生成配置只保留目標(biāo)語言。比如只做中英文就不要讓 gen-l10n 為所有語言生成 getter。第二在pubspec.yaml里如果某些依賴庫允許挑選 locale 子集用--dart-defineFLUTTER_LOCALIZATION_LOCALESzh,en這類參數(shù)在構(gòu)建時(shí)縮減數(shù)據(jù)。這個(gè)參數(shù)不一定在所有版本可用但方向是對(duì)的凡是能按需加載的語言數(shù)據(jù)都不要貪多。順帶提醒做這些裁剪操作后一定要在鴻蒙真機(jī)上重新驗(yàn)證“切阿拉伯語”“切泰語”這類極端場景因?yàn)椴眉暨^頭會(huì)直接導(dǎo)致缺失語言數(shù)據(jù)而崩潰而模擬器上因?yàn)閿?shù)據(jù)緩存原因有時(shí)候反而測不出來。6. 常見問題與排查技巧實(shí)錄這一章是從多個(gè)項(xiàng)目里整理出來的高頻問題清單。大部分問題我在前文已經(jīng)點(diǎn)到過這里集中做一個(gè)速查配上我排查時(shí)的思路。問題現(xiàn)象根本原因排查辦法改完 ARB 文件熱重載不生效gen-l10n 的代碼生成不會(huì)隨熱重載自動(dòng)觸發(fā)手動(dòng)執(zhí)行flutter gen-l10n或重啟flutter run系統(tǒng)語言切換后 App 不響應(yīng)鴻蒙部分設(shè)備didChangeLocales時(shí)機(jī)不穩(wěn)在 App 內(nèi)提供手動(dòng)切換入口不依賴系統(tǒng)事件中文顯示成方塊字體回退鏈斷掉指定字體無中文字形配置fontFamilyFallback檢查全局 Theme 字體日期格式化拋 LocaleDataExceptionHAP 打包裁剪了 intl 語言數(shù)據(jù)顯式聲明所需語言資源驗(yàn)證 build 后資源完整性切換語言后 TabBar 跳回第一頁頁面樹重建導(dǎo)致 tab 狀態(tài)丟失用ValueNotifierint顯式保存 tab 索引PlatformView 內(nèi)原生控件文案不跟隨原生側(cè)不知道語言切換事件通過 MethodChannel 主動(dòng)通知原生刷新英文文本溢出遮擋布局按中文長度設(shè)計(jì)翻譯后文本變長所有動(dòng)態(tài)文本容器預(yù)留邊距測試長語言首幀語言匹配成英文supportedLocales 列表不完整或 fallback 語義不對(duì)檢查 locale 匹配邏輯打印平臺(tái)實(shí)際 locale 列表6.1 改完 ARB 文件熱重載沒反應(yīng)這個(gè)問題幾乎每個(gè)用 gen-l10n 的人都會(huì)遇到。原因是代碼生成發(fā)生在編譯之前熱重載并不會(huì)感知 ARB 文件的修改。解決辦法很簡單回到終端執(zhí)行flutter gen-l10n讓它重新生成 Dart 代碼然后再熱重載。如果你用的是 Android Studio 或 DevEco Studio 里的 run 模式可以把它理解成“改完資源后要先編譯一次資源再加載 Dart 代碼”。6.2 切到某些語言后 App 直接崩潰這類崩潰大概率是 locale 數(shù)據(jù)找不到。常見場景是supportedLocales里聲明了Locale(fr)但intl的日期符號(hào)數(shù)據(jù)里沒有fr運(yùn)行時(shí) build 日期格式就炸了。排查時(shí)看崩潰堆棧里有沒有LocaleDataException有的話就回到 5.4 節(jié)的“語言數(shù)據(jù)按需加載”部分檢查你的裁剪配置。6.3 PlatformView 嵌入原生控件文案語言不統(tǒng)一游戲庫 App 里如果嵌了原生廣告、原生地圖或系統(tǒng)相冊(cè)選擇器這些組件走的不是 Flutter 的 Localizations。我的經(jīng)驗(yàn)是所有需要和原生打交道的文案都走一遍我們項(xiàng)目里統(tǒng)一的“語言同步通道”。簡單說就是切換語言時(shí)除了更新 Flutter 內(nèi)部狀態(tài)同時(shí)調(diào)用 MethodChannel 把當(dāng)前語言告訴原生層讓原生層自己更新界面。如果你發(fā)現(xiàn)某個(gè)原生控件語言沒變先檢查原生側(cè)有沒有監(jiān)聽對(duì)應(yīng)通道再檢查事件是不是在setState之前發(fā)的——順序錯(cuò)了也會(huì)丟消息。6.4 首幀語言標(biāo)簽匹配錯(cuò)誤在鴻蒙設(shè)備上系統(tǒng)設(shè)置里選擇“簡體中文”后PlatformDispatcher可能返回Locale(zh, Hans, CN)或Locale(zh, CN)兩種格式。如果你的supportedLocales里寫了Locale(zh, CN)那么遇到Locale(zh, Hans, CN)就可能匹配不上。我之前給過一個(gè)辦法語言匹配永遠(yuǎn)只用languageCode判斷除非你要明確區(qū)分簡繁。這條規(guī)則在國際化項(xiàng)目里應(yīng)該作為鐵律寫進(jìn)團(tuán)隊(duì)規(guī)范。6.5 字符串拼接導(dǎo)致翻譯不自然最后這條不算 bug但影響品質(zhì)。很多游戲庫 App 會(huì)把“查看全部”和“下載量”分開寫再用$text1 $text2拼起來。這種拼接在中文里看著正常翻譯到英文、日文就可能變成“View All 5 Downloads”這種別扭形式。我建議所有需要組合的文案都整句進(jìn) ARB哪怕要傳三四個(gè)參數(shù)。翻譯文本有整句上下文語言質(zhì)量會(huì)高很多也方便后續(xù)接入專業(yè)翻譯團(tuán)隊(duì)。7. 多語言文件的團(tuán)隊(duì)協(xié)作與長期維護(hù)國際化不是一個(gè)一次性的編碼任務(wù)。尤其在游戲庫這種快速迭代的項(xiàng)目里每次發(fā)版都有新游戲文案要加、新活動(dòng)頁要加語言。如果團(tuán)隊(duì)里多人同時(shí)改 ARB 文件很容易產(chǎn)生沖突而且翻譯內(nèi)容本身也需要審核流程。最后這一章聊聊我在協(xié)作和維護(hù)層面沉淀下來的經(jīng)驗(yàn)。7.1 ARB 文件的命名與版本管理約定我給團(tuán)隊(duì)定的規(guī)范是ARB 文件按語言分文件文件名統(tǒng)一app_langCode.arb。中文模板app_zh.arb永遠(yuǎn)作為主文件新增 key 先加在中文模板里然后其他語言的翻譯文件在它的基礎(chǔ)上補(bǔ)充。多人協(xié)作時(shí)ARB 文件的沖突比較常見。因?yàn)?JSON 結(jié)構(gòu)簡單Git 合并沖突通常能自動(dòng)解決但為了減少?zèng)_突面我要求每次提交只改自己負(fù)責(zé)的那幾個(gè) key不要在同一個(gè)提交里大范圍重排字段順序。另外建議配置 CI 檢查如果某個(gè)語言文件缺少模板文件中的 key構(gòu)建直接失敗。這樣能避免“中文有、英文沒有”發(fā)布上線后才被發(fā)現(xiàn)。7.2 生成代碼不要手工改但可以加封裝層前面說過生成目錄里的文件不要手改。但業(yè)務(wù)代碼里直接到處寫context.l10n.xxx將來如果生成代碼出現(xiàn)破壞性變更改起來會(huì)想哭。我習(xí)慣在業(yè)務(wù)代碼和生成代碼之間加一個(gè)薄薄的封裝比如抽取AppStrings類統(tǒng)一暴露所有文案方法。這樣生成代碼的內(nèi)部實(shí)現(xiàn)變了業(yè)務(wù)層基本不用動(dòng)。這個(gè)封裝層在 Flutter SDK 升級(jí)時(shí)特別值錢。7.3 翻譯文案需要“語境注釋”ARB 文件里的keymetadata 里除了placeholders官方還預(yù)留了description字段。我強(qiáng)烈建議把文案出現(xiàn)的場景寫在里面比如“用于游戲詳情頁下載按鈕下方展示累計(jì)下載次數(shù)”這樣翻譯人員不會(huì)把語境弄錯(cuò)。尤其是“Play”這種詞名詞動(dòng)詞不分沒有語境注釋很容易翻錯(cuò)。我的做法是把 description 作為必填項(xiàng)寫不出來的業(yè)務(wù)人員說明這個(gè) key 本身定義得有問題。7.4 多語言自測清單我每次發(fā)版前必跑一遍發(fā)版前面臨的多語言問題多數(shù)不是代碼邏輯問題而是“某些頁面漏了翻譯”“某些語言下布局崩了”。我整理了一份自測清單每次覆蓋多語言發(fā)布都會(huì)跑一遍所有一級(jí)頁面首頁、分類、我的在每種語言下截屏對(duì)比。游戲詳情頁的動(dòng)態(tài)字段模擬數(shù)字超過 10000、文本超過 200 字符的場景。切換語言后回到首頁tab 索引和滾動(dòng)位置保持不變。系統(tǒng)切換語言后殺掉 App 冷啟動(dòng)驗(yàn)證首幀語言偏好邏輯。在真機(jī)上驗(yàn)證日期、數(shù)字、貨幣格式是否按當(dāng)前語言顯示。檢查所有 PlatformView 原生組件文案是否同步切換。檢查推送通知里的文案是否跟隨 App 內(nèi)語言選擇。這份清單看著繁瑣但大多數(shù)國際化事故都能在上面幾個(gè)環(huán)節(jié)提前暴露。省下來的線上投訴遠(yuǎn)比測試成本值。8. 幾個(gè)容易被忽略的小細(xì)節(jié)個(gè)人經(jīng)驗(yàn)向最后再分享幾個(gè)我在多個(gè)項(xiàng)目里驗(yàn)證過的小經(jīng)驗(yàn)不構(gòu)成完整章節(jié)但每一個(gè)都能幫你少踩點(diǎn)坑。第一關(guān)于語言偏好存儲(chǔ)。很多人喜歡用shared_preferences存語言代碼這沒問題但注意存儲(chǔ)的 key 要獨(dú)立于其他配置項(xiàng)并且寫入時(shí)要做校驗(yàn)。曾經(jīng)遇到過一個(gè)線上問題用戶設(shè)備上app_language被第三方清理工具清空了導(dǎo)致每次冷啟動(dòng)語言都變回系統(tǒng)語言用戶以為自己的設(shè)置丟了投訴了好幾次。后來改成寫入同時(shí)校驗(yàn)值是否在 supportedLocales 里不在就丟棄問題才解決。第二關(guān)于文本溢出檢測。在游戲列表頁和詳情頁建議在 debug 模式下開啟Text控件的溢出檢測或者干脆在開發(fā)期用一個(gè)腳本跑所有頁面截圖把每張截圖里的溢出標(biāo)記全部標(biāo)紅。英文文本比中文文本長 30% 到 50% 是常態(tài)游戲名稱、活動(dòng)標(biāo)題這種不知道多長的字段是最容易溢出的地方。第三關(guān)于 OpenHarmony 設(shè)備上的測試覆蓋。不同廠商的鴻蒙定制系統(tǒng)語言標(biāo)簽格式和字體回退表現(xiàn)都會(huì)有差異。有條件的話至少找一臺(tái)純 OpenHarmony 設(shè)備、一臺(tái)主流廠商設(shè)備分別測一遍。我自己遇到過“某品牌手機(jī)上中文顯示正常、英文換行位置異?！钡陌咐詈蠖ㄎ坏绞菑S商在系統(tǒng)字體層面做了特殊處理這個(gè)問題只靠模擬器根本看不出來。第四關(guān)于國際化和項(xiàng)目架構(gòu)的先后順序。真的越早把語言機(jī)制設(shè)計(jì)進(jìn)去越好。如果項(xiàng)目已經(jīng)跑了兩三年幾百個(gè)頁面都直接寫死中文再來補(bǔ)國際化那工作量是推倒重來的級(jí)別。我見過太多團(tuán)隊(duì)在需求爆發(fā)的階段把“先寫死中文后面再說”當(dāng)口頭禪結(jié)果后面永遠(yuǎn)沒空補(bǔ)。從第一天就接上 gen-l10n哪怕只做中文后期加語言的成本也不會(huì)太高。