useLocale 国际化
17:43说明
useLocale 提供翻译函数与语言包管理:t 按键路径取文案并替换 {key} 占位符,setLocale 切换语言并持久化,currentLocale 与 locales 以响应式形式暴露当前语言和语言列表。
示例
当前语言信息
读取 currentLocale 的 label、name 与 locale,未匹配语言时回退为 -。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item title="当前语言" :value="currentLangText" :arrow="false" />
<ux-cell-item title="Locale" :value="currentLocaleText" :arrow="false" :border-bottom="false" />
</ux-cell-group>
</template>
<script setup lang="ts">
import { useLocale } from '@/uni_modules/uview-pro-x';
const { currentLocale } = useLocale();
// currentLocale 可能为 null,统一在计算属性里收敛
const currentLangText = computed((): string => {
const cur = currentLocale.value;
if (cur == null) return '-';
return cur.label + ' (' + cur.name + ')';
});
const currentLocaleText = computed((): string => {
const cur = currentLocale.value;
return cur == null ? '-' : cur.locale;
});
</script>语言切换
点击按钮调用 setLocale 切换 zh-CN / en-US / fr-FR,当前语言的按钮显示为 primary 主题。
查看源码
vue
<template>
<ux-button size="small" :type="isActive('zh-CN') ? 'primary' : 'info'" block text="简体中文" @click="switchLocale('zh-CN')" />
<ux-gap :height="8" />
<ux-button size="small" :type="isActive('en-US') ? 'primary' : 'info'" block text="English" @click="switchLocale('en-US')" />
<ux-gap :height="8" />
<ux-button size="small" :type="isActive('fr-FR') ? 'primary' : 'info'" block text="Français" @click="switchLocale('fr-FR')" />
</template>
<script setup lang="ts">
import { useLocale } from '@/uni_modules/uview-pro-x';
const { currentLocale, setLocale } = useLocale();
const currentName = computed((): string => {
const cur = currentLocale.value;
return cur == null ? '' : cur.name;
});
function isActive(name: string): boolean {
return currentName.value == name;
}
// 切换语言,内部会持久化到本地存储
function switchLocale(name: string): void {
setLocale(name);
}
</script>翻译示例
t 按 uModal.title、uSearch.placeholder 等 key 取组件内置文案,切换语言后随之刷新。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in translateRows"
:key="index"
:title="item.title"
:value="item.value"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useLocale } from '@/uni_modules/uview-pro-x';
const { t } = useLocale();
type CellRow = {
title: string;
value: string;
last: boolean;
};
// 语言切换后这些文案会随当前语言变化
const translateRows = computed((): CellRow[] => [
{ title: '弹窗标题', value: t('uModal.title'), last: false },
{ title: '确认按钮', value: t('uModal.confirmText'), last: false },
{ title: '搜索占位符', value: t('uSearch.placeholder'), last: false },
{ title: '上传文案', value: t('uUpload.uploadText'), last: true }
]);
</script>占位符替换示例
t 的第二个参数传入替换对象,uUpload.notAllowedExt 中的 {ext} 会被替换为 pdf。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item title="原文(含占位符)" value="uUpload.notAllowedExt" :arrow="false" />
<ux-cell-item title="替换后" :value="placeholderReplaced" :arrow="false" :border-bottom="false" />
</ux-cell-group>
</template>
<script setup lang="ts">
import { useLocale } from '@/uni_modules/uview-pro-x';
const { t } = useLocale();
// 第二个参数为替换对象,字符串中的 {ext} 会被替换
const placeholderReplaced = computed((): string => t('uUpload.notAllowedExt', { ext: 'pdf' }));
</script>命名空间示例 (uUpload)
useLocale('uUpload') 预先绑定命名空间,t 的 key 无需再带 uUpload. 前缀。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in namespaceRows"
:key="index"
:title="item.title"
:value="item.value"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useLocale } from '@/uni_modules/uview-pro-x';
// 指定命名空间后,t 的 key 不必再带前缀
const { t: uploadT } = useLocale('uUpload');
type CellRow = {
title: string;
value: string;
last: boolean;
};
const namespaceRows = computed((): CellRow[] => [
{ title: 'uploadText', value: uploadT('uploadText'), last: false },
{ title: 'uploadImage', value: uploadT('uploadImage'), last: false },
{ title: 'retry', value: uploadT('retry'), last: true }
]);
</script>可用语言列表
读取 locales 列出已注册语言的 label 与 name,序号在数据层生成。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in localeRows"
:key="index"
:title="item.title"
:value="item.value"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useLocale } from '@/uni_modules/uview-pro-x';
const { currentLocale, locales } = useLocale();
type CellRow = {
title: string;
value: string;
last: boolean;
};
// last 在数据层生成,模板不需要读源数组长度
const localeRows = computed((): CellRow[] => {
const list = locales.value;
const rows: CellRow[] = [];
for (let i = 0; i < list.length; i++) {
rows.push({
title: (i + 1).toString(),
value: list[i].label + ' (' + list[i].name + ')',
last: i == list.length - 1
});
}
return rows;
});
</script>语言包合并演示
t 的第三个参数指定语言,分别取 en-US 与 fr-FR 文案,结果不受当前语言影响。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in mergeRows"
:key="index"
:title="item.title"
:value="item.value"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useLocale } from '@/uni_modules/uview-pro-x';
const { t } = useLocale();
type CellRow = {
title: string;
value: string;
last: boolean;
};
// 第三个参数指定语言,结果不受当前语言影响
const mergeRows: CellRow[] = [
{ title: 'en-US 分区副标题', value: t('uSection.subTitle', null, 'en-US'), last: false },
{ title: 'en-US 空状态', value: t('uEmpty.data', null, 'en-US'), last: false },
{ title: 'en-US 弹窗标题', value: t('uModal.title', null, 'en-US'), last: false },
{ title: 'fr-FR 空搜索', value: t('uEmpty.search', null, 'fr-FR'), last: false },
{ title: 'fr-FR 分区副标题', value: t('uSection.subTitle', null, 'fr-FR'), last: true }
];
</script>uCalendar 组件翻译
从内置语言包读取 uCalendar 的星期缩写与年月单位,以及 uEmpty 的购物车 / 搜索空状态文案。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in builtinRows"
:key="index"
:title="item.title"
:value="item.value"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useLocale } from '@/uni_modules/uview-pro-x';
const { t } = useLocale();
type CellRow = {
title: string;
value: string;
last: boolean;
};
// 内置语言包覆盖日历、空状态、上传等组件文案
const builtinRows: CellRow[] = [
{
title: '星期缩写',
value: t('uCalendar.sun') + ' ' + t('uCalendar.mon') + ' ' + t('uCalendar.tue') + ' ' + t('uCalendar.wed'),
last: false
},
{ title: '年月单位', value: t('uCalendar.year') + ' ' + t('uCalendar.month'), last: false },
{ title: '购物车空', value: t('uEmpty.car'), last: false },
{ title: '搜索空', value: t('uEmpty.search'), last: true }
];
</script>uEmpty 组件翻译
沿用内置语言包的读取方式,展示 uEmpty.car 与 uEmpty.search 的空状态文案。
查看源码
vue
<template>
<ux-cell-group :border="false">
<ux-cell-item
v-for="(item, index) in builtinRows"
:key="index"
:title="item.title"
:value="item.value"
:arrow="false"
:border-bottom="!item.last"
/>
</ux-cell-group>
</template>
<script setup lang="ts">
import { useLocale } from '@/uni_modules/uview-pro-x';
const { t } = useLocale();
type CellRow = {
title: string;
value: string;
last: boolean;
};
// 内置语言包覆盖日历、空状态、上传等组件文案
const builtinRows: CellRow[] = [
{
title: '星期缩写',
value: t('uCalendar.sun') + ' ' + t('uCalendar.mon') + ' ' + t('uCalendar.tue') + ' ' + t('uCalendar.wed'),
last: false
},
{ title: '年月单位', value: t('uCalendar.year') + ' ' + t('uCalendar.month'), last: false },
{ title: '购物车空', value: t('uEmpty.car'), last: false },
{ title: '搜索空', value: t('uEmpty.search'), last: true }
];
</script>API
参数
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| namespace | 命名空间前缀;非空时 t 的 key 自动拼接为 namespace.key | string | '' | - |
返回值
| 字段 | 说明 | 类型 |
|---|---|---|
| currentLocale | 当前语言信息(name / label / locale),未匹配时为 null | Ref<Locale | null> |
| locales | 已注册的语言列表 | Ref<Locale[]> |
| t | 翻译函数;key 不存在时原样返回 key,第三参数可指定语言 | (key: string, replacements?: JsonObject | null, localeName?: string) => string |
| setLocale | 切换当前语言并持久化,语言未注册时只告警不切换 | (name: string) => void |
| getLocales | 获取已注册的语言列表 | () => Locale[] |
| getCurrentLocale | 获取当前语言信息 | () => Locale | null |
| initLocale | 初始化语言包(install 内部调用) | (locale?: UViewProXLocaleOptions | null) => void |
注意事项
- 仅在 H5(
WEB条件编译)端会从location.href读取lang=参数并注入语言;其他平台该步骤恒返回null,不影响原有语言解析。 - 默认语言解析优先级:URL 注入 >
isForce为true时的defaultLocale> 本地存储的已选语言 >defaultLocale(内置默认zh-CN)。 setLocale只接受已注册语言,名字不存在时仅打印警告且不切换;切换成功会写入本地存储uview-pro-x-locale。t找不到 key 时原样返回 key,不会抛出错误。