前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载useI18n()是 OpenPencil Vue SDKopen-pencil/vue提供的一个兼容聚合型组合式函数它一次性返回全部产品域menu、settings、tools、panels 等的响应式翻译消息组以及活动语言、可用语言列表与切换语言的控制函数。本文围绕 useI18n 官方文档 展开结合 i18n 源码实现 讲解其返回结构、底层语言状态管理与懒加载机制并给出一个无需复制任何翻译目录即可工作的自定义语言选择器组件。读完本文你将掌握在 OpenPencil 宿主应用中读取本地化 UI 消息、按需订阅指定语言域、以及用原生语言元数据构建个性化语言切换器的完整方案。一、useI18n 是什么兼容聚合体与产品域组合式函数useI18n()提供活动语言active locale、翻译消息与面向菜单、命令、工具、面板、页面和窗口的标签可以让你在不复制翻译目录的前提下创建自定义语言选择器。在源码层面它被明确标注为「兼容聚合体」/** Compatibility aggregate. New code should import the narrow domain composable. */ export function useI18n() { return { ai: useAIMessages(), automation: useAutomationMessages(), ... locale: useStore(locale) as RefLocale, availableLocales: AVAILABLE_LOCALES, localeLabels: LOCALE_LABELS, setLocale } }见 packages/vue/src/i18n/useI18n.ts关键设计原则是新组件应当只导入自己需要的产品域组合式函数而不是订阅每一个翻译目录。这既能减少响应式订阅范围也便于按需加载对应语言的 JSON 目录详见第五节。每个域组合式函数返回一个响应式 refimport { useSettingsMessages, useRenameMessages } from open-pencil/vue const settings useSettingsMessages() const rename useRenameMessages()在script中读取时使用.value在模板中 Vue 会自动解包unwrapsref。二、返回结构24 个翻译 ref 与 4 个语言控制项useI18n()的完整返回结构分为两类翻译 refTranslation refs共 24 个产品域ai、automation、code、collaboration、commands、common、credentials、diagnostics、editor、files、fonts、media、menu、pages、panels、recovery、rendering、rename、settings、storage、tools、updates、variables、variableTypes。语言控制Locale controls共 4 个locale当前活动语言响应式availableLocales可用语言代码列表localeLabels语言代码 → 本地化显示名的映射setLocale(code)切换语言该列表与 useI18n.ts 源码 中的返回对象一一对应也印证了文档中「menu、commands、panels、pages 等标签均来自这些域」的描述。从源码结构看packages/vue/src/i18n/messages.ts每个域还有配套的xxxMessageDefaults默认消息对象作为英文基准目录被nanostores/i18n用于合并翻译 JSON。注意dialogs 组已移除开发版v0.14.0 之后中原先的dialogs组、useDialogMessages()和dialogMessages已被移除。请改用其所属域如settings、rename、recovery并同步更新对应的消息键。当前 messages.ts 中确实已不存在任何dialogs导出与文档说明一致。三、底层实现useI18nNamespace 与 nanostores 桥接聚合体的每个消息域本质上是useI18nNamespace的调用结果其实现仅一行export function useI18nNamespaceMessagesStore extends Store(messages: MessagesStore) { return useStore(messages) as RefStoreValueMessagesStore }见 packages/vue/src/i18n/useI18n.ts它借助nanostores/vue的useStore把 nanostores 的原子 store 转成 Vue 的Ref从而让语言切换时所有订阅了该 store 的组件自动响应式更新。整个 index.ts 导出清单 表明useI18n、24 个域组合式函数、i18n实例以及locale/localeSetting/setLocale/AVAILABLE_LOCALES/LOCALE_LABELS等语言原语全部对外导出。四、实战不复制目录的自定义语言选择器文档给出的基础示例用useI18n()直接构建一个下拉语言选择器script setup langts import { useI18n } from open-pencil/vue const { menu, locale, availableLocales, localeLabels, setLocale } useI18n() /script template label classflex items-center gap-2 span{{ menu.view }}/span select :valuelocale changesetLocale(($event.target as HTMLSelectElement).value as typeof locale) option v-forcode in availableLocales :keycode :valuecode {{ localeLabels[code] }} /option /select /label /template要点拆解不复制目录availableLocales与localeLabels直接来自 SDK 的语言元数据因此无需维护任何重复的语言清单或显示名表响应式切换locale是响应式 refsetLocale更新后模板中的menu.view等所有消息组会一起刷新文档 Notes 中的第一条「locale changes are reactive across all SDK message groups」类型安全(typeof locale)限定 select 的取值类型只能传入Locale联合类型中的合法代码。如果只想读取菜单标签而不订阅全部 24 个域可以改用useMenuMessages()订阅范围更小、更符合 SDK 的推荐用法。五、语言状态底层locale.ts 中的持久化与浏览器解析useI18n()返回的locale/availableLocales/localeLabels/setLocale全部来自 packages/vue/src/i18n/locale.ts可用语言第 4 行[en, de, es, fr, it, ja, pl, ru, zh-CN]共 9 种其中除en外的 8 种为翻译语言TRANSLATED_LOCALES显示标签第 30-40 行LOCALE_LABELS给出每种语言的原生显示名如zh-CN: 中文简体、ja: 日本語持久化偏好localeSetting是一个 nanostores atomsetLocale(code)同时写入该 store 与localStorage键名open-pencil-locale启动恢复模块加载时会从localStorage读取已保存的语言并校验其是否属于AVAILABLE_LOCALES非法值会被忽略浏览器语言解析resolveBrowserLocale按navigator.languages顺序精确匹配语言代码匹配失败时退回匹配语言基名如pt-BR无法匹配时会尝试pt最后兜底en活动语言合成locale由localeFrom(localeSetting, browserLocale)合成——优先用户偏好否则使用浏览器语言。这些细节解释了文档 Notes 第二条「the SDK also exports lower-level locale primitives when you need direct store access」。如果你需要把语言状态接入更大的应用外壳或只想拿语言元数据而不订阅完整的useI18n()返回对象可直接从open-pencil/vue导入locale、localeSetting、setLocale、AVAILABLE_LOCALES、LOCALE_LABELS详见 SDK Locale APIs。六、懒加载翻译目录create.ts 中的按需导入useI18n()之所以能「不复制目录」即可切换语言底层依赖 packages/vue/src/i18n/create.ts 中基于nanostores/i18n的createI18n实例const localeLoaders { de: () import(#vue/i18n/locales/de), es: () import(#vue/i18n/locales/es), ... zh-CN: () import(#vue/i18n/locales/zh-cn) } satisfies RecordTranslatedLocale, () Promise{ default: ComponentsJSON } export const i18n createI18nLocale, en(locale, { baseLocale: en, async get(code) { if (code en) return {} const mod await localeLoaders[code]() return mod.default } })每个非英文语言通过动态import()懒加载对应语言目录locales/目录下按语言分文件组织共 200 个 JSON 与 8 个 TS 文件en作为baseLocale直接返回空对象、由xxxMessageDefaults兜底。这意味着切换语言时只拉取目标语言的 JSON同时默认消息与翻译消息在nanostores/i18n内部完成合并这正是useI18n()返回各域 ref 都能即时更新的机制基础。七、与相关 API 的关系useMenuModel需要读取菜单模型而非仅菜单文案时使用见 use-menu-modelSDK Locale APIs需要绕过聚合体、直接操作语言 store 或获取语言元数据时使用见 locale-apis域级组合式函数新组件应优先使用useSettingsMessages、useRenameMessages等单一域入口而不是useI18n()全量订阅。小结useI18n()是 OpenPencil Vue SDK 中读取本地化 UI 消息的入口聚合体它把 24 个产品域的响应式翻译 ref 与语言控制项locale、availableLocales、localeLabels、setLocale打包成一份开箱即用的返回对象。其底层由 nanostores store Vue ref 桥接useI18nNamespace、localStorage持久化与浏览器语言解析locale.ts、以及按语言懒加载 JSON 的nanostores/i18n实例create.ts共同支撑。对于新代码按产品域导入窄接口是更优实践对于需要自定义语言选择器或深度集成语言状态的场景本文给出的示例与底层原语足以覆盖从 UI 到存储层的完整链路。赞分享前端桌面应用AI 应用MCP 服务【免费下载链接】open-pencilAI-native design editor. Open-source Figma alternative.项目地址https://gitcode.com/gh_mirrors/op/open-pencil点击查看免费下载相关推荐OpenPencil Vue SDK 国际化指南useI18n 组合式函数与多语言切换实战OpenPencil Vue SDK 国际化指南useI18n 组合式函数与多语言切换实战 导读 useI18n 是 OpenPencilAI native前端桌面应用AI 应用MCP 服务OpenPencil Vue SDK 区域配置 APILocale APIs深入解析语言切换、回退机制与自定义消息目录OpenPencil Vue SDK 区域配置 APILocale APIs深入解析语言切换、回退机制与自定义消息目录 open pencil/vue前端桌面应用AI 应用MCP 服务Pyarmor本地化支持如何自定义错误消息和界面语言Pyarmor本地化支持如何自定义错误消息和界面语言 Pyarmor作为专业的Python代码混淆工具提供了强大的本地化支持功能让开发者能够自定义错误消息开发工具应用安全上一篇SharpCompress快速开始5分钟掌握压缩与解压核心操作下一篇如何快速制作专业EPUB电子书在线编辑器完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考