多语言

组件库内置国际化方案：语言包按命名空间组织，组件通过 useLocale 取值，切换语言会持久化并在下次启动恢复。内置 zh-CN、en-US 两套语言包，另有 fr-FR 可按需引入。

语言包结构

每个语言包是一个对象，除 name / label / locale 三个标识字段外，其余按命名空间分组（如 uModal、uUpload）：

export default {
    name: 'zh-CN',
    label: '简体中文',
    locale: 'zh-Hans',
    uModal: {
        title: '提示',
        confirmText: '确定',
        cancelText: '取消'
    },
    uSearch: {
        placeholder: '请输入关键字',
        actionText: '搜索'
    }
}

字段	说明
name	语言标识，用于切换与持久化，如 zh-CN
label	显示名称，用于语言列表，如 简体中文
locale	标准 locale 标识，如 zh-Hans

配置语言

在 main.uts 中通过 locale 选项配置：

import uViewProX from './uni_modules/uview-pro-x'

app.use(uViewProX, {
    locale: {
        locales: [],           // 语言包数组，空数组表示使用内置 zh-CN / en-US
        defaultLocale: 'zh-CN', // 默认语言
        isForce: false          // true 时 defaultLocale 优先级最高
    }
})

字段	类型	说明
locales	any[]	语言包数组；未传或为空时使用内置语言包
defaultLocale	string	默认语言名称
isForce	boolean	为 true 时 defaultLocale 优先级最高，忽略已保存的选择

使用语言包

用 useLocale 取值，优先使用解构调用：

import { useLocale } from '@/uni_modules/uview-pro-x'

const { t, currentLocale, locales, setLocale } = useLocale()

// 按完整路径取值
t('uModal.title')

// 切换语言（会持久化）
setLocale('en-US')

命名空间

useLocale(namespace) 传入命名空间后，t 会自动加前缀，避免重复书写：

const { t } = useLocale('uSearch')

t('placeholder')        // 等价于 t('uSearch.placeholder')

占位符替换

文案中形如 {name} 的占位符，可通过第二个参数传入替换对象：

// 语言包中：notAllowedExt: '不允许选择{ext}格式的文件'
t('uUpload.notAllowedExt', { ext: 'png' })

自定义语言包

locales 传入自定义语言包时：

• 同名语言（如再传一个 zh-CN）与内置语言包深合并，你提供的字段覆盖内置字段，未覆盖的字段继续用内置值；
• 新语言（如 ja-JP）直接注册，并出现在 locales 列表中。

import uViewProX from './uni_modules/uview-pro-x'
import { frFR } from '@/uni_modules/uview-pro-x'

app.use(uViewProX, {
    locale: {
        locales: [frFR],        // 与内置合并，新增法语
        defaultLocale: 'fr-FR'
    }
})

强制覆盖

默认同名语言是「深合并」，只覆盖你写出的字段。若希望传入的语言包完全替换内置同名语言，把 isForce 设为 true。

语言解析优先级

初始化时，默认语言的解析顺序为：

1. URL 注入（H5 端）：链接末尾的 lang 参数（如 ?lang=en-US），用于文档站 iframe 联动演示页语言；
2. isForce 为 true：取 defaultLocale；
3. 本地已保存：用户此前切换过的语言；
4. defaultLocale：首次进入且未强制时的兜底。

注意事项

1. 语言选择持久化在本地存储（键 uview-pro-x-locale），下次启动自动恢复。
2. t(key) 命中不到时原样返回 key，便于定位缺失文案；切换语言时不会报错。
3. 命名空间由组件约定，调用 t 时不要重复叠加前缀（useLocale('uSearch') 后写 t('placeholder')，而非 t('uSearch.placeholder')）。
4. H5 端的 lang 注入仅在 WEB 平台生效，其它平台恒定回退到常规解析顺序。
5. isForce 会同时改变两件事：同名语言包由「深合并」变为「完全替换」，且 defaultLocale 在解析时优先级最高（忽略已保存的选择）。