国际化

Avue 默认使用简体中文，内置 zh-cn、zh 和 en。语言管理 API 来自 src/locale/index.ts；可以传语言代码，也可以合并自定义语言对象。

安装时选择语言

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import en from 'element-plus/es/locale/lang/en'
import Avue from '@smallwei/avue'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus, { locale: en })
app.use(Avue, { locale: 'en' })
app.mount('#app')

Avue 的按钮和提示语、Element Plus 的日期与分页文本分别由各自的语言配置控制。入口中的 CSS 和图标注册沿用快速上手。

语言管理 API

import { locale } from '@smallwei/avue'

locale.use('en')
locale.t('form.submitBtn') // 'Submit'
locale.getLocaleCode()    // 'en'
locale.getLocale('zh-cn') // 读取中文语言对象，不切换当前语言

方法	说明
locale.use(code, overrides?)	选择已注册语言，再深合并覆盖文本；返回合并后的语言对象
locale.use(messages)	以当前语言代码对应的注册语言包为基础重新合并自定义对象
locale.register(code, messages, aliases?)	注册自定义语言及别名；不会自动切换
locale.t(path, options?)	用点路径取文本，并替换命名或数字占位符
locale.getLocale(code?)	无参数读取当前对象；传代码读取该语言的对象
locale.getLocaleCode()	返回当前匹配到的语言代码
locale.i18n(handler)	设置自定义翻译处理器；传 null 取消

代码匹配会去掉首尾空格并转小写，先查完整代码，再查短代码。例如 en-US 会回退到 en；没有匹配语言时回到 zh-cn。缺少的翻译键会由内置中文补齐。

自定义文案与占位符

import { locale } from '@smallwei/avue'

locale.register('team-zh', {
  form: { submitBtn: '保存资料' },
  common: { closeBtn: '返回' },
  business: { welcome: '你好，{name}' }
}, ['team'])
locale.use('team')
locale.t('business.welcome', { name: '张三' }) // '你好，张三'

只覆盖需要改变的键即可，源码会深合并语言对象。每次 use() 都从注册包重新构建，不会累积上一次 use() 的临时覆盖；需要持续保留的文本先 register()，或一次传入完整的覆盖对象。业务字段的 label、自定义按钮文本和字典标签属于页面配置，需要由业务代码自行翻译。

运行时切换

当前语言状态保存在普通模块变量中，locale.use() 不是 Vue 响应式状态。已经缓存的计算属性不保证自动更新；需要即时切换时，用响应式 key 重新创建相关组件，同时让业务数据保留在外层。

<template>
  <el-select v-model="language" style="width: 180px">
    <el-option label="简体中文" value="zh-cn" />
    <el-option label="English" value="en" />
  </el-select>
  <el-config-provider :locale="elementLocale">
    <avue-form :key="language" v-model="form" :option="option" />
  </el-config-provider>
</template>

<script setup>
import { computed, ref, watch } from 'vue'
import { locale } from '@smallwei/avue'
import zhCn from 'element-plus/es/locale/lang/zh-cn'
import en from 'element-plus/es/locale/lang/en'

const language = ref('zh-cn')
const form = ref({ name: '' })
const elementLocale = computed(() => language.value === 'en' ? en : zhCn)
const option = computed(() => ({
  column: [{
    prop: 'name',
    label: language.value === 'en' ? 'Name' : '姓名'
  }]
}))
watch(language, value => locale.use(value), { immediate: true, flush: 'sync' })
</script>

切换语言会影响同一 Avue 模块实例中的其他组件，应在应用统一的语言入口管理。重建组件会重置组件内部交互状态，业务模型仍由外层 form 保存。

接入已有翻译函数

安装参数 i18n 或 locale.i18n() 可接入项目已有的翻译器。处理器签名为 (path, options, currentMessages)。

app.use(Avue, {
  locale: 'zh-cn',
  i18n(path, options) {
    // translate 和 hasTranslation 使用项目已有的实现
    if (hasTranslation(path)) return translate(path, options)
    return undefined
  }
})

当处理器返回 undefined、null 或原始路径时，Avue 回退到当前语言对象。返回字符串时仍会替换占位符。locale.i18n(null) 恢复默认翻译逻辑。

语言包与浏览器引入

模块项目也可以导入语言包对象：

import Avue from '@smallwei/avue'
import enLocale from '@smallwei/avue/lib/locale/lang/en'

app.use(Avue, { locale: enLocale })

语言代码更适合管理后续切换：传对象会覆盖当前语言文本，但不改变当前语言代码。使用已加载的浏览器全局包时可直接 app.use(AVUE, { locale: 'en' })；内置语言不需要额外下载语言文件。自定义语言可以通过 AVUE.locale.register() 注册。

源码也提供 lib/locale/browser/en.js、zh.js、zh-cn.js 浏览器语言文件，加载后注册到 window.AVUE_LANG。它们与模块导入路径的用途不同，不要把 CommonJS 语言模块直接作为浏览器脚本执行。