CodeSpirit 多語言國際化使用指南Beta做國際化這件事很多人一開始覺得簡單無非就是“把文案抽出來翻譯幾份切換一下”。真到上手才發(fā)現(xiàn)坑全埋在后面語言包怎么組織才不失控帶參數(shù)的消息怎么處理某個語言的復(fù)數(shù)規(guī)則跟中文完全不一樣怎么辦日期格式、貨幣符號、文字方向……哪一樣拎出來都能讓項目在臨上線前翻車。這篇指南就圍繞CodeSpirit項目的國際化實踐展開把從資源文件設(shè)計、文案抽取到運行時切換、問題排查的完整鏈路梳理一遍所有內(nèi)容都來自我在實際項目里踩過的坑和驗證過的方案適合正在做國際化改造、或者準(zhǔn)備給項目增加多語言支持的開發(fā)者參考。1. 項目啟動前先想清楚語言資源文件的組織方式與命名策略1.1 資源文件的目錄結(jié)構(gòu)怎么定后續(xù)維護才不痛苦很多團隊做國際化第一步就是建一個locales目錄然后按語言分文件夾。這個方向沒錯但顆粒度怎么切直接決定半年后你維護這個項目時的心情。我見過最崩潰的寫法是把所有文案全塞進一個messages.js里一個對象幾千行找一個鍵靠CtrlF來回掃。這種方案在項目只有三五個頁面時還能忍一旦模塊變多沖突和誤改就成了家常便飯。更合理的方式是按業(yè)務(wù)域拆分。CodeSpirit里我推薦這么組織src/ locales/ zh-CN/ common.json auth.json dashboard.json settings.json en-US/ common.json auth.json dashboard.json settings.json這么做的好處顯而易見每個模塊的文案獨立成文件多人并行開發(fā)時各自改各自的git沖突的概率大幅下降。而且按模塊加載時可以做到只加載當(dāng)前路由需要的語言包而不是一次性加載全部首屏性能更好。用JSON而不是JS模塊存文案也有講究。JSON是純數(shù)據(jù)不摻邏輯后端如果要做翻譯管理平臺或者想用在線表格維護文案導(dǎo)入導(dǎo)出都方便。JS模塊雖然能寫函數(shù)、能用變量但也容易混進業(yè)務(wù)邏輯最后搞不清語言包里到底存的是數(shù)據(jù)還是代碼。1.2 Key的命名策略一眼看懂歸屬避免“孤兒文案”Key的命名是國際化項目里最容易被忽視、后患最大的決策。沒有統(tǒng)一規(guī)范翻譯的人不知道這個key是哪個頁面的開發(fā)的人不知道這個key有沒有被引用最后就是一堆“孤兒文案”躺在語言包里刪也不敢刪留又占地方。我建議的命名格式是“模塊.頁面.元素.狀態(tài)”比如dashboard.chart.revenueLabel、auth.login.submitButton、settings.profile.avatarUploadSuccess。這套規(guī)則有四個明確的優(yōu)勢可讀性好看到key就知道它屬于哪個功能無需打開頁面去對照按前綴就能實現(xiàn)語言包的自動合并和分割配合構(gòu)建工具做tree-shaking也方便排序后結(jié)構(gòu)清晰代碼審查時一眼能看出新增了哪些文案工具鏈可以基于前綴自動生成文檔甚至校驗?zāi)硞€模塊下是否有漏翻譯的key再補充一點狀態(tài)盡量寫在key里比如按鈕的加載中狀態(tài)是auth.login.submitButtonLoading而不是auth.login.loading。因為loading這個詞太泛放common里會被各種地方引用改起來牽一發(fā)動全身寫在具體業(yè)務(wù)key下語義明確后續(xù)刪除也無牽掛。2. 最容易踩坑的五個國際化細(xì)節(jié)占位符、復(fù)數(shù)、日期、貨幣與排版方向2.1 占位符別用字符串拼接請統(tǒng)一采用命名參數(shù)國際化里最經(jīng)典的低級錯誤就是寫這樣的代碼// 這樣寫翻譯的人根本沒法調(diào)整語序 const msg 歡迎 username 登錄系統(tǒng);中文語序下“歡迎XX登錄系統(tǒng)”沒毛病但英文習(xí)慣是“Welcome, XX”有些語言甚至?xí)褎釉~放到句尾。你一旦用了字符串拼接翻譯就只能放棄語法正確性把整句硬拆成幾段。這不是翻譯能力問題是代碼結(jié)構(gòu)堵死了人家的路。正確做法是使用命名占位符。CodeSpirit統(tǒng)一用{name}這種語法{ welcome.message: 歡迎 {username} 登錄系統(tǒng), welcome.message_en: Welcome, {username} }調(diào)用時統(tǒng)一走工具函數(shù)不要出現(xiàn)“有的地方用{}、有的地方用%s、有的地方用$1”這種混亂局面。另外要特別提醒同一個key下的參數(shù)不同語言版本里必須保持一致。曾有個項目把{count}寫成了{(lán)num}中文語言包沒暴露問題但英文語言包渲染時直接把{count}當(dāng)普通文本輸出在頁面上用戶看到一串花括號。這種事情就是在挑戰(zhàn)用戶耐心測試還未必覆蓋得到。2.2 復(fù)數(shù)形式不要以為只有英語才區(qū)分單復(fù)數(shù)中文的復(fù)數(shù)處理很簡單名詞基本不變靠量詞表達數(shù)量。所以很多國內(nèi)團隊設(shè)計語言包時壓根沒考慮過復(fù)數(shù)鍵位。等英文包上線問題就來了。英文里“1 item”和“5 items”是兩回事。而阿拉伯語、俄語這些語言的復(fù)數(shù)規(guī)則更復(fù)雜有的分單數(shù)、雙數(shù)、少數(shù)、多數(shù)。硬編碼count 1 ? items : item只能cover住英文遇上別的語言就原形畢露。如果要手動管理可以這樣設(shè)計消息結(jié)構(gòu){ cart.itemCount: { one: 1 item, other: {count} items } }但這還遠(yuǎn)遠(yuǎn)不夠因為不同語言對“哪類數(shù)字算one”的定義不同。所以更可靠的方案是借助Intl.PluralRules這個瀏覽器原生APIconst pr new Intl.PluralRules(ru); pr.select(1); // one pr.select(2); // few pr.select(5); // many在CodeSpirit里我建議語言包的值先通過一個pluralize工具函數(shù)處理根據(jù)當(dāng)前語言環(huán)境自動選擇正確的復(fù)數(shù)形式。這個坑不踩不知道等海外用戶開始反饋“頁面上寫著1 items”你就明白什么叫細(xì)節(jié)決定體驗了。2.3 日期與貨幣永遠(yuǎn)使用Intl API而不是手寫格式時間格式化是另一個重災(zāi)區(qū)?！?024年1月5日”在中文環(huán)境沒問題但放到英文環(huán)境應(yīng)該是“January 5, 2024”或“2024/01/05”歐洲很多國家又是“5 January 2024”。你要是自己寫正則拼接基本就把自己鎖死在一種格式上了。瀏覽器提供了足夠強大的原生能力一定優(yōu)先使用const date new Date(2024-01-05T10:30:00); // 根據(jù)不同locale自動格式化 new Intl.DateTimeFormat(zh-CN, { dateStyle: full }).format(date); // 2024年1月5日星期五 new Intl.DateTimeFormat(en-US, { dateStyle: full }).format(date); // Friday, January 5, 2024貨幣也同理Intl.NumberFormat可以自動處理貨幣符號、千分位和小數(shù)位甚至不同貨幣的展示習(xí)慣。這點在設(shè)計訂單金額展示時極其關(guān)鍵同一個數(shù)字1234.5美元環(huán)境顯示$1,234.50歐元區(qū)顯示1 234,50 €不是簡單換個符號就行。在CodeSpirit里我封裝了一個formatDateTime和一個formatCurrency函數(shù)內(nèi)部統(tǒng)一走Intl API業(yè)務(wù)代碼只管傳入Date對象和金額不要自己做任何拼接。這類基礎(chǔ)函數(shù)越早統(tǒng)一越好不然后面改一次所有頁面都得跟著動。2.4 從右到左語言適配你的頁面可能整個鏡像如果你的產(chǎn)品將來要支持阿拉伯語或希伯來語那國際化不只是文案翻譯整個布局都要反一反。英文是從左往右讀阿拉伯語從右往左導(dǎo)航欄、文字對齊、圖標(biāo)方向全得跟著變。好在這個問題CSS本身有方案。dir屬性切換后flex布局和grid布局大部分情況下會自動鏡像但這不是白來的有幾個地方必須提前設(shè)計文本對齊不能用硬編碼的text-align: left盡量用邏輯屬性text-align: start和endmargin和padding也盡量用margin-inline-start這類邏輯屬性而不是margin-left、margin-right箭頭圖標(biāo)、翻頁按鈕的左右方向需要做鏡像處理CodeSpirit的做法是在根節(jié)點動態(tài)設(shè)置dir屬性配合一套RTL樣式覆蓋變量。做這塊時最好找母語者測試光靠開發(fā)自己看是看不出問題的——我自己曾經(jīng)把阿拉伯語頁面做出來箭頭全反了還不自知直到被用戶截圖打臉。2.5 語言包里的“硬編碼”漏網(wǎng)之魚文案抽離最怕的不是抽得慢而是抽不干凈。常見漏網(wǎng)之魚包括圖片里的文字比如按鈕背景圖里寫著“立即購買”這種只有設(shè)計師重新出圖才能解決后端返回的錯誤信息后端接口直接拋中文前端翻譯不了頁面標(biāo)題document.title的拼接字符串第三方組件自帶的文案比如日期選擇器的“今天”“確定”這里沒有銀彈全憑細(xì)心和規(guī)范。我習(xí)慣在每個迭代的代碼審查里專門加一條“文案檢查”看到字符串字面量就問一句這個東西會不會顯示給用戶會的話為什么不走語言包這個習(xí)慣堅持下來后期翻譯遺漏率會降很多。3. 從零搭建一套可用的國際化流程安裝配置到運行時切換3.1 基礎(chǔ)引入與初始配置首次接壤的準(zhǔn)備工作以CodeSpirit前端項目為例先安裝國際化插件這是vue和react生態(tài)里最常用的方案。安裝好后建立語言包目錄并導(dǎo)入基礎(chǔ)文案。初始化的核心配置大概長這樣import { createI18n } from vue-i18n; const i18n createI18n({ legacy: false, locale: localStorage.getItem(locale) || navigator.language || zh-CN, fallbackLocale: zh-CN, messages: { zh-CN: { common: require(../locales/zh-CN/common.json), auth: require(../locales/zh-CN/auth.json) }, en-US: { common: require(../locales/en-US/common.json), auth: require(../locales/en-US/auth.json) } } });這里有兩個關(guān)鍵點第一fallbackLocale一定要設(shè)置。它的作用是當(dāng)某個key在英文語言包里缺失時自動降級用中文填充而不是直接把key名扔到頁面上。這能避免很多“半成品”的尷尬畫面。第二首屏的locale不要寫死優(yōu)先從用戶過往選擇讀取。localStorage里存了上次的偏好就用偏好沒有就用瀏覽器語言。這算是最樸素的用戶體驗優(yōu)化。還需要在index.html里提前設(shè)置好lang屬性和dir屬性。ESLint等靜態(tài)檢查工具也建議配一個html標(biāo)簽的lang校驗可以提前發(fā)現(xiàn)很多疏忽。3.2 運行時切換語言不只是換語言包狀態(tài)和路由也得聯(lián)動語言切換看起來就是點個按鈕把locale變量改掉但真實落地要注意三件事。第一件事切換后要手動觸發(fā)重新渲染。有些框架的響應(yīng)式系統(tǒng)不會自動追蹤locale的變化你改了值頁面卻沒反應(yīng)讓人懷疑自己寫錯了。解決方法是把當(dāng)前語言作為響應(yīng)式依賴注入或者顯式調(diào)用nextTick后重新渲染。第二件事持久化當(dāng)前語言。切換語言后立即存入localStorage刷新頁面時還能保持用戶的偏好。這個細(xì)節(jié)雖然簡單但沒做的話用戶每次打開都要重新選語言體驗分直接扣一截。第三件事異步加載語言包。切換語言時如果目標(biāo)語言包還沒加載需要動態(tài)import然后等加載完成再更新localeasync function changeLocale(locale) { if (!loadedLocales.has(locale)) { const messages await import(../locales/${locale}/index.js); i18n.global.setLocaleMessage(locale, messages.default); loadedLocales.add(locale); } i18n.global.locale.value locale; localStorage.setItem(locale, locale); }這種懶加載模式的好處是首包不攜帶所有語言英文用戶訪問中文站點時不會為了看英文而先下載一整包中文。項目語言多了以后這個性能收益非常明顯。還有一個小細(xì)節(jié)切換語言后一些第三方組件不會自動跟著變。比如日期選擇器它內(nèi)部默認(rèn)是英文切換成中文后還顯示“January”。這種組件一般自帶locale屬性需要在切換時主動傳入對應(yīng)配置。這也是國際化里比較頭疼的一類問題沒有統(tǒng)一的解決方案只能逐個排查組件文檔。3.3 帶參數(shù)的消息、富文本消息與動態(tài)key的安全接入語言包里除了純靜態(tài)文案還有大量帶動態(tài)參數(shù)的消息。比如訂單狀態(tài)的提示需要把訂單號放到句子里。用前面的命名參數(shù)方案在模板里這樣調(diào)用p{{ t(order.created, { orderNo: order.orderNo }) }}/p這種用法是基礎(chǔ)但有兩個進階場景需要注意。一是富文本。有些文案里需要嵌入鏈接、加粗文字等HTML標(biāo)簽語言包不能只存純文本。CodeSpirit的實踐是把富文本拆成段落級別的key在模板里組合渲染而不是試圖在JSON里寫HTML片段?？吹接腥税颜蜨TML塞進語言包的勸一句翻譯工具的轉(zhuǎn)義問題會讓你哭。二是動態(tài)key。有時候key的一部分是變量比如order.status.${status}這種寫法。這種風(fēng)格要盡量避免因為維護困難翻譯的人不知道這個key可能有哪些值測試也覆蓋不全。正確的做法是把所有狀態(tài)列出來在語言包中平鋪寫出寧可顯式寫五個key也別“聰明”地拼一個動態(tài)key。3.4 靜態(tài)提取與自動檢查別讓人工翻譯成為瓶頸文案寫得規(guī)范英文翻譯的質(zhì)量就不會差但項目大了以后人工翻譯跟不上開發(fā)速度是必然。這時候工具鏈就派上用場了。我常用的是一個“提取-對齊-校驗”三件套流程。構(gòu)建時自動掃描代碼中所有調(diào)用t()和$t()的位置收集第一個參數(shù)中的key和語言包中的key做對比。缺失的key輸出警告多余的key輸出提醒。這個流程雖簡單但能保證“提交代碼時語言包基本是齊的”。翻譯本身可以用現(xiàn)成的翻譯API做初稿再人工校對。不過要小心機器翻譯在專業(yè)術(shù)語上經(jīng)常翻得不準(zhǔn)比如“提現(xiàn)”“風(fēng)控”“權(quán)益”這類詞機器很可能翻譯成字面意思離業(yè)務(wù)本意差遠(yuǎn)了。初審之外的終審必須由熟悉業(yè)務(wù)的人來做。4. 上線后最容易翻車的幾個問題排查思路與避坑實錄4.1 問題一某些頁面切換語言后沒反應(yīng)排查順序有講究。先看控制臺有沒有報錯多半是語言包加載失敗key找不到。再看網(wǎng)絡(luò)面板里語言包資源有沒有真的發(fā)請求沒發(fā)就是懶加載邏輯里loadedLocales的狀態(tài)更新出了問題。如果頁面局部沒反應(yīng)重點檢查組件是不是沒有綁定當(dāng)前語言這個響應(yīng)式依賴。比如你在setup里解構(gòu)了t但使用的是普通變量而不是computed切換后組件不會重新渲染。這個屬于響應(yīng)式依賴丟失問題記住一個原則所有跟語言相關(guān)的派生狀態(tài)都要用computed包一層。4.2 問題二日期組件、富文本組件語言跟主體不一致第三方組件沒跟隨語言切換通常是因為組件內(nèi)部有自己的國際化管理掛在全局的locale上。排查時先確認(rèn)組件文檔里屬性名稱然后創(chuàng)建一個統(tǒng)一的管理器在切換語言時同步更新所有已注冊組件的locale。我一個項目里同時接了日期組件、富文本編輯器、代碼高亮它們各有各的語言包切換邏輯各不相同。后來寫了一個syncComponentLocale函數(shù)在語言切換流程里逐個調(diào)用每個組件實例的更新方法。這個函數(shù)名字聽起來土但確實管用。4.3 問題三動態(tài)內(nèi)容里的時間還是舊格式或貨幣符號錯亂這個跟響應(yīng)式有關(guān)系但本質(zhì)是“格式化函數(shù)的執(zhí)行時機”問題。如果你在組件初始化時把時間字符串格式化好了存成普通變量語言切換后這個字符串不會重新計算。務(wù)必把格式化放到渲染期或者用computed包裹。貨幣符號錯亂的情景常見于金額數(shù)據(jù)在接口層被處理成字符串返回前端拿不到數(shù)字也就沒法做Intl.NumberFormat。后來我們約定后端一律返回數(shù)字前端負(fù)責(zé)格式化徹底根治了這個隱患。4.4 避坑經(jīng)驗搭建一個“翻譯檢查面板”比一百次口頭強調(diào)都管用最后一個建議聽起來有點“重”但收益不小。在內(nèi)部開發(fā)環(huán)境里我習(xí)慣做一個隱藏的翻譯檢查面板把所有語言包缺失的key、未翻譯的條目、格式可疑的值匯總成列表按頁面展示。測試同學(xué)在驗證功能時順手打開面板瞄一眼幾秒鐘就能發(fā)現(xiàn)有沒有漏翻譯的文案比事后翻截圖高效太多。做法也不復(fù)雜攔截所有翻譯調(diào)用的返回結(jié)果如果發(fā)現(xiàn)返回的字符串里還含有{或}就判定為key缺失把信息推送到面板上。理論上這不難難的是堅持做。但說實話就靠這個面板我們有一次趕上線日程時在測試環(huán)境里提前攔截了二十多個漏翻的key避免了一場線上事故。5. 交互體驗與性能優(yōu)化的幾個加分項5.1 骨架屏和加載狀態(tài)里語言也要跟著變很多團隊只注重完整頁面的語言切換卻忽略了加載態(tài)和異常態(tài)。用戶切換語言后骨架屏上的占位文字還停留在舊語言這種不一致最容易被人截圖挑刺。骨架屏文案也要從語言包里取同時要保證切換語言的瞬間骨架屏立即刷新。這需要在模板里把骨架屏用到的文案同樣定義為響應(yīng)式依賴。5.2 按需加載與緩存策略語言包不該成為首屏負(fù)擔(dān)國際化不是“把所有語言都掛在首屏資源里”而是“用戶需要什么語言就提供什么語言”。首屏只加載當(dāng)前語言的必要模塊其他語言模塊等用戶切換時再異步加載。這本身就是最基礎(chǔ)也最有效的優(yōu)化。加上緩存策略后效果更好。語言包變更頻率低非常適合給一份強緩存同步更新時用構(gòu)建hash或版本號做資源更新。曾經(jīng)有段時間我們某個語言包沒加版本號導(dǎo)致用戶改了偏好語言后依然拉取舊緩存頁面上一半新文案一半舊文案排查了半天才發(fā)現(xiàn)是緩存問題。現(xiàn)在語言包文件名里帶上內(nèi)容hash這個問題再沒出現(xiàn)過。5.3 從“地道翻譯”到“本地化”語言背后的文化適配“翻譯”和“本地化”是兩件事。真正好的國際化不只是把中文換成英文還要考慮當(dāng)?shù)氐奈幕?xí)慣。比如日期是“2024年1月5日”這樣的表達習(xí)慣還是“1/5/2024”數(shù)字是十進制的千分位格式還是某些國家習(xí)慣用空格分隔首字母大小寫規(guī)則、標(biāo)點符號、地址書寫順序……這些細(xì)節(jié)靠翻譯工具搞不定需要各個國家地區(qū)的真實使用場景來反推。如果你的產(chǎn)品將來要出海建議早一點找到目標(biāo)市場的用戶做語言包評審而不是等上線后讓用戶幫忙“找茬”。6. 寫在最后國際化不是一次改造而是一套持續(xù)運轉(zhuǎn)的機制做國際化改造代碼層面的工作量大概只占四成剩下六成都花在流程和方法論上。語言包的維護不是上線那天結(jié)束而是從那天才開始。后續(xù)每個迭代都可能新增文案每個文案都可能漏翻譯每個翻譯都可能不地道。所以關(guān)鍵不是上線那天的狀態(tài)而是你有沒有建立一套讓語言包“持續(xù)被維護”的機制——比如代碼審查里的文案檢查、構(gòu)建時的key對齊校驗、測試環(huán)境的翻譯面板。按我個人的經(jīng)驗先用一個小模塊試點把語言包結(jié)構(gòu)、命名規(guī)范、運行時切換流程跑通再推廣到全項目。別一上來就全面鋪開不然光是排查歷史遺留文案就夠你消耗掉所有精力。希望這套CodeSpirit的國際化實踐能讓你在改造路上少踩幾個坑。