跳到主要内容

国际化(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)显式覆盖。