Dashy 多语言国际化（i18n）完整指南：语言切换、新语种接入与组件文案翻译
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），仅供参考