# 国际化支持

<cite>
**本文引用的文件**
- [src/locale/index.js](file://src/locale/index.js)
- [src/main.js](file://src/main.js)
- [packages/locale/index.js](file://packages/locale/index.js)
- [packages/locale/format.js](file://packages/locale/format.js)
- [packages/locale/lang/zh-CN.js](file://packages/locale/lang/zh-CN.js)
- [packages/locale/lang/en-US.js](file://packages/locale/lang/en-US.js)
- [packages/mixin/locale.js](file://packages/mixin/locale.js)
- [packages/core/src/mixin/locale.js](file://packages/core/src/mixin/locale.js)
- [packages/components/ProForm.vue](file://packages/components/ProForm.vue)
- [packages/components/ProTable.vue](file://packages/components/ProTable.vue)
- [packages/index.js](file://packages/index.js)
- [package.json](file://package.json)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件系统性阐述项目的国际化（i18n）支持方案，覆盖以下方面：
- 语言包结构与组织方式：语言代码规范、文件命名约定、目录结构
- 动态切换机制：语言状态管理、组件重新渲染、持久化策略
- 自定义语言包开发：键值对管理、占位符处理、复数形式支持
- 多语言开发规范：文本提取、翻译管理、质量保证
- 完整 API 参考与使用示例
- 最佳实践与常见问题
- 与第三方国际化库的集成方式

## 项目结构
国际化能力由三层协同构成：
- 应用层 i18n 配置：集中初始化 vue-i18n 实例，合并第三方组件库与自研语言包
- 组件层混入：为业务组件注入 $t 与 t 方法，统一调用入口
- 自研语言包：提供格式化模板与按语言分包的键值集合

```mermaid
graph TB
subgraph "应用层"
A["src/main.js<br/>挂载 i18n 实例"]
B["src/locale/index.js<br/>创建 i18n 实例并合并语言包"]
end
subgraph "组件层"
C["packages/mixin/locale.js<br/>混入 $t/t"]
D["packages/core/src/mixin/locale.js<br/>混入 $t/t"]
E["packages/components/ProForm.vue<br/>使用 t('pro.common.*')"]
F["packages/components/ProTable.vue<br/>使用 t('pro.common.*')"]
end
subgraph "语言包层"
G["packages/locale/index.js<br/>导出 t/use/i18n"]
H["packages/locale/format.js<br/>占位符模板"]
I["packages/locale/lang/zh-CN.js<br/>中文键值"]
J["packages/locale/lang/en-US.js<br/>英文键值"]
end
A --> B
A --> C
A --> D
C --> G
D --> G
E --> C
F --> D
G --> H
G --> I
G --> J
B --> I
B --> J
```

图表来源
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [src/locale/index.js:1-19](file://src/locale/index.js#L1-L19)
- [packages/mixin/locale.js:1-18](file://packages/mixin/locale.js#L1-L18)
- [packages/core/src/mixin/locale.js:1-17](file://packages/core/src/mixin/locale.js#L1-L17)
- [packages/locale/index.js:1-64](file://packages/locale/index.js#L1-L64)
- [packages/locale/format.js:1-50](file://packages/locale/format.js#L1-L50)
- [packages/locale/lang/zh-CN.js:1-48](file://packages/locale/lang/zh-CN.js#L1-L48)
- [packages/locale/lang/en-US.js:1-48](file://packages/locale/lang/en-US.js#L1-L48)

章节来源
- [src/locale/index.js:1-19](file://src/locale/index.js#L1-L19)
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/locale/index.js:1-64](file://packages/locale/index.js#L1-L64)
- [packages/locale/format.js:1-50](file://packages/locale/format.js#L1-L50)
- [packages/locale/lang/zh-CN.js:1-48](file://packages/locale/lang/zh-CN.js#L1-L48)
- [packages/locale/lang/en-US.js:1-48](file://packages/locale/lang/en-US.js#L1-L48)
- [packages/mixin/locale.js:1-18](file://packages/mixin/locale.js#L1-L18)
- [packages/core/src/mixin/locale.js:1-17](file://packages/core/src/mixin/locale.js#L1-L17)
- [packages/components/ProForm.vue:146-156](file://packages/components/ProForm.vue#L146-L156)
- [packages/components/ProTable.vue:154-170](file://packages/components/ProTable.vue#L154-L170)

## 核心组件
- 应用级 i18n 初始化：在应用入口创建并注册 vue-i18n 实例，设置默认语言与消息体
- 自研语言包模块：提供 t/use/i18n 导出，负责与 vue-i18n 的桥接与本地回退
- 模板格式化器：支持占位符替换，兼容对象与数组两种传参形式
- 组件混入：向组件注入 $t 与 t 方法，确保在组合式与选项式 API 中均可使用
- 业务组件使用：通过 t('pro.common.xxx') 访问语言包键值

章节来源
- [src/locale/index.js:8-18](file://src/locale/index.js#L8-L18)
- [packages/locale/index.js:35-64](file://packages/locale/index.js#L35-L64)
- [packages/locale/format.js:9-50](file://packages/locale/format.js#L9-L50)
- [packages/mixin/locale.js:1-18](file://packages/mixin/locale.js#L1-L18)
- [packages/core/src/mixin/locale.js:1-17](file://packages/core/src/mixin/locale.js#L1-L17)
- [packages/components/ProForm.vue:128-139](file://packages/components/ProForm.vue#L128-L139)
- [packages/components/ProTable.vue:168-194](file://packages/components/ProTable.vue#L168-L194)

## 架构总览
下图展示从应用启动到组件渲染的国际化调用链路。

```mermaid
sequenceDiagram
participant App as "应用入口<br/>src/main.js"
participant I18n as "i18n 实例<br/>src/locale/index.js"
participant Mix as "组件混入<br/>packages/*/mixin/locale.js"
participant Lng as "语言包模块<br/>packages/locale/index.js"
participant Tpl as "格式化器<br/>packages/locale/format.js"
App->>I18n : 创建并注册 i18n 实例
App->>Mix : 注册混入$t/t
Mix->>Lng : 调用 t(path, options)
Lng->>Lng : 优先走 vue-i18n 全局翻译
alt 未命中
Lng->>Tpl : 使用模板格式化
Tpl-->>Lng : 返回格式化后的字符串
end
Lng-->>Mix : 返回翻译结果
Mix-->>App : 渲染组件文本
```

图表来源
- [src/main.js:10-13](file://src/main.js#L10-L13)
- [src/locale/index.js:8-18](file://src/locale/index.js#L8-L18)
- [packages/mixin/locale.js:5-16](file://packages/mixin/locale.js#L5-L16)
- [packages/locale/index.js:12-33](file://packages/locale/index.js#L12-L33)
- [packages/locale/format.js:23-46](file://packages/locale/format.js#L23-L46)

## 详细组件分析

### 语言包结构与组织
- 语言代码规范：采用标准语言标签，如 zh-CN、en-US
- 文件命名约定：lang/<语言代码>.js，例如 zh-CN.js、en-US.js
- 目录结构：packages/locale 下包含 lang 子目录与 format.js、index.js
- 键值组织：以 pro.common、pro.table 等命名空间分组，便于检索与维护

章节来源
- [packages/locale/lang/zh-CN.js:1-48](file://packages/locale/lang/zh-CN.js#L1-L48)
- [packages/locale/lang/en-US.js:1-48](file://packages/locale/lang/en-US.js#L1-L48)
- [packages/locale/index.js:60-64](file://packages/locale/index.js#L60-L64)

### 动态切换机制
- 语言状态管理：通过 vue-i18n 的 locale 属性控制当前语言
- 组件重新渲染：当 locale 变更时，组件内部通过 $t/t 触发响应式更新
- 持久化存储：可结合浏览器存储或用户偏好设置，在应用启动时恢复语言

```mermaid
flowchart TD
Start(["开始"]) --> SetLocale["设置 i18n.locale"]
SetLocale --> MergeMsg["合并第三方与自研语言包"]
MergeMsg --> UpdateLang["更新本地 lang 缓存"]
UpdateLang --> TriggerRender["触发组件 $t/t 调用"]
TriggerRender --> RenderDone["完成组件重新渲染"]
RenderDone --> End(["结束"])
```

图表来源
- [src/locale/index.js:14-17](file://src/locale/index.js#L14-L17)
- [packages/locale/index.js:19-32](file://packages/locale/index.js#L19-L32)
- [packages/mixin/locale.js:5-16](file://packages/mixin/locale.js#L5-L16)

章节来源
- [src/locale/index.js:8-18](file://src/locale/index.js#L8-L18)
- [packages/locale/index.js:12-33](file://packages/locale/index.js#L12-L33)
- [packages/mixin/locale.js:1-18](file://packages/mixin/locale.js#L1-18)

### 自定义语言包开发流程
- 新增语言包：在 packages/locale/lang 下新增对应语言代码文件
- 键值对管理：按命名空间组织键值，避免冲突
- 占位符处理：通过 format.js 提供的模板语法进行参数替换
- 复数形式支持：可在 format.js 基础上扩展规则，或在业务侧根据上下文处理

章节来源
- [packages/locale/format.js:9-50](file://packages/locale/format.js#L9-L50)
- [packages/locale/lang/zh-CN.js:1-48](file://packages/locale/lang/zh-CN.js#L1-L48)
- [packages/locale/lang/en-US.js:1-48](file://packages/locale/lang/en-US.js#L1-L48)

### 多语言开发规范
- 文本提取：统一使用 t('pro.xxx') 形式，避免硬编码
- 翻译管理：集中维护语言包文件，建立审阅与版本控制流程
- 质量保证：在构建阶段进行缺失键检测与占位符一致性校验

章节来源
- [packages/components/ProForm.vue:128-139](file://packages/components/ProForm.vue#L128-L139)
- [packages/components/ProTable.vue:168-194](file://packages/components/ProTable.vue#L168-L194)

### API 参考与使用示例
- t(path, options)：翻译函数，支持点号路径访问与占位符替换
- $t(...)：组件实例方法，自动绑定当前组件上下文
- use(langObj)：切换本地语言包缓存
- i18n(initI18n)：注入 vue-i18n 实例，建立桥接

章节来源
- [packages/locale/index.js:35-64](file://packages/locale/index.js#L35-L64)
- [packages/mixin/locale.js:5-16](file://packages/mixin/locale.js#L5-L16)
- [packages/core/src/mixin/locale.js:5-16](file://packages/core/src/mixin/locale.js#L5-L16)

### 与第三方国际化库的集成
- 依赖声明：vue-i18n 版本 ^9.2.2
- 集成方式：在应用入口创建 i18n 实例，并将第三方组件库语言包与自研语言包合并

章节来源
- [package.json:30](file://package.json#L30)
- [src/locale/index.js:3-6](file://src/locale/index.js#L3-L6)

## 依赖关系分析

```mermaid
graph LR
PkgIndex["packages/index.js<br/>导出 lang/i18n/locale"] --> LngIndex["packages/locale/index.js"]
SrcMain["src/main.js"] --> SrcI18n["src/locale/index.js"]
SrcI18n --> LangCN["packages/locale/lang/zh-CN.js"]
SrcI18n --> LangEN["packages/locale/lang/en-US.js"]
Mixin["packages/mixin/locale.js"] --> LngIndex
CoreMixin["packages/core/src/mixin/locale.js"] --> LngIndex
ProForm["packages/components/ProForm.vue"] --> Mixin
ProTable["packages/components/ProTable.vue"] --> CoreMixin
```

图表来源
- [packages/index.js:49-68](file://packages/index.js#L49-L68)
- [src/main.js:10-13](file://src/main.js#L10-L13)
- [src/locale/index.js:3-6](file://src/locale/index.js#L3-L6)
- [packages/mixin/locale.js:1-18](file://packages/mixin/locale.js#L1-L18)
- [packages/core/src/mixin/locale.js:1-17](file://packages/core/src/mixin/locale.js#L1-L17)
- [packages/components/ProForm.vue:146-156](file://packages/components/ProForm.vue#L146-L156)
- [packages/components/ProTable.vue:154-170](file://packages/components/ProTable.vue#L154-L170)

章节来源
- [packages/index.js:49-68](file://packages/index.js#L49-L68)
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [src/locale/index.js:1-19](file://src/locale/index.js#L1-L19)
- [packages/mixin/locale.js:1-18](file://packages/mixin/locale.js#L1-L18)
- [packages/core/src/mixin/locale.js:1-17](file://packages/core/src/mixin/locale.js#L1-L17)
- [packages/components/ProForm.vue:146-156](file://packages/components/ProForm.vue#L146-L156)
- [packages/components/ProTable.vue:154-170](file://packages/components/ProTable.vue#L154-L170)

## 性能考量
- 合并策略：首次切换语言时合并第三方与自研语言包，后续复用缓存，减少重复计算
- 模板格式化：仅在未命中 vue-i18n 时执行，避免不必要的字符串处理
- 组件渲染：通过 $t/t 的响应式特性触发局部更新，降低整体重绘成本

## 故障排查指南
- 语言包未生效：确认 i18n 实例已正确注册，且语言代码与文件名一致
- 占位符不替换：检查传入 options 是否为对象或数组，以及占位符键名是否匹配
- 组件未更新：确保在组件中使用 $t 或 t 方法，并在语言切换后触发重新渲染
- 第三方库文案未翻译：检查是否将第三方语言包与自研语言包合并到同一 locale

章节来源
- [src/locale/index.js:8-18](file://src/locale/index.js#L8-L18)
- [packages/locale/format.js:23-46](file://packages/locale/format.js#L23-L46)
- [packages/mixin/locale.js:5-16](file://packages/mixin/locale.js#L5-L16)

## 结论
本项目通过 vue-i18n 与自研语言包模块的协作，实现了统一、可扩展的国际化能力。应用层负责初始化与合并，组件层通过混入提供一致的调用接口，语言包层以命名空间与占位符模板支撑多场景需求。遵循本文档的规范与流程，可高效地扩展新语言与优化现有翻译。

## 附录
- 语言包文件示例路径
  - [中文语言包](file://packages/locale/lang/zh-CN.js)
  - [英文语言包](file://packages/locale/lang/en-US.js)
- 组件使用示例
  - [ProForm 组件中的 t 调用:128-139](file://packages/components/ProForm.vue#L128-L139)
  - [ProTable 组件中的 t 调用:168-194](file://packages/components/ProTable.vue#L168-L194)