国际化

Vital Design 内置组件文案的多语言支持。业务页面自身的文案建议使用 vue-i18n 等方案单独管理。

内置语言

语言	语言名（LangName）
简体中文	zh-cn
繁體中文	zh-tw
English	en-us

内置语言包覆盖日历、分页、列表、上传、搜索等组件的固定文案。

切换语言

从 vital-design/locale 导入 useLang：

import { useLang } from 'vital-design/locale';
import type { LangName } from 'vital-design/locale';

const { lang, use, toggle, merge } = useLang();

// 切换到英文
use('en-us');

// 不传参数时，按 zh-cn → zh-tw → en-us 顺序循环切换
toggle();

useLang 会将当前语言写入本地缓存（vd-use-lang），下次启动时自动恢复。

应用初始化时也可直接指定默认语言：

// main.ts 或 App.vue
import { useLang } from 'vital-design/locale';

useLang('zh-cn');

覆盖部分文案

使用 merge 可深度合并自定义配置，无需重写整份语言包：

import { useLang } from 'vital-design/locale';

const { merge } = useLang();

merge({
  common: {
    confirm: 'OK',
    cancel: 'Cancel',
  },
  list: {
    loading: 'Loading...',
    finished: 'No more data',
  },
});

合并作用于当前语言的配置对象，切换语言后需重新 merge 或在使用 use 时传入完整配置。

切换并传入自定义语言包

use 方法的第二个参数可传入完整或部分语言配置：

import { useLang } from 'vital-design/locale';

const { use } = useLang();

use('zh-cn', {
  common: {
    confirm: '确定',
    cancel: '取消',
    // ...
  },
  pagination: {
    prev: '上一页',
    next: '下一页',
  },
});

自定义组件接入语言包

若业务组件需要读取语言配置，可使用 useTranslate：

import { useTranslate } from 'vital-design/locale';

const t = useTranslate('pagination');

const prevText = t('prev');       // 读取 pagination.prev
const confirmText = t('confirm'); // 回退到 common.confirm

useTranslate 会先查找组件命名空间下的字段，找不到时回退到 common 公共字段。字段值为函数时，可传入参数执行：

// calendar.dateTitle 为 (year, month) => string
const title = t('dateTitle', 2026, 3);

语言包结构

语言配置类型为 LangVars，主要字段包括：

命名空间	说明
common	确认、取消、年月日等公共文案
calendar	日历标题、星期、区间文案
cascader	级联选择占位符
list	加载中、加载完成、错误提示
pagination	分页按钮与信息文案
uploader	上传状态文案
search	搜索按钮文案
dropdown	下拉占位符
read-more	展开 / 收起文案
picker-color	颜色输入占位符

完整定义见 vital-design/locale 导出的 LangVars 类型。

业务代码国际化

组件库语言包仅覆盖组件内部文案。页面标题、表单标签、接口错误提示等业务文案，请使用 vue-i18n 或项目自有的 i18n 方案，与组件库语言切换相互独立。

可在切换组件语言的同时切换 vue-i18n 语言：

import { useI18n } from 'vue-i18n';
import { useLang } from 'vital-design/locale';

function setLocale(name: 'zh-cn' | 'en-us') {
  useLang().use(name);
  useI18n().locale.value = name;
}

类型定义

import type { LangName, LangVars } from 'vital-design/locale';
import { useLang, useTranslate, Locale } from 'vital-design/locale';