完整指南:語言切換、新語種接入與組件文案翻譯)
Dashy 多語言國際化i18n完整指南語言切換、新語種接入與組件文案翻譯【免費下載鏈接】dashy A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!項目地址: https://gitcode.com/GitHub_Trending/da/dashy本文基于 docs/multi-language-support.md 編寫并結合 src/utils/languages.js、src/utils/i18n.js、src/components/Settings/LanguageSwitcher.vue 與 tests/locales/check-locales.js 等源碼與測試文件進行深度印證與擴充。Dashy 是一款自托管的個人儀表盤天然面向全球用戶因此國際化Internationalization簡稱 i18n是它的核心基礎設施之一。本文圍繞 Dashy 的 vue-i18n 多語言方案完整講解三條主線普通用戶如何切換界面語言、貢獻者如何新增一種語言、開發者如何在新組件中接入可翻譯文案并深入源碼層面解析語言加載、優先級回退與翻譯覆蓋率校驗的底層實現。讀完本文你將能在自己的 Dashy 實例上切換語言也能獨立為 Dashy 提交一份完整、可被 CI 校驗通過的新語種翻譯并掌握在 Vue 組件中正確使用$t的規范。一、語言檢測與回退機制Dashy 默認會嘗試使用瀏覽器或操作系統的語言設置。如果該語言還沒有對應的翻譯文件則會自動回退到英語English。這一行為在 src/utils/i18n.js 中定義const i18n createI18n({ legacy: false, globalInjection: true, locale: defaultLanguage, // 默認語言 fallbackLocale: defaultLanguage, // 回退語言 messages: registered, });其中defaultLanguage來自 src/utils/config/defaults.js其默認值為en即英語既是默認語言也是回退語言。fallbackLocale保證了任何缺失的翻譯鍵都能落到英語而不會出現空白文案。legacy: false表示使用 vue-i18n 的 Composition API 模式globalInjection: true則允許在模板中直接使用全局注入的$t函數而無需在每個組件里手動引入。二、如何切換語言2.1 在 UI 中手動切換在 Dashy 界面的配置菜單Config Menu中點擊Language語言按鈕會打開語言選擇彈窗從下拉列表中選擇目標語言即可。你的選擇會被保存到瀏覽器的localStorage中下次打開 Dashy 時依然生效。從源碼 src/components/Settings/LanguageSwitcher.vue 可以看到完整的交互鏈路下拉列表由languages數組映射生成每項顯示為“國旗 emoji 語言名”friendlyName選擇語言并點擊保存按鈕后saveLanguage()會先通過checkLocale()確認語言在availableLocales中隨后調用loadLocale(code)動態加載對應的 JSON 翻譯文件并通過i18n.global.setLocaleMessage(code, msg)注冊到運行時最后把語言碼寫入localStorage.setItem(localStorageKeys.LANGUAGE, code)并關閉彈窗。2.2 通過配置文件設置你也可以在conf.yml配置文件中直接指定語言。在appConfig.language字段填入受支持語言的 ISO 代碼即可例如德語appConfig: language: de2.3 語言的解析優先級綜合 src/utils/config/ConfigHelpers.js 中的getUsersLanguage()實現語言的實際解析優先級為localStorage中保存的用戶手動選擇鍵名為language見 defaults.js配置文件config.appConfig.language內置默認值en。同時該函數還維護了一個legacyAliases兼容映射{ cn: zh-CN }即舊配置中寫cn的老用戶會被自動映射到簡體中文避免升級后語言設置失效。最終代碼會在 src/utils/languages.js 的languages數組中查找匹配項若找不到則返回undefined由上層回退處理。2.4 當前支持的語言列表以倉庫當前 src/utils/languages.js 為準Dashy 共注冊了以下 32 種語言/方言代碼、名稱、國旗語言代碼語言名稱語言代碼語言名稱enEnglishglGalegoen-GBEnglish (British)ruРусскийar???????roRomanabgБългарскиskSloven?inabn?????slSloven??inacs?e?tinasvSvenskadaDansktrTürk?edeDeutschukUkrainianelΕλληνικ?zh-CN簡體中文esEspa?olzh-TW繁體中文frFran?aiskyКыргызчаhi??????nbNorskhuMagyarnlNederlandsitItalianoplpolskija日本語ptPortuguêsko???zz-piratePirate語言代碼遵循 2 位 ISO-639 下的同名 JSON 文件例如de.json、zh-CN.json。三、如何添加一種新語言Dashy 使用 vue-i18n 管理多語言支持。添加新語言只需三步創建翻譯文件、翻譯內容、注冊到應用。3.1 第一步創建語言文件在 src/assets/locales/ 目錄下為你的語言新建一個 JSON 文件。標準語言使用 2 位 ISO-639 代碼命名例如德語de.json、法語fr.json、西班牙語es.json方言/地區語言使用帶后綴的 CLDR 格式命名例如en-GB.json英式英語、zh-CN.json簡體中文、zh-TW.json繁體中文。3.2 第二步翻譯內容以 src/assets/locales/en.json 為模板將 JSON 的**值value**翻譯成目標語言鍵key保持不變。某些條目可以留空不譯——缺失的鍵會自動回退到英語。特別注意翻譯值中如果出現花括號包裹的內容如{theme}、{name}花括號內的內容必須原樣保留因為這是 vue-i18n 的變量插值占位符運行時會被動態替換。以德語theme-maker段落為例{ theme-maker: { export-button: Benutzerdefinierte Variablen exportieren, reset-button: Stile zurücksetzen für, show-all-button: Alle Variablen anzeigen, save-button: Speichern, cancel-button: Abbrechen, saved-toast: {theme} Erfolgreich aktualisiert, reset-toast: Benutzerdefinierte Farben für {theme} entfernt }, }3.3 第三步注冊到應用在 src/utils/languages.js 的languages數組中追加你的語言元數據包含語言名稱、ISO 代碼和國旗 emojiexport const languages [ { name: English, code: en, flag: }, { name: German, code: de, flag: }, // 語言名稱、ISO 代碼與國旗 emoji ];注冊后翻譯文件會通過 src/utils/languages.js 中的import.meta.glob批量匹配加載const loaders import.meta.glob([ ../assets/locales/*.json, !../assets/locales/en.json, // 排除英語它作為默認與回退語言 ]); export const loadLocale async (code) { if (code en) return en; const loader loaders[../assets/locales/${code}.json]; if (!loader) throw new Error(Unsupported locale: ${code}); const mod await loader(); return mod.default; };也就是說只要 JSON 文件命名正確并放在locales/目錄、且被注冊進languages數組就會被 Vite 自動識別為可動態加載的語言包無需再改動其他構建配置。en.json被顯式排除出 glob因為它必須作為默認與回退語言提前同步注冊見 i18n.js 中“先注冊全部代碼、空對象回退英語”的預注冊邏輯。完成以上三步后還可以把你的新語言補充到倉庫根目錄 README.md 的 Language Switching 小節并可選署名以便為你的貢獻留檔。如果你不習慣提交 Pull Request也可以直接把翻譯好的文件交給維護者由維護者合并進應用。四、翻譯覆蓋率檢查yarn validate-localesDashy 內置了一個翻譯 lint/測試腳本用于驗證翻譯文件的完整性與合法性并輸出每種語言的覆蓋率報告yarn validate-locales該命令定義在 package.jsonvalidate-locales: node tests/locales/check-locales.js腳本本體位于 tests/locales/check-locales.js它會被 CI 在 Pull Request 時自動執行也是新增語言后必須通過的門禁。它會依次執行以下檢查失敗failure所有語言文件均已注冊、存在且可被正確解析為 JSON 對象根節點必須是對象非數組、非 null失敗failurelanguages.js中注冊了代碼但缺少對應 JSON 文件失敗failure存在 JSON 文件但未在languages.js中注冊失敗failure代碼中使用了en.json中不存在的翻譯鍵警告warnen.json中存在從未在代碼中被引用的冗余鍵警告warn其他語言包中存在en.json或代碼中都沒有用到的多余鍵覆蓋率報告其他語言相對en.json的翻譯完成度百分比按字母序逐行展示≥80% 為青色、≥50% 為黃色、更低為紅色100% 為綠色。腳本通過正則掃描 src 下所有.vue與.js文件中的$t、$tc、i18n.t、i18n.global.t調用將字面量鍵與動態前綴分別提取后與各語言包做交叉比對對于運行時拼接鍵名的動態調用如反引號模板字符串腳本會提取其靜態前綴進行前綴匹配無法靜態驗證的調用點也會在輸出中單獨列出提示。少數間接使用的鍵如 JsonEditor、AuthButtons、InitServiceWorker 中的動態鍵被維護在IGNORED_KEYS集合中以免誤報。一句話總結該腳本保證“英語是唯一真相源”——代碼里用到的鍵必須在en.json中存在而其他語言只要缺失鍵就會回退英語因此不強制 100% 翻譯但英語缺失就是硬錯誤。五、在新組件中添加可翻譯文案如果你正在開發一個新組件或發現某個舊組件遺漏了翻譯任何展示給用戶的文本都應從組件中抽離存放到語言文件中。得益于全局注入接入過程非常簡單。5.1 第一步在 en.json 中添加翻譯文本打開 src/assets/locales/en.json找到合適的段落或新建一個段落。假設新組件叫my-widget可以這樣組織my-widget: { awesome-text: I am some text, that will be seen by the user }必須為所有文本提供英語翻譯。其他語言的缺失不是問題會自動回退英語但英語缺失就意味著沒有任何內容可以展示。5.2 第二步在組件模板中使用 $t語言文件就緒后可在組件模板中通過全局$t函數傳入翻譯鍵來獲取對應文案p{{ $t(my-widget.awesome-text) }}/p這里的{{ }}是 Vue 的插值語法表示內部是 JavaScript/動態表達式。渲染結果為pI am some text, that will be seen by the user/p5.3 在 JavaScript 中程序化使用如果需要從組件腳本中程序化展示文案例如 toast 彈窗使用this.$talert(this.$t(my-widget.awesome-text))5.4 變量插值Interpolations當翻譯文案需要插入動態變量時vue-i18n 支持類似 mustache 的插值語法。先在語言文件中定義帶{變量名}占位符的文案{ welcome-message: Hello {name}! }然后在調用時把變量作為$t的第二個參數JSON 對象傳入$t(welcome-message, { name: Alicia })渲染結果Hello Alicia!這就是文檔 3.2 節中“花括號內內容必須保留”的原因——{theme}、{name}這類占位符正是插值變量。vue-i18n 還支持復數Pluralization、日期時間與數字格式化Datetime Number Formatting、消息格式Message Formatting等高級特性詳見 vue-i18n 官方指南。5.5 完整實例搜索欄組件以 src/components/Settings/SearchBar.vue 為范例模板中使用$t渲染標簽與占位符template form label forsearch-input{{ $t(search.search-label) }}/label input v-modelsearchValue :placeholder$t(search.search-placeholder) / /form /template對應的翻譯鍵定義在 src/assets/locales/en.json{ search: { search-label: Search, search-placeholder: Start typing to filter, clear-search-tooltip: Clear Search, enter-to-search-web: Press enter to search the web, enter-to-open-url: Press enter to open URL, enter-to-launch-first: Press enter to launch first match }, ... }注意該組件中searchNote會根據不同場景動態選擇search.enter-to-search-web/search.enter-to-open-url/search.enter-to-launch-first三個鍵見 SearchBar.vue這正是 5.4 節所述“動態前綴”類用法check-locales.js的靜態掃描會覆蓋此類調用。六、底層原理小結從源碼層面回看 Dashy 的多語言架構可以總結出三條核心設計單真相源Single Source of Truthen.json是所有語言的基準其他語言允許缺失并回退英語但英語鍵的缺失屬于硬失敗由validate-locales在 CI 中強制把關動態按需加載借助 Vite 的import.meta.globlanguages.js 只需維護一份languages元數據數組翻譯 JSON 即可被自動發現并按需懶加載見loadLocale英語則常駐內存三級優先級與兼容性用戶語言依次取 localStorage →appConfig.language→ 默認en并通過legacyAliasescn→zh-CN保證歷史配置平滑遷移全局注入的$t/this.$t讓組件內接入翻譯幾乎零成本。無論是終端用戶、翻譯貢獻者還是組件開發者都可以依據本文在 Dashy 中完成語言切換、新語種接入與文案國際化新增語言后務必運行yarn validate-locales通過覆蓋率與一致性檢查再提交 Pull Request 參與上游協作。【免費下載鏈接】dashy A self-hostable personal dashboard built for you. Includes status-checking, widgets, themes, icon packs, a UI editor and tons more!項目地址: https://gitcode.com/GitHub_Trending/da/dashy創作聲明:本文部分內容由AI輔助生成(AIGC),僅供參考