Vben Admin 新增维吾尔语（ug-CN）完整总结
一、涉及的所有层级
在 Vben Admin 里加一门新语言，需要同步修改以下层级，缺一不可：
| 层级 | 位置 | 作用 |
|---|---|---|
| 类型定义 | @vben-core/typings 的 SupportedLanguages |
让 SupportedLanguagesType 包含 'ug-CN' |
| 核心简单语言包 | packages/@core/composables/src/use-simple-locale/messages.ts |
Modal、Alert 等核心组件的按钮文字 |
| 框架语言包 | packages/locales/src/langs/ug-CN/ |
Vben 框架通用文案（登录、偏好、UI 等） |
| 应用语言包 | apps/web-antd/src/locales/langs/ug-CN/ |
业务覆盖（demos、page 等） |
| 语言列表 | SUPPORT_LANGUAGES / setSupportLanguages |
语言切换器显示维吾尔语 |
| 第三方库 | Ant Design Vue、vxe-table、dayjs | 各组件库自身的 locale |
二、各层详细配置
1. 类型定义
在应用内新建 .d.ts，用模块增强（不改 node_modules）：
ts
// apps/web-antd/src/typings/locale.d.ts
import '@vben-core/typings';
declare module '@vben-core/typings' {
interface SupportedLanguages {
'ug-CN': 'ئۇيغۇرچە';
}
}2. 核心简单语言包
packages/@core/composables/src/use-simple-locale/messages.ts：
ts
export const messages: Partial<Record<Locale, Record<string, string>>> = {
'en-US': { cancel: 'Cancel', confirm: 'Confirm', ... },
'zh-CN': { cancel: '取消', confirm: '确认', ... },
'ug-CN': {
cancel: 'ئەمەلدىن قالدۇرۇش',
collapse: 'يىغىش',
confirm: 'جەزىملەش',
expand: 'كېڭەيتىش',
prompt: 'ئەسكەرتمە',
reset: 'ئەسلىگە قايتۇرۇش',
submit: 'تاپشۇرۇش',
toggleSidebar: 'يان بالداقنى ئالماشتۇرۇش',
confirmTitle: 'جەزىملەڭ',
},
};
export const getMessages = (locale: Locale) =>
messages[locale] ?? messages['en-US'] ?? {};这一层最容易被遗漏。Modal、Alert 的按钮不走 @vben/locales，走的是这个核心简单语言包。
3. 框架语言包
packages/locales/src/langs/ug-CN/ 下要放和 zh-CN 同名同结构的 JSON：
authentication.json
common.json
preferences.json
profile.json
ui.json
...4. 应用语言包
apps/web-antd/src/locales/langs/ug-CN/ 下放业务覆盖，同样和 zh-CN 对齐。
5. 语言列表
SUPPORT_LANGUAGES 或运行时 setSupportLanguages：
ts
{ label: 'ئۇيغۇرچە', value: 'ug-CN' }6. 第三方库
| 库 | 做法 |
|---|---|
| Ant Design Vue | 拷贝 es/locale/ug_CN.js + date-picker / time-picker / calendar / vc-pagination / vc-picker 下的 ug_CN.js 共 6 份文件 |
| dayjs | 官方已有 ug-cn，直接 import 'dayjs/locale/ug-cn' |
| vxe-table | 在 Vben 的 setupVbenVxeTable 的 localMap 里加 'ug-CN': ugCN |
三、Ant Design Vue 的 6 个文件
只拷 locale/ug_CN.js 不够，它内部会 import 三个子模块：
es/locale/ug_CN.js
es/date-picker/locale/ug_CN.js
es/time-picker/locale/ug_CN.js
es/calendar/locale/ug_CN.js
es/vc-pagination/locale/ug_CN.js
es/vc-picker/locale/ug_CN.js每个还要有对应的 .d.ts。缺任何一个，构建时 esbuild 会报 Could not resolve。
四、踩过的坑
| 坑 | 原因 | 解决 |
|---|---|---|
| 504 Outdated Optimize Dep | Vite 依赖预构建缓存过期 | 删 apps/web-antd/node_modules/.vite，重启 |
Could not resolve ../date-picker/locale/ug_CN |
antd locale 入口引用了子模块，只拷了入口 | 补齐 6 个文件 |
| 切换语言界面仍中文 | 框架层 packages/locales/src/langs/ 缺 ug-CN |
从 zh-CN 复制一份 |
| Modal 按钮显示英文 | 核心简单语言包 messages.ts 缺 ug-CN |
在 messages.ts 里加 ug-CN |
| vxe-table 不跟随切换 | Vben 的 localMap 未注册 ug-CN |
加映射 |
| 文档标签写成 "Chinese (UyGur)" | 概念错误，维吾尔语不是中文 | 改成 "Uyghur" / "维吾尔语" |
五、两条重要经验
1. 不要直接改 node_modules
pnpm install/ 更新依赖会丢失- 优先改 workspace 源码（
packages/下），或用pnpm patch固化
2. 改语言后必须清缓存
localStorage（偏好设置持久化）node_modules/.vite（Vite 依赖预构建）- 浏览器硬刷新
Ctrl+Shift+R
六、向官方提交 PR 的经验
Ant Design Vue
- Fork → 切分支
feature/locale-ug_CN（基于upstream/main） - 新增 4 个 locale 文件 + 改
dayjs.ts+ 改文档 - 提交格式：
feat(locale): add ug_CN locale support - PR 描述里说明 dayjs 依赖情况
- 第一次贡献的 CI 需要维护者手动批准，耐心等
dayjs
- 官方已有
ug-cn，无需重复提交
七、下次新项目开箱清单
- 新建
.d.ts做类型增强，加'ug-CN' - 核心简单语言包
packages/@core/composables/src/use-simple-locale/messages.ts加ug-CN - 框架语言包
packages/locales/src/langs/ug-CN/从zh-CN复制 - 应用语言包
apps/web-antd/src/locales/langs/ug-CN/从zh-CN复制 - 语言列表
SUPPORT_LANGUAGES加ug-CN - Ant Design Vue 拷 6 个文件到
node_modules或用 patch - vxe-table
localMap加映射 - dayjs 直接 import
dayjs/locale/ug-cn - 清缓存重启：
rm -r apps/web-antd/node_modules/.vite+pnpm dev - 验证：切到维吾尔语，检查框架文字、Antd 组件、vxe-table、Modal 按钮是否都切换
八、最终成果
- Vben 框架文字
- Ant Design Vue 组件
- vxe-table 表格
- Modal / Alert 按钮（核心简单语言包）
- 业务页面内容
- 向 ant-design-vue 提交了 PR #8595
全部同步切换为维吾尔语。