cube-ui 国际化完全指南：组件文案翻译与 Locale 应用级扩展

前端UI组件移动开发【免费下载链接】cube-ui:large_orange_diamond: A fantastic mobile ui lib implement by Vue项目地址https://gitcode.com/gh_mirrors/cu/cube-ui点击查看免费下载cube-ui 内部所有非可配置的文案默认均为中文从1.11.0版本开始国际化文档 正式引入Locale模块为组件内置文案提供翻译与动态切换能力1.12.23版本又进一步通过Locale.localeMixin将翻译能力延伸至你自己的应用组件。读完本文你将掌握 cube-ui 语言包的注册、切换与缓存机制理解{{config}}模板与校验器消息的渲染原理并能用$t方法为业务组件接入多语言。cube-ui 国际化能力概览在介绍用法之前先明确该特性解决的核心问题cube-ui 组件如 ActionSheet 的“取消/确认”、Select 的“请选择”、TimePicker 的“现在/今日”、Validator 的各类校验提示等内部文案以中文写死。当你的应用需要面向多语言用户时需要一种机制将这些文案替换为其他语言并且保证替换后组件依旧能根据当前语言自动渲染。该机制在两个层面生效组件级国际化1.11.0通过Locale.use()注册语言包并切换组件内文案随之变化且语言包会被缓存重复切换零额外开销应用级国际化1.12.23通过Locale.localeMixin向你的业务组件注入$t翻译函数让 cube-ui 的国际化能力直接服务你的应用文案。组件国际化的使用默认中文语言包与响应式语言状态cube-ui 默认使用中文语言包并且在Locale.install阶段自动完成注册。查看 src/common/locale/index.js 的实现可以看到默认行为const DEFAULT_LANG zh-CN const locale { name: locale, install (Vue) { if (locale.installed) return proto Vue.prototype Vue.util.defineReactive(proto, $cubeLang, DEFAULT_LANG) proto[$cubeMessages] { [DEFAULT_LANG]: defaultMessages } locale.installed true }, // ... }关键细节语言类型$cubeLang通过Vue.util.defineReactive定义为响应式属性因此当Locale.use()切换语言时所有依赖该属性的组件视图会自动更新默认语言包defaultMessages即 src/locale/lang/zh-CN.js在安装时已挂载到Vue.prototype.$cubeMessages上所以你无需任何初始化即可使用中文。切换至内置英文语言包cube-ui 内部已经内置了英文语言包 src/locale/lang/en-US.js你只需要两步即可完成切换import Vue from vue import { Locale } from cube-ui import enUSMessages from cube-ui/src/locale/lang/en-US Vue.use(Locale) // 切换至英语并且缓存当前语言包 Locale.use(en-US, enUSMessages)Vue.use(Locale)会调用install完成上述响应式初始化多次调用会被installed标志跳过Locale.use(en-US, enUSMessages)则负责切换语言并缓存语言包。语言包缓存与按需切换Locale.use的缓存逻辑位于 src/common/locale/index.jsuse (lang, messages) { proto[$cubeLang] lang const cubeMessages proto[$cubeMessages] // if messages have never been stored in vue.prototye if (!(lang in cubeMessages)) { cubeMessages[[lang]] messages } }可以看到只有首次使用某个语言时会存储对应的messages之后再次切换到该语言只需传入lang名称直接命中缓存。官方文档中的伪代码如下import Vue from vue import { Locale } from cube-ui import enUSMessages from cube-ui/src/locale/lang/en-US // 默认加载中文语言包 Vue.use(Locale) // 切换至英语并且需要导入英语语言包 one.click(() { Locale.use(en-US, enUSMessages) }) another.click(() { // 从缓存取之前的语言包无需再传入 messages Locale.use(zh-CN) })这种设计让语言切换变成纯粹的响应式赋值操作在用户反复切换语言时不会产生重复的模块加载成本。自定义语言包日、韩等如果内置的中英语言包不满足需求你可以提供自己的语言包对象并按同样的方式注册import Vue from vue import { Locale } from cube-ui import jPMessages from /somewhere/ja-JP.js // 自己的语言包 Vue.use(Locale) // 切换至日语并且需要导入日语语言包 Locale.use(ja-JP, jPMessages)语言包本身只是一个普通的 ES Module导出结构与内置语言包保持一致即可。语言包结构与校验器消息模板默认中文语言包的完整结构你自定义的语言包必须与 cube-ui 默认语言包的结构兼容组件内部会按 key 取值。默认中文语言包完整内容如下与 src/locale/lang/zh-CN.js 一致export default { cancel: 取消, confirm: 确认, ok: 确定, prev: 上一步, next: 下一步, selectText: 请选择, now: 现在, selectTime: 选择时间, today: 今日, formatDate: M月D日, hours: 点, minutes: 分, validator: { required: 此为必填项, type: { string: 请输入字符, number: 请输入数字, array: 数据类型应为数组, date: 请选择有效日期, email: 请输入有效邮箱, tel: 请输入有效的手机号码, url: 请输入有效网址 }, min: { string: 至少输入 {{config}} 位字符, number: 不得小于 {{config}}, array: 请选择至少 {{config}} 项, date: 请选择 {{config | toLocaleDateString(yyyy年MM月dd日)}} 之后的时间, email: 至少输入 {{config}} 位字符, tel: 至少输入 {{config}} 位字符, url: 至少输入 {{config}} 位字符 }, max: { string: 请勿超过 {{config}} 位字符, number: 请勿大于 {{config}}, array: 最多选择 {{config}} 项, date: 请选择 {{config | toLocaleDateString(yyyy年MM月dd日)}} 之前的时间, email: 请勿超过 {{config}} 位字符, tel: 请勿超过 {{config}} 位字符, url: 请勿超过 {{config}} 位字符 }, len: { string: 请输入 {{config}} 位字符, number: 长度应等于 {{config}}, array: 请选择 {{config}} 项, date: 请选择 {{config | toLocaleDateString(yyyy年MM月dd日)}} 之前的时间, email: 请输入 {{config}} 位字符, tel: 请输入 {{config}} 位字符, url: 请输入 {{config}} 位字符 }, pattern: 格式错误, custom: 未通过校验, notWhitespace: 空白内容无效 } }对照英文语言包 src/locale/lang/en-US.js 可以看到相同的 key 结构例如formatDate: M-D、hours: 这正是“结构兼容”的含义key 路径必须一致value 按语言自定义。{{config}} 占位符与 helper 函数渲染校验器文案中的{{config}}会在运行时被替换为校验参数如长度限制、最小值等而{{config | toLocaleDateString(yyyy年MM月dd日)}}这种写法表示将config作为输入经过toLocaleDateString函数处理后填入。渲染逻辑在 src/common/helpers/string-template.jsconst stringRE /\{\{((?:.|\n)?)\}\}/g function format (string, config ) { return string.replace(stringRE, (match, group1) { const helpersArr group1.split(|).slice(1).map(_ _.trim()) // ... 依次调用 helper 函数处理 config }) }模板内以|分隔出 helper 名称与参数最终从Locale.helpers中找到对应函数执行。内置的toLocaleDateString实现src/common/locale/index.js还做了 Safari 兼容处理将yyyy-MM-dd形式的日期字符串中的-替换为/再按传入的格式规则格式化。如果你需要新的格式化能力可以用Locale.addHelper(fnName, fn)注册自定义 helper重复注册同名函数会触发告警这也意味着语言包模板是可扩展的。应用级国际化1.12.23组件级国际化解决了 cube-ui 自身文案的问题而应用级国际化让你自己的业务文案也复用同一套语言切换机制。官方文档给出的接入过程分两步第一步导入包含 cube-ui 全集的语言包你的语言包应包含 cube-ui 默认语言包的全部 key作为子集再叠加你自己的应用文案。示例如下// default.js export default { application_key: 这是我应用的翻译, country: { province: 北京 }, /* cube-ui 的默认配置*/ cancel: Cancel, // ...忽略中间部分的配置 validator: { /* ... */ } }然后在应用入口文件导入并注册import Vue from vue import { Locale } from cube-ui import defaultMessages from default.js // 自己的语言包 Vue.use(Locale) Locale.use(zh-CN, defaultMessages)注意这里将应用自己的语言包以zh-CN名义注册覆盖默认注册的中文包。由于use()只在语言未缓存时写入入口处一次注册即可让组件文案与应用文案共用同一份数据。第二步通过 mixins 注入翻译能力cube-ui 提供了语言包key value的转换函数$t通过Locale.localeMixin注入到你的组件// dialog.vue import { Locale } from cube-ui script export default { // ... mixins: [Locale.localeMixin] // 注入 mixin拥有 $t 的能力1.12.23 版本新加 } /script接着即可在模板中直接使用template div {{$t(application_key)}} /div /template渲染结果为这是我应用的翻译。深层路径解析a.b.c考虑到语言包可能是多层级嵌套结构$t接受以.为分隔符的路径字符串来获取深层属性。例如语言包为export default { a: { b: { c: 嵌套的 c } } }模板中这样使用template div {{$t(a.b.c)}} /div /template$t的实现位于 src/common/mixins/locale.js其核心逻辑是读取当前响应式语言this.$cubeLang对应的语言包若未注册则告警并返回空串否则调用parsePath解析路径computed: { $t () { const lang this.$cubeLang const messages this.$cubeMessages[lang] if (isUndef(messages)) { warn(TRANSLATION_ABSENT) return } return (path) { return parsePath(messages, path) } } }parsePathsrc/common/helpers/util.js按.切分路径并逐层取属性中途遇到未定义的值会安全地返回空串避免渲染报错function parsePath (obj, path ) { const segments path.split(.) let result obj for (let i 0; i segments.length; i) { const key segments[i] if (isUndef(result[key])) { result break } else { result result[key] } } return result }值得注意的实现细节$t是一个 computed 属性它返回一个闭包函数而该闭包读取的是响应式的$cubeLang与$cubeMessages因此切换语言后模板中的$t(...)调用结果会自动刷新无需手动重新渲染。组件内部对语言包的消费方式为了让自定义语言包真正生效理解组件如何消费这些 key 很有帮助。以 src/components/action-sheet/action-sheet.vue 为例return this.cancelTxt || this.$t(cancel)组件优先使用用户通过 props 传入的自定义文案如cancelTxt未传入时才回退到$t取语言包文案。同样的模式出现在src/components/select/select.vue占位符selectText、标题、取消/确定按钮支持placeholder、title等 prop 优先src/components/segment-picker/segment-picker.vuenext/prev上一步/下一步src/components/time-picker/time-picker.vueselectTime、today、formatDate、now、hours、minutessrc/components/validator/validator.vue通过localeMixin与$cubeLang/$cubeMessages完成校验消息的国际化渲染见 validator.vue 第 35 行及第 273-274 行。这种“prop 优先、语言包兜底”的设计保证了在未接入 Locale 时组件依然可用接入后又能获得完整的国际化能力。总结与接入清单接入 cube-ui 国际化只需记住三件事组件文案Vue.use(Locale)之后用Locale.use(lang, messages)注册并切换语言包内置zh-CN与en-US其他语言自备语言包应用文案在入口用包含 cube-ui 全集 key 的语言包注册在业务组件mixins: [Locale.localeMixin]模板中$t(a.b.c)取值模板扩展语言包中可用{{config}}占位符与| helperName(args)语法需要新格式化函数时通过Locale.addHelper注册。相关的语言包定义、核心实现与消费组件都可以在当前仓库中直接查阅默认中文语言包、内置英文语言包、Locale 核心实现、localeMixin 与 $t以及 国际化官方文档。赞分享前端UI组件移动开发【免费下载链接】cube-ui:large_orange_diamond: A fantastic mobile ui lib implement by Vue项目地址https://gitcode.com/gh_mirrors/cu/cube-ui点击查看免费下载相关推荐yargs国际化完全指南掌握locale文件结构与扩展方法打造多语言CLI应用 yargs国际化完全指南掌握locale文件结构与扩展方法打造多语言CLI应用 yargs是一个强大的Node.js命令行参数解析库它内置了完整的CLI开发工具Bash-stack快速入门教程如何在3步内创建你的第一个Web应用Bash stack快速入门教程如何在3步内创建你的第一个Web应用 你是否想过用简单的Bash脚本就能构建现代Web应用今天我要向你介绍一个神奇的工具——docker-stacks中的JupyterLab扩展国际化文档翻译指南docker stacks中的JupyterLab扩展国际化文档翻译指南 在当今全球化的环境中为JupyterLab扩展提供多语言支持变得越来越重要。本指南云原生开发工具数据科学上一篇JabRef浏览器扩展使用教程一键导入参考文献到你的文献库下一篇Netgear路由器远程管理终极指南5分钟搞定隐藏Telnet功能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考