国际化(i18n)
Web 端组件内置完整的文案体系:所有组件的默认文案(按钮、占位符、状态提示、aria 标签等)都不硬编码中文,统一从语言包读取。内置简体中文(默认回退源)与英文两种语言,并可注册任意自定义语言。
切换语言
用 ConfigProvider 的 locale prop 包住应用(或任意子树):
vue
<script setup lang="ts">
import { ConfigProvider } from "ruanno-ui";
</script>
<template>
<ConfigProvider locale="en">
<!-- 子树内所有组件文案切换为英文 -->
<App />
</ConfigProvider>
</template>locale 取值:
- 字符串:已注册语言包的名称,内置
"zh-CN"(默认)与"en"; - 对象:直接传入
LocaleMessages结构的语言包,适合微调个别文案。
文档站右上角的「中 / EN」切换即此机制,组件演示会跟随切换。
注册自定义语言包
ts
import { registerLocale, zhCN, type LocaleMessages } from "ruanno-ui";
// 方式一:基于内置包改写
const zhTW: LocaleMessages = {
...zhCN,
common: { ...zhCN.common, confirm: "確定", cancel: "取消" },
};
registerLocale("zh-TW", zhTW);vue
<ConfigProvider locale="zh-TW">...</ConfigProvider>语言包为嵌套对象结构,键路径与组件一一对应(common / table / select / datepicker / dialog / pagination / upload…),完整清单见 packages/ui/src/locale/zh-CN.ts。缺失的键自动回退简体中文。
组件内取文案
库内组件统一通过 useLocale() 取文案,业务组件也可以复用同一体系:
ts
import { useLocale } from "ruanno-ui";
const { t } = useLocale();
t("dialog.confirm"); // 按点路径取
t("table.filter", { title: "状态" }); // {x} 占位符替换取不到的键原样返回路径并回退 zh-CN,不会抛错。
与 vue-i18n 共存
两者互不冲突:业务文案继续用 vue-i18n,组件库文案由 ConfigProvider 管理。需要联动时,把 i18n 的 locale 透传进来即可:
vue
<ConfigProvider :locale="locale === 'en' ? 'en' : 'zh-CN'">uni-app 端
@ruanno-ui/uniapp 的组件文案随包内置(默认简体中文),当前版本未提供独立语言包体系;有英文需求时可通过组件的文案类 prop(如 confirmText / cancelText / placeholder)显式覆盖。