uni-app x 插件多语言支持指南基于 uni-app 国际化与 HBuilderX 插件国际化双规范【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app插件支持多语言是插件作者在面向全球开发者发布插件时必须处理的能力。uni-app x 的插件多语言机制并非独立发明而是基于两套既有规范延伸而来面向uni-app/uniCloud类型插件的应用层国际化vue-i18n 与 locale 语言文件体系以及面向 HBuilderX 扩展插件的package.nls语言包规范。本文以 docs/plugin/language.md 为核心骨架结合仓库内的国际化专题文档 docs/i18n.md 与示例工程 examples/hello-uvue 的源码实现系统讲解两类插件的多语言配置方法、语言文件组织方式、语言标签规范及仓库级可运行示例帮助插件作者为自己的插件接入完整的国际化能力。一、插件多语言的两大规范体系uni-app x 的插件生态包含多种类型前端组件、uts 插件、页面模板、项目模板等详见 插件全景描述不同类型的插件对多语言的处理方式不同。官方将插件多语言规范划分为两个分支| 插件分类 | 规范依据 | 多语言文件形态 | | - | - | - | | uni-app 及 uniCloud 分类插件 | uni-app 应用级国际化规范 | 项目内locale/目录语言 json vue-i18n | | HBuilderX 分类插件 | HBuilderX 插件国际化规范 | 插件根目录package.nls.[语言代码].json|判断插件属于哪一类取决于插件最终被安装、运行的宿主环境若插件是运行在 uni-app x 应用内部的功能模块如 uni_modules 组件、uts 插件、页面模板其界面文字属于宿主应用的一部分应遵循uni-app 应用级国际化规范与宿主应用共用locale语言文件与 vue-i18n 运行时若插件是 HBuilderX 编辑器扩展提供菜单、命令、面板等编辑器内能力应遵循HBuilderX 插件国际化规范通过package.nls语言包随插件打包分发。下文分别对两套规范展开讲解。二、uni-app / uniCloud 分类插件应用级国际化对于这类插件官方文档明确指向 uni-app 的国际化专题对应仓库文档 docs/i18n.md。uni-app x 的国际化分为两种场景固定一种外语直接在代码里写死目标语言无需额外机制动态切换语言内置多种语言根据条件在运行时切换需要引入 vue-i18n 与 locale 语言文件体系。同时要区分两套国际化对象开发者代码插件/应用自身界面与uni-app x 框架内置组件和 API如uni.showModal的按钮文字。2.1 开发者代码的国际化vue-i18n locale 语言文件从 HBuilderX 5.25 起uni-app x 项目内置的vue-i18n升级到11.4.6版本如需使用其他版本可在项目根目录自行安装。APP 蒸汽模式、鸿蒙和 iOS VDOM 模式、Web 平台、小程序平台可直接使用内置的 vue-i18n 官方库Android VDOM 模式官方推荐使用 lime-i18n 插件解决动态语言切换。第一步创建 locale 目录与语言文件在项目根目录创建locale目录按语言标签放置语言文件├── locale │ ├── en.json │ ├── zh-Hans.json │ └── zh-Hant.json ├── i18n.uts └── main.uts语言文件内容示例以简体中文为例{ i18n.title: 国际化, i18n.description: 使用 vue-i18n 切换页面语言, i18n.currentLocale: 当前语言, i18n.greeting: 你好uni-app x, i18n.named: 欢迎使用 {framework}, i18n.switchToZhHans: 简体中文, i18n.switchToZhHant: 繁体中文, i18n.switchToEn: English }仓库示例工程 examples/hello-uvue/locale/zh-Hans.json、examples/hello-uvue/locale/zh-Hant.json、examples/hello-uvue/locale/en.json 提供了完整的三语对照实现其中命名参数{framework}的用法在英文、繁体、简体文件中保持一致便于运行时替换。第二步初始化 vue-i18n在i18n.uts中创建 i18n 实例并注册各语言消息。仓库示例 examples/hello-uvue/i18n.uts 的实现如下import { createI18n } from vue-i18n import en from ./locale/en.json import zhHans from ./locale/zh-Hans.json import zhHant from ./locale/zh-Hant.json export const i18n createI18n({ legacy: false, locale: zh-Hans, fallbackLocale: en, messages: { en, zh-Hans: zhHans, zh-Hant: zhHant } })关键配置说明legacy: false使用 Composition API 模式locale: zh-Hans默认语言应用启动时展示的语言fallbackLocale: en回退语言当某语言缺少某个 key 时自动回退到英文避免界面出现空文本messages注册的语言消息映射key 必须与 locale 目录中的语言标签一致。第三步在 main.uts 挂载 i18nimport App from ./App.uvue import { createSSRApp } from vue import { i18n } from ./i18n.uts export function createApp() { const app createSSRApp(App) app.use(i18n) return { app } }第四步页面中使用 t() 与 locale页面脚本中通过useI18n()获取t翻译函数与locale响应式语言对象模板中调用t()渲染对应语言内容。仓库示例页面 examples/hello-uvue/pages/i18n/i18n.uvue 展示了完整的模板与脚本写法template view classpage text classtitle{{ t(i18n.title) }}/text text classdescription{{ t(i18n.description) }}/text text classlocale-label{{ t(i18n.currentLocale) }}: {{ locale }}/text text classmessage greeting{{ t(i18n.greeting) }}/text text classmessage named{{ t(i18n.named, { framework: uni-app x } as UTSJSONObject) }}/text button clickchangeLocale(zh-Hans){{ t(i18n.switchToZhHans) }}/button button clickchangeLocale(zh-Hant){{ t(i18n.switchToZhHant) }}/button button clickchangeLocale(en){{ t(i18n.switchToEn) }}/button /view /template script setup languts import { useI18n } from vue-i18n const { t, locale } useI18n() const syncLocale (newLocale : string) { locale.value newLocale } // #ifdef WEB || MP-WEIXIN uni.onLocaleChange((res : UniNamespace.OnLocaleChangeCallbackResult) { if (res.locale ! null) { syncLocale(res.locale!) } }) // #endif const changeLocale (newLocale : string) { // #ifdef WEB || MP-WEIXIN uni.setLocale(newLocale) // #endif syncLocale(newLocale) } /script该页面代码还揭示了两个重要细节带参数翻译t(i18n.named, { framework: uni-app x } as UTSJSONObject)演示了命名参数插值{framework}占位符会被替换为传入的值平台条件编译uni.setLocale/uni.onLocaleChange仅在 Web 与微信小程序平台可用因此在代码中用// #ifdef WEB || MP-WEIXIN包裹其他平台通过直接修改locale.value完成语言切换这正是 uni-app x 条件编译处理跨平台差异的标准姿势。2.2 pages.json 的国际化注意App 平台的 pages.json 暂不支持通过配置语言 json 文件实现国际化目前可暂时通过 tabbar 和 navigationBar 的 API 来设置文字。Web 平台额外支持 pages.json 国际化。在项目根目录locale目录下配置语言 json 文件locale/[语言标签].json然后在 pages.json 中通过%key%占位符引用语言文件示例zh-Hans.json{ app.name: Hello uni-app, index.title: 首页 }pages.json 示例{ pages: [ { path: pages/index/index, style: { navigationBarTitleText: %index.title% } } ], tabBar: { list: [{ pagePath: pages/index/index, text: %index.home% } ] } }pages.json 中支持国际化配置的属性目前包括navigationBarTitleTexttabBar - list - text2.3 manifest.json 的国际化适用版本HBuilderX 5.0 及以上版本app-android / app-ios 平台云端打包和 app-harmony 平台本地打包支持设置国际化。manifest.json 的国际化方式与 pages.json 相同在项目根目录locale目录下配置语言 json 文件。应用名称的国际化在 manifest.json 可视化界面的应用名称中配置为%app.name%或源码视图中配置{ name: %app.name%, app.ios.des.camera: 拍照功能需要使用摄像头 }配置后需提交云端打包生效。注意app-android、app-ios 平台离线打包需在原生工程中配置应用的国际化名称。app-ios 平台隐私信息许可描述也可国际化。在可视化界面 iOS App 配置 的 隐私信息访问的许可描述 对应项如摄像头NSCameraUsageDescription配置为%app.ios.des.camera%或源码视图配置{ app-ios: { distribute: { privacyDescription: { NSCameraUsageDescription: %app.ios.des.camera% } } } }同样需提交云端打包生效。注意app-ios 平台暂不支持 Info.plist 中其他信息的国际化有此特殊需求时离线打包可在原生 Xcode 工程中配置。2.4 uniCloud DB Schema 的国际化uniCloud 的 DB Schema 中涉及的字段显示名称、错误格式提示语同样需要国际化。在项目根目录uniCloud/database/locale/{数据库表名}/[语言标签].json放置语言文件然后在*.schema.json文件中使用%占位├─uniCloud │ ├─cloudfunctions │ └─database │ │ hello.schema.json │ └─locale │ └─hello │ en.json │ zh-Hans.jsonhello.schema.json 文件内容{ bsonType: object, required: [], permission: { read: false, create: false, update: false, delete: false }, properties: { _id: { description: ID }, name: { bsonType: string, label: %name%, errorMessage: { format: {label}%name.format% } } } }en.json 文件内容{ name: Name, name.format: invalid format }zh-Hans.json 文件内容{ name: 姓名, name.format: 格式无效 }label与errorMessage中的占位符会在数据库管理端、表单校验提示中按当前语言环境被替换为对应文案。2.5 框架内置组件与 API 的国际化uni-app x 的部分组件和 API 涉及界面框架内置支持的国际化语言会在手机 OS 或浏览器语言命中时自适应若设备语言不在内置列表内则默认使用英文。各平台内置语言支持情况app-Android 平台中文简体、中文繁体、英语、法语HBuilderX 4.25 及以上、西班牙语HBuilderX 4.25 及以上app-iOS 平台中文简体、中文繁体HBuilderX 4.25 及以上、英语HBuilderX 4.25 及以上、法语HBuilderX 4.25 及以上、西班牙语HBuilderX 4.25 及以上web 平台中文简体、中文繁体、英语、法语、西班牙语涉及界面的组件和 API 包括uni.showModal默认的确定和取消按钮文字会根据 OS 和浏览器语言自适应也可通过参数自行指定文字uni.showActionSheet取消按钮文字会根据 OS 和浏览器语言自适应uni.chooseImage、uni.chooseVideoapp 平台弹出的拍摄和从相册选择的 actionsheet 方式选择框文字不支持国际化但可设置sourceType参数为单项、自行弹出选择框处理。拍摄打开的是系统相机界面在 app 平台跟随系统语言从相册选择分系统相册跟随手机 OS 语言和自定义相册可随 uni-app x 内置国际化语言列表配置小程序这部分国际化大多跟随小程序宿主语言uni.chooseMediaapp 平台弹出系统媒体选择界面使用当前系统语言。2.6 语言获取与切换 APIuni-app x 可通过如下 API 获取 OS、浏览器或应用的语言uni.getSystemInfouni.getDeviceInfouni.getDeviceInfo().osLanguage获取 OS 语言uni.getAppBaseInfouni.getAppBaseInfo().appLanguage获取应用语言uni.getAppBaseInfo().hostLanguage获取宿主语言Web 平台还支持uni.setLocale设置应用语言与uni.onLocaleChange应用语言变化时触发回调即uni.setLocale执行时。需要强调的是Web 平台要区分系统语言与应用语言两个概念应用语言由uni.setLocale控制系统语言来自浏览器环境。三、HBuilderX 分类插件package.nls 语言包规范HBuilderX 扩展插件遵循 HBuilderX 插件国际化规范通过插件根目录下的package.nls.[语言代码].json文件进行识别。以插件除默认语言外还支持英语和日语为例插件包需要包含如下文件插件根目录 ├── package.json ├── package.nls.en.json ├── package.nls.json └── package.nls.ja.json文件命名规则与作用| 文件 | 作用 | | - | - | |package.nls.json| 默认语言通常是中文的语言包 | |package.nls.en.json| 英语语言包 | |package.nls.ja.json| 日语语言包 |其中package.nls.json是必选项作为无匹配语言时的回退其他语言的package.nls.[语言代码].json按需添加。语言代码必须符合规范即遵循 BCP 47 语言标签规范详见下文第四节插件作者应根据目标市场覆盖的语言范围决定提供哪些语言包。四、语言标签规范BCP 47无论 uni-app 分类还是 HBuilderX 分类插件语言代码都必须符合 BCP 47 规范。语言标签由一个或多个子标签subtags组成用连字号-分隔子标签只能由基本拉丁字母或数字组成语言代码通常为两个或三个字母参考 ISO 639 规范地区代码两个字母位于语言代码之后参考 ISO 3166-2 规范。常见语言标签示例| 标签 | 含义 | 使用场景 | | - | - | - | | zh | 中文泛指 | 通用中文内容 | | zh-Hans | 简体中文 | 简体文本不指定地区 | | zh-Hans-SG | 中文简体新加坡 | 新加坡简体中文 | | zh-Hant | 繁体中文 | 繁体文本不指定地区 | | zh-Hant-HK | 中文繁体香港 | 香港繁体中文 | | zh-Hant-TW | 中文繁体台湾 | 台湾繁体中文 | | en | 英文 | - | | en-US | 英文美国 | - |在 uni-app 分类插件中这些标签直接作为locale目录下语言 json 文件的文件名如en.json、zh-Hans.json同时也是 vue-i18nmessages的 key在 HBuilderX 分类插件中则作为package.nls.[标签].json的文件名后缀。五、仓库示例hello-uvue 完整国际化实现仓库示例工程 examples/hello-uvue 提供了插件/应用国际化可直接参考的完整实现包含以下关键文件| 文件 | 职责 | | - | - | | examples/hello-uvue/i18n.uts | 创建 vue-i18n 实例注册 en / zh-Hans / zh-Hant 三语消息 | | examples/hello-uvue/locale/en.json | 英文语言包 | | examples/hello-uvue/locale/zh-Hans.json | 简体中文语言包 | | examples/hello-uvue/locale/zh-Hant.json | 繁体中文语言包 | | examples/hello-uvue/pages/i18n/i18n.uvue | 国际化演示页面t() 渲染、命名参数、语言切换、平台条件编译 |该示例可直接作为 uni-app / uniCloud 分类插件作者接入多语言的脚手架复制locale目录与i18n.uts在main.uts中app.use(i18n)完成挂载即可在插件各页面通过useI18n()使用翻译能力。六、插件作者多语言最佳实践小结先判断插件分类运行在 uni-app x 应用内的插件走应用级国际化locale vue-i18nHBuilderX 编辑器扩展走package.nls语言包规范两者不可混用语言文件命名严格遵循语言标签规范BCP 47zh-Hans与zh-Hant是简繁中文的标准写法地区变体如zh-Hant-HK按需细分始终配置 fallbackLocalevue-i18n 中设置回退语言如en避免某语言 key 缺失时界面出现空文本区分应用语言与系统语言Web 平台通过uni.setLocale/uni.onLocaleChange控制应用语言通过uni.getDeviceInfo().osLanguage、uni.getAppBaseInfo().appLanguage等 API 读取语言环境参见 docs/api/get-device-info.md 与 docs/api/get-app-base-info.md善用条件编译跨平台差异 API如uni.setLocale仅 Web / 小程序可用用// #ifdef指令隔离保证各平台编译通过框架内置界面尽量依赖自适应uni.showModal、uni.showActionSheet等按钮文字会跟随系统语言自适应插件作者只需关注自身界面文案的国际化即可。通过上述两条规范与仓库内可直接运行的示例插件作者可以低成本地为自己的 uni-app x 插件、uniCloud 扩展或 HBuilderX 扩展接入完整的多语言能力从而覆盖更广泛的开发者市场。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考