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