# 国际化 API

<cite>
**本文引用的文件**
- [src/locale/index.js](file://src/locale/index.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/index.js](file://packages/index.js)
- [packages/mixin/locale.js](file://packages/mixin/locale.js)
- [packages/core/src/mixin/locale.js](file://packages/core/src/mixin/locale.js)
- [lib/locales/tr-TR.js](file://lib/locales/tr-TR.js)
- [lib/locales/fr-FR.js](file://lib/locales/fr-FR.js)
- [packages/locale/lang/tr-TR.js](file://packages/locale/lang/tr-TR.js)
- [packages/locale/lang/fr-FR.js](file://packages/locale/lang/fr-FR.js)
</cite>

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

## 简介
本文件为 Pro-IVIEW V3 国际化功能的 API 参考与最佳实践指南，重点覆盖以下内容：
- 国际化 API：locale.use()、i18n()、lang() 的使用方式与行为边界
- 语言包结构与自定义语言包开发流程
- 动态语言切换的实现机制与性能优化建议
- 多语言开发最佳实践与注意事项
- 语言包加载与缓存策略
- 国际化与组件的集成方式与配置选项

## 项目结构
围绕国际化的核心文件分布如下：
- 应用级 i18n 实例：在应用入口初始化并注入全局
- 组件库内部国际化模块：提供本地化的翻译函数与适配逻辑
- 语言包：按区域代码组织的 JSON 结构，支持扩展与合并
- 混入：为组件提供 $t 与 t 方法，统一调用路径
- 插件入口：对外暴露 locale/use、i18n、lang 等 API，并在安装时完成初始化

```mermaid
graph TB
subgraph "应用层"
A["src/locale/index.js<br/>创建 vue-i18n 实例"]
end
subgraph "组件库内部"
B["packages/locale/index.js<br/>本地化适配与翻译函数"]
C["packages/locale/format.js<br/>字符串模板格式化"]
D["packages/locale/lang/*.js<br/>语言包集合"]
E["packages/mixin/locale.js<br/>组件混入"]
F["packages/core/src/mixin/locale.js<br/>核心混入"]
end
subgraph "插件与入口"
G["packages/index.js<br/>导出 locale/i18n/lang 并安装"]
end
A --> G
G --> B
B --> D
B --> C
E --> B
F --> B
```

图表来源
- [src/locale/index.js:1-18](file://src/locale/index.js#L1-L18)
- [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/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/index.js:1-69](file://packages/index.js#L1-L69)

章节来源
- [src/locale/index.js:1-18](file://src/locale/index.js#L1-L18)
- [packages/locale/index.js:1-64](file://packages/locale/index.js#L1-L64)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)

## 核心组件
- 应用级 i18n 实例（vue-i18n）
  - 在应用入口创建并配置默认语言、消息合并策略
  - 将第三方 UI 组件库的语言包与组件库自身的语言包进行合并
- 组件库内部国际化模块（packages/locale）
  - 提供本地化翻译函数 t(path, options)
  - 提供 locale.use(lang) 切换语言对象
  - 提供 locale.i18n(initI18n) 注入外部 i18n 实例
  - 内部维护当前语言对象、已合并标记与消息缓存
- 语言包（packages/locale/lang）
  - 按区域代码组织，结构包含 pro.locale 与业务命名空间（如 common、table、tableEdit）
  - 支持通过合并策略与第三方 UI 语言包共同生效
- 组件混入（packages/mixin/locale.js、packages/core/src/mixin/locale.js）
  - 为组件提供 $t 与 t 方法，统一调用本地化翻译函数
- 插件入口（packages/index.js）
  - 对外导出 locale/use、i18n、lang 等 API
  - 在安装时根据传入配置调用 locale.use 与 locale.i18n

章节来源
- [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/locale/index.js:52-58](file://packages/locale/index.js#L52-L58)
- [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/index.js:23-28](file://packages/index.js#L23-L28)
- [packages/index.js:49-57](file://packages/index.js#L49-L57)

## 架构总览
国际化系统由“应用级 i18n 实例”、“组件库内部国际化模块”、“语言包”、“组件混入”、“插件入口”五部分协同组成。其交互关系如下：

```mermaid
sequenceDiagram
participant App as "应用入口"
participant I18n as "应用级 i18n 实例"
participant Plugin as "组件库插件"
participant Locale as "内部国际化模块"
participant Mixin as "组件混入"
participant UI as "组件"
App->>I18n : 创建并配置实例
App->>Plugin : app.use(插件)
Plugin->>Locale : 调用 locale.use(可选)
Plugin->>Locale : 调用 locale.i18n(可选)
UI->>Mixin : 使用 $t/t 方法
Mixin->>Locale : 调用 t(path, options)
Locale->>I18n : 优先从外部 i18n 获取翻译
Locale->>Locale : 若无外部 i18n，则回退到本地语言包
```

图表来源
- [src/locale/index.js:8-18](file://src/locale/index.js#L8-L18)
- [packages/index.js:23-28](file://packages/index.js#L23-L28)
- [packages/locale/index.js:12-33](file://packages/locale/index.js#L12-L33)
- [packages/mixin/locale.js:5-16](file://packages/mixin/locale.js#L5-L16)

## 详细组件分析

### locale.use(lang)
- 作用：切换内部使用的语言对象（lang），用于回退翻译路径
- 行为：若传入空值则保持当前语言对象不变
- 典型场景：在插件安装时或运行期动态切换语言包
- 注意事项：仅影响回退路径；若已注入外部 i18n，优先走外部翻译

章节来源
- [packages/locale/index.js:52-54](file://packages/locale/index.js#L52-L54)
- [packages/index.js:23-25](file://packages/index.js#L23-L25)

### locale.i18n(initI18n)
- 作用：注入外部 i18n 实例（通常为应用级 i18n 实例）
- 行为：内部通过该实例获取当前语言与翻译函数；同时合并本地语言包与外部消息
- 典型场景：在插件安装时传入应用级 i18n 实例，确保组件内翻译与应用一致

章节来源
- [packages/locale/index.js:56-58](file://packages/locale/index.js#L56-L58)
- [packages/index.js:26-28](file://packages/index.js#L26-L28)

### locale.lang(code)
- 作用：根据传入的区域码尝试加载并切换语言包
- 行为：从全局命名空间读取语言包对象，若区域码匹配则调用 locale.use 切换；否则输出提示信息
- 典型场景：运行期动态加载指定语言包并切换

章节来源
- [packages/index.js:53-57](file://packages/index.js#L53-L57)

### t(path, options)
- 作用：统一的翻译入口，优先从外部 i18n 获取翻译，其次回退到本地语言包
- 优先级与回退逻辑：
  - 若当前上下文存在 $t 或外部 i18n 实例，优先调用外部翻译
  - 若外部 i18n 存在且 locale 发生变化，会合并本地语言包与外部消息，并缓存结果
  - 若外部翻译不可用，则按点分路径从当前语言对象中查找
  - 最终通过格式化器对占位符进行替换
- 性能要点：通过 merged 缓存与 nowLang 标记避免重复合并

```mermaid
flowchart TD
Start(["进入 t(path, options)"]) --> CheckExternal["检查是否存在外部 i18n 与 $t"]
CheckExternal --> |有| UseExternal["调用外部翻译"]
CheckExternal --> |无| CheckLocaleChange["检查 locale 是否变更"]
CheckLocaleChange --> |变更| MergeMsg["合并本地语言包与外部消息"]
MergeMsg --> SetCache["更新缓存与 nowLang 标记"]
SetCache --> UseExternal
CheckLocaleChange --> |未变更| UseExternal
UseExternal --> Found{"返回值有效？"}
Found --> |是| Return1["返回翻译结果"]
Found --> |否| LookupLocal["按路径查找本地语言对象"]
LookupLocal --> Format["格式化占位符"]
Format --> Return2["返回格式化结果"]
```

图表来源
- [packages/locale/index.js:12-33](file://packages/locale/index.js#L12-L33)
- [packages/locale/index.js:35-50](file://packages/locale/index.js#L35-L50)
- [packages/locale/format.js:9-49](file://packages/locale/format.js#L9-L49)

章节来源
- [packages/locale/index.js:35-50](file://packages/locale/index.js#L35-L50)
- [packages/locale/format.js:9-49](file://packages/locale/format.js#L9-L49)

### 语言包结构与自定义语言包开发
- 结构规范
  - 顶层包含 pro.locale 与业务命名空间（如 common、table、tableEdit）
  - 建议与第三方 UI 组件库语言包保持一致的键名，便于合并
- 开发步骤
  - 新建对应区域代码的语言包文件（如 zh-CN、en-US、fr-FR、tr-TR 等）
  - 在文件中定义 pro.locale 与各业务命名空间下的键值
  - 在插件安装时通过 locale.use 或运行期通过 lang(code) 加载并切换
- 示例参考
  - 中文语言包：[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/lang/fr-FR.js:1-49](file://packages/locale/lang/fr-FR.js#L1-L49)
  - 土耳其语语言包：[packages/locale/lang/tr-TR.js:1-48](file://packages/locale/lang/tr-TR.js#L1-L48)
  - lib 下法语与土耳其语语言包示例：[lib/locales/fr-FR.js:1-49](file://lib/locales/fr-FR.js#L1-L49)，[lib/locales/tr-TR.js:1-48](file://lib/locales/tr-TR.js#L1-L48)

章节来源
- [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/lang/fr-FR.js:1-49](file://packages/locale/lang/fr-FR.js#L1-L49)
- [packages/locale/lang/tr-TR.js:1-48](file://packages/locale/lang/tr-TR.js#L1-L48)
- [lib/locales/fr-FR.js:1-49](file://lib/locales/fr-FR.js#L1-L49)
- [lib/locales/tr-TR.js:1-48](file://lib/locales/tr-TR.js#L1-L48)

### 动态语言切换与性能优化
- 切换机制
  - 通过 locale.use 切换语言对象，或通过 lang(code) 从全局加载并切换
  - 当外部 i18n 的 locale 发生变化时，内部会合并本地语言包与外部消息，并缓存以避免重复计算
- 性能优化建议
  - 合并策略：仅在 locale 变更或首次访问时执行合并，利用 merged 与 nowLang 标记
  - 消息缓存：通过 setLocaleMessage 将合并后的消息写回外部 i18n，减少后续查找成本
  - 占位符格式化：使用 format 函数进行一次性格式化，避免重复解析

章节来源
- [packages/locale/index.js:19-31](file://packages/locale/index.js#L19-L31)
- [packages/locale/index.js:20-30](file://packages/locale/index.js#L20-L30)
- [packages/locale/format.js:9-49](file://packages/locale/format.js#L9-L49)

### 国际化与组件的集成方式
- 组件混入
  - 通过 $t 与 t 方法在组件中统一调用翻译函数
  - 在组件生命周期中自动绑定当前上下文，保证 this 指向正确
- 插件安装
  - 在插件安装时，根据传入配置调用 locale.use 与 locale.i18n，确保组件内翻译与应用一致

```mermaid
classDiagram
class LocaleModule {
+t(path, options)
+use(lang)
+i18n(initI18n)
}
class Mixin {
+$t(...args)
+methods.t(...args)
}
class Plugin {
+install(app, opts)
+locale
+i18n
+lang
}
Mixin --> LocaleModule : "调用 t"
Plugin --> LocaleModule : "use/i18n"
```

图表来源
- [packages/locale/index.js:35-58](file://packages/locale/index.js#L35-L58)
- [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)
- [packages/index.js:23-28](file://packages/index.js#L23-L28)

章节来源
- [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/index.js:23-28](file://packages/index.js#L23-L28)

### 配置选项与加载策略
- 应用级 i18n 配置
  - 在应用入口创建 i18n 实例，设置默认语言与消息合并
  - 将第三方 UI 组件库语言包与组件库自身语言包合并
- 插件级配置
  - 在插件安装时传入 locale 与 i18n，分别用于切换语言对象与注入外部 i18n
  - 通过 lang(code) 运行期动态加载语言包并切换
- 加载与缓存策略
  - 合并策略：本地语言包与外部消息合并，写回外部 i18n 以提升后续访问性能
  - 缓存策略：通过 merged 与 nowLang 标记避免重复合并

章节来源
- [src/locale/index.js:8-18](file://src/locale/index.js#L8-L18)
- [packages/index.js:23-28](file://packages/index.js#L23-L28)
- [packages/locale/index.js:19-31](file://packages/locale/index.js#L19-L31)

## 依赖分析
- 组件库内部国际化模块依赖语言包与格式化器
- 组件通过混入使用翻译函数
- 插件负责在安装时完成初始化与注入
- 应用级 i18n 实例负责提供外部翻译能力并与内部模块协作

```mermaid
graph LR
Lang["语言包集合"] --> Locale["内部国际化模块"]
Format["格式化器"] --> Locale
Mixin["组件混入"] --> Locale
Plugin["插件入口"] --> Locale
AppI18n["应用级 i18n 实例"] --> Locale
```

图表来源
- [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/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/index.js:1-69](file://packages/index.js#L1-L69)
- [src/locale/index.js:1-18](file://src/locale/index.js#L1-L18)

章节来源
- [packages/locale/index.js:1-64](file://packages/locale/index.js#L1-L64)
- [packages/index.js:1-69](file://packages/index.js#L1-L69)
- [src/locale/index.js:1-18](file://src/locale/index.js#L1-L18)

## 性能考虑
- 合并与缓存
  - 仅在 locale 变更时执行合并，避免重复计算
  - 合并后的消息写回外部 i18n，减少后续查找成本
- 字符串格式化
  - 使用 format 函数进行占位符替换，避免重复解析
- 语言包体积
  - 按需加载语言包，避免一次性加载全部语言包造成首屏压力

## 故障排查指南
- 外部 i18n 未注入
  - 现象：组件内翻译回退到本地语言包
  - 处理：在插件安装时传入 i18n 实例，或在运行期调用 locale.i18n
- 语言包未加载
  - 现象：lang(code) 输出提示信息
  - 处理：确认全局命名空间中存在对应语言包对象，且区域码匹配
- 翻译键缺失
  - 现象：返回空字符串或占位符未替换
  - 处理：检查语言包结构与键名，确保与第三方 UI 组件库保持一致

章节来源
- [packages/locale/index.js:12-33](file://packages/locale/index.js#L12-L33)
- [packages/index.js:53-57](file://packages/index.js#L53-L57)

## 结论
Pro-IVIEW V3 的国际化体系通过“应用级 i18n 实例 + 组件库内部国际化模块 + 语言包 + 组件混入 + 插件入口”的组合，实现了灵活、可扩展且高性能的多语言支持。开发者可通过 locale.use、locale.i18n、locale.lang 快速集成与切换语言包，并遵循语言包结构与合并策略，确保翻译一致性与性能表现。

## 附录
- API 一览
  - locale.use(lang)：切换语言对象
  - locale.i18n(initI18n)：注入外部 i18n 实例
  - locale.lang(code)：按区域码加载并切换语言包
  - t(path, options)：统一翻译入口，优先外部 i18n，其次本地语言包
- 语言包示例
  - 中文：[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/lang/fr-FR.js:1-49](file://packages/locale/lang/fr-FR.js#L1-L49)
  - 土耳其语：[packages/locale/lang/tr-TR.js:1-48](file://packages/locale/lang/tr-TR.js#L1-L48)
- lib 下语言包示例
  - 法语：[lib/locales/fr-FR.js:1-49](file://lib/locales/fr-FR.js#L1-L49)
  - 土耳其语：[lib/locales/tr-TR.js:1-48](file://lib/locales/tr-TR.js#L1-L48)