多语言

jzfw-ui 内置 zh-cn / zh-tw / en / ja / ko / fr / es 七语种词典。源语言为简体中文，词典 key 即中文原文；未命中时 t() 原样返回 key，因此中文环境无需维护 value。

API

import {
  locale, defaultLocale,
  t, $t,
  setLocale, getLocale, normalizeLocale,
  registerLocale, initLocale
} from "@/uni_modules/jzfw-ui";

名称	签名	说明
locale	Ref<string>	当前语言代码，空串表示尚未确定
defaultLocale	Ref<string>	默认语言，系统语言无法识别时回退（默认 zh-cn）
t	(name: string) => string	翻译文案，未命中词典时原样返回 key
$t	(name: string, data: UTSJSONObject) => string	带占位符替换的翻译，data 的键替换文案里的 {key}
setLocale	(value: string) => void	设置语言并持久化（存储键 jzfw-locale）
getLocale	() => string	获取当前语言，优先级：内存 > 持久化 > 系统 > 默认
normalizeLocale	(code: string) => string	归一化语言代码（zh-Hans/en-US… → 内置 7 码）
registerLocale	(code: string, items: string[][]) => void	注册 / 覆盖某语言词典
initLocale	(value?: string) => void	初始化语言，建议在 onLaunch 调用一次

基本用法

setLocale("en");
t("暂无数据");   // 英文环境返回 "No data available"

模板中：

<jz-text :value="t('你好')"></jz-text>

带占位符翻译

$t 会替换文案里的 {key} 占位符：

$t("欢迎回来，{name}", { name: "Jzfw" } as UTSJSONObject);
// → "欢迎回来，Jzfw"

$t("最多输入{maxlength}位", { maxlength: 6 } as UTSJSONObject);
// → "最多输入6位"

注意：非原生 App 端模板表达式编译后是纯 JS 对象，$t 内部已对其做 JSON 归一处理，无需手动转换；但在脚本中传入字面量时建议写 as UTSJSONObject。

扩充 / 覆盖词条

// 覆盖英文文案
registerLocale("en", [["暂无数据", "Nothing here"]]);

registerLocale 会用传入的 [key, value][] 数组替换该语言的整张词典，因此扩充时通常需要带上原有词条。若只想追加少量词条，建议封装一个合并函数后再调用。

语言探测与切换

initLocale() 会：

1. 触发一次 getLocale() 探测（内存 → 存储 → 系统 → 默认）；
2. 非 App 端监听 uni.onLocaleChange，变化时自动 setLocale。

App 端（Android / iOS / 鸿蒙）运行时未实现 uni.getLocale，内部改取系统信息里的应用语言（language / osLanguage）。

内置词条一览（zh-cn 源）

词典覆盖通用文案与首批组件文案，主要有：

• 通用：加载中、暂无数据、确定、取消、提示、展开、收起、没有更多了、请输入、请选择、清空、完成、重置、全选、今天
• 表单校验：此字段为必填项、最小值为{min}、最少需要{min}个字符、最大值为{max}、最多允许{max}个字符、格式不正确、验证失败
• 上传 / 列表：上传 / 拍摄、上传失败、加载更多、上拉加载更多、下拉刷新、释放立即刷新、正在刷新、刷新成功
• 日期时间：年、月、日、时、分、秒、周日~周六、{year}年{month}月、至、开始日期、结束日期、请选择日期、请选择日期范围
• 键盘 / 验证：数字键盘、车牌键盘、密码键盘、安全键盘，请放心输入、身份证号码格式不正确、车牌号格式不正确、向右滑动完成验证、向右滑动转动图片、验证通过

完整词条见 uni_modules/jzfw-ui/locale/index.uts。