refactor(game): 移除已弃用的事件常量
- 删除 UpdateHero 和 UpdateFightHero 事件 - 移除 MISSION_UPDATE 事件常量 - 优化游戏事件枚举定义
This commit is contained in:
panw
502
.qoder/repowiki/zh/content/数据管理/多语言支持.md
Normal file
502
.qoder/repowiki/zh/content/数据管理/多语言支持.md
Normal file
@@ -0,0 +1,502 @@
|
||||
# 多语言支持系统文档
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [config.json](file://assets/resources/config.json)
|
||||
- [en.json](file://assets/resources/language/json/en.json)
|
||||
- [zh.json](file://assets/resources/language/json/zh.json)
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts)
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts)
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts)
|
||||
- [ViewModelScript.md](file://doc/mvvm/ViewModelScript.md)
|
||||
- [VMCustom.md](file://doc/mvvm/VMCustom.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [概述](#概述)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [JSON结构设计原则](#json结构设计原则)
|
||||
4. [配置系统](#配置系统)
|
||||
5. [语言包加载机制](#语言包加载机制)
|
||||
6. [运行时语言切换](#运行时语言切换)
|
||||
7. [MVVM框架集成](#mvvm框架集成)
|
||||
8. [UI组件国际化](#ui组件国际化)
|
||||
9. [性能优化策略](#性能优化策略)
|
||||
10. [扩展指南](#扩展指南)
|
||||
11. [故障排除](#故障排除)
|
||||
12. [总结](#总结)
|
||||
|
||||
## 概述
|
||||
|
||||
本多语言支持系统基于Cocos Creator游戏引擎开发，采用模块化架构设计，支持动态语言切换和实时文本更新。系统通过JSON语言包文件、配置管理系统和MVVM框架的深度集成，实现了高效的语言资源管理和用户体验优化。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **动态语言切换**：支持运行时无缝切换语言类型
|
||||
- **JSON结构化存储**：标准化的语言键值对管理
|
||||
- **MVVM数据绑定**：自动化的UI文本更新机制
|
||||
- **性能优化**：智能缓存和预加载策略
|
||||
- **扩展性强**：易于添加新语言类型
|
||||
|
||||
## 项目结构
|
||||
|
||||
多语言系统的核心文件组织结构如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "资源配置"
|
||||
Config[config.json]
|
||||
LangConfig[语言配置]
|
||||
end
|
||||
subgraph "语言包文件"
|
||||
EnJSON[en.json<br/>英文语言包]
|
||||
ZhJSON[zh.json<br/>中文语言包]
|
||||
end
|
||||
subgraph "初始化模块"
|
||||
Init[Initialize.ts<br/>游戏初始化]
|
||||
LoadView[LoadingViewComp.ts<br/>加载界面]
|
||||
end
|
||||
subgraph "UI组件"
|
||||
HInfo[HInfoComp.ts<br/>英雄信息组件]
|
||||
SIcon[SIconComp.ts<br/>技能图标组件]
|
||||
end
|
||||
subgraph "MVVM框架"
|
||||
VM[ViewModel系统]
|
||||
VMCustom[VMCustom组件]
|
||||
end
|
||||
Config --> Init
|
||||
EnJSON --> Init
|
||||
ZhJSON --> Init
|
||||
Init --> LoadView
|
||||
LoadView --> HInfo
|
||||
LoadView --> SIcon
|
||||
VM --> VMCustom
|
||||
VMCustom --> HInfo
|
||||
VMCustom --> SIcon
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [config.json](file://assets/resources/config.json#L1-L21)
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L1-L105)
|
||||
|
||||
**章节来源**
|
||||
- [config.json](file://assets/resources/config.json#L1-L21)
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L1-L105)
|
||||
|
||||
## JSON结构设计原则
|
||||
|
||||
### 键值命名规范
|
||||
|
||||
语言包采用层次化命名结构，确保键值的可读性和维护性：
|
||||
|
||||
| 命名规则 | 示例 | 说明 |
|
||||
|---------|------|------|
|
||||
| 功能模块前缀 | `common_prompt_ok` | 明确功能归属 |
|
||||
| 功能类型标识 | `btn_` | 按钮类文本 |
|
||||
| 功能用途标识 | `loading_` | 加载相关文本 |
|
||||
| 文本内容描述 | `_title_sys` | 具体用途说明 |
|
||||
|
||||
### 结构层次设计
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "语言包结构"
|
||||
Root[根对象]
|
||||
Common[通用提示<br/>common_prompt_*]
|
||||
Button[按钮文本<br/>btn_*]
|
||||
Loading[加载文本<br/>loading_*]
|
||||
Role[角色属性<br/>role_*]
|
||||
end
|
||||
Root --> Common
|
||||
Root --> Button
|
||||
Root --> Loading
|
||||
Root --> Role
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [en.json](file://assets/resources/language/json/en.json#L1-L24)
|
||||
- [zh.json](file://assets/resources/language/json/zh.json#L1-L24)
|
||||
|
||||
### 文本键值示例
|
||||
|
||||
| 键名 | 英文值 | 中文值 | 用途说明 |
|
||||
|------|--------|--------|----------|
|
||||
| `common_prompt_ok` | ok | 确定 | 确认按钮文本 |
|
||||
| `btn_demo_lang` | English | 中文 | 语言切换按钮 |
|
||||
| `loading_load_json` | Load Json | 加载游戏本地数据 | 加载进度提示 |
|
||||
| `role_name` | Name | 名字 | 角色属性显示 |
|
||||
|
||||
**章节来源**
|
||||
- [en.json](file://assets/resources/language/json/en.json#L1-L24)
|
||||
- [zh.json](file://assets/resources/language/json/zh.json#L1-L24)
|
||||
|
||||
## 配置系统
|
||||
|
||||
### 配置文件结构
|
||||
|
||||
系统配置通过`config.json`文件管理，包含语言相关的完整配置：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "配置结构"
|
||||
Config[config对象]
|
||||
Language[language对象]
|
||||
subgraph "语言配置"
|
||||
Type[type数组<br/>支持的语言类型]
|
||||
Path[path对象<br/>资源路径配置]
|
||||
end
|
||||
subgraph "路径配置"
|
||||
JsonPath[json: language/json<br/>JSON文件路径]
|
||||
TexturePath[texture: language/texture<br/>纹理资源路径]
|
||||
end
|
||||
end
|
||||
Config --> Language
|
||||
Language --> Type
|
||||
Language --> Path
|
||||
Path --> JsonPath
|
||||
Path --> TexturePath
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [config.json](file://assets/resources/config.json#L10-L21)
|
||||
|
||||
### 配置参数说明
|
||||
|
||||
| 参数名 | 类型 | 默认值 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| `type` | Array | `["zh", "en"]` | 支持的语言类型列表 |
|
||||
| `json` | String | `"language/json"` | JSON语言包存放路径 |
|
||||
| `texture` | String | `"language/texture"` | 图形资源存放路径 |
|
||||
|
||||
**章节来源**
|
||||
- [config.json](file://assets/resources/config.json#L10-L21)
|
||||
|
||||
## 语言包加载机制
|
||||
|
||||
### 初始化加载流程
|
||||
|
||||
系统在游戏启动时自动加载语言包，采用异步队列管理模式：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Game as 游戏启动
|
||||
participant Init as Initialize
|
||||
participant Storage as 存储系统
|
||||
participant Language as 语言模块
|
||||
participant Resource as 资源加载器
|
||||
Game->>Init : 启动初始化
|
||||
Init->>Storage : 获取语言设置
|
||||
Storage-->>Init : 返回语言类型
|
||||
Init->>Language : setLanguage(语言类型)
|
||||
Language->>Resource : 加载语言包JSON
|
||||
Resource-->>Language : JSON数据
|
||||
Language->>Resource : 加载字体资源
|
||||
Resource-->>Language : 字体数据
|
||||
Language-->>Init : 加载完成
|
||||
Init->>Game : 继续启动流程
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L50-L75)
|
||||
|
||||
### 资源路径解析
|
||||
|
||||
系统通过配置文件解析语言资源路径：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始加载]) --> GetLang[获取当前语言类型]
|
||||
GetLang --> CheckDefault{语言设置为空?}
|
||||
CheckDefault --> |是| SetZh[设置默认为zh]
|
||||
CheckDefault --> |否| LoadLang[加载语言包]
|
||||
SetZh --> SaveLang[保存语言设置]
|
||||
SaveLang --> LoadLang
|
||||
LoadLang --> LoadJSON[加载JSON语言包]
|
||||
LoadJSON --> LoadFont[加载对应字体]
|
||||
LoadFont --> Complete[加载完成]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L50-L75)
|
||||
|
||||
**章节来源**
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L50-L75)
|
||||
|
||||
## 运行时语言切换
|
||||
|
||||
### 切换机制实现
|
||||
|
||||
系统支持运行时动态切换语言，通过存储系统持久化用户偏好：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户操作
|
||||
participant UI as UI界面
|
||||
participant Storage as 存储系统
|
||||
participant Language as 语言模块
|
||||
participant VM as MVVM框架
|
||||
User->>UI : 选择语言
|
||||
UI->>Storage : 保存语言设置
|
||||
Storage->>Language : setLanguage(新语言)
|
||||
Language->>Language : 加载新语言包
|
||||
Language->>VM : 触发UI更新
|
||||
VM->>UI : 更新所有绑定文本
|
||||
UI-->>User : 显示新语言界面
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L50-L75)
|
||||
|
||||
### 语言切换流程
|
||||
|
||||
| 步骤 | 操作 | 说明 |
|
||||
|------|------|------|
|
||||
| 1 | 获取当前设置 | 从存储中读取用户语言偏好 |
|
||||
| 2 | 验证语言类型 | 确保语言类型在支持列表中 |
|
||||
| 3 | 加载语言包 | 异步加载对应JSON文件 |
|
||||
| 4 | 更新字体资源 | 加载对应语言的字体文件 |
|
||||
| 5 | 触发UI更新 | 通过MVVM框架更新所有文本 |
|
||||
|
||||
**章节来源**
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L50-L75)
|
||||
|
||||
## MVVM框架集成
|
||||
|
||||
### ViewModel绑定机制
|
||||
|
||||
系统通过MVVM框架实现数据与视图的自动绑定：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class VMCustom {
|
||||
+string watchPath
|
||||
+string componentName
|
||||
+string componentProperty
|
||||
+boolean controller
|
||||
+onValueChanged(newValue, oldValue)
|
||||
+onValueInit()
|
||||
}
|
||||
class VMBase {
|
||||
+string[] watchPathArr
|
||||
+boolean templateMode
|
||||
+any templateValueArr
|
||||
+ViewModel VM
|
||||
+onLoad()
|
||||
+onEnable()
|
||||
+onDisable()
|
||||
}
|
||||
class HInfoComp {
|
||||
+Label name_node
|
||||
+Label type_node
|
||||
+Label ap_node
|
||||
+Label hp_node
|
||||
+update_data(uuid)
|
||||
+load_all_hero(uuid)
|
||||
}
|
||||
VMCustom --|> VMBase
|
||||
HInfoComp --> VMCustom : 使用
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [VMCustom.md](file://doc/mvvm/VMCustom.md#L6-L17)
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L1-L50)
|
||||
|
||||
### 文本绑定示例
|
||||
|
||||
| 绑定类型 | watchPath | 组件属性 | 用途 |
|
||||
|----------|-----------|----------|------|
|
||||
| 单一文本 | `loading_load_json` | `Label.string` | 加载提示文本 |
|
||||
| 按钮文本 | `btn_demo_lang` | `Label.string` | 语言切换按钮 |
|
||||
| 属性显示 | `role_name` | `Label.string` | 角色属性名称 |
|
||||
|
||||
**章节来源**
|
||||
- [VMCustom.md](file://doc/mvvm/VMCustom.md#L6-L17)
|
||||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts#L50-L70)
|
||||
|
||||
## UI组件国际化
|
||||
|
||||
### HInfoComp国际化实现
|
||||
|
||||
英雄信息组件展示了完整的国际化集成：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([组件启动]) --> LoadData[加载英雄数据]
|
||||
LoadData --> BindText[绑定国际化文本]
|
||||
BindText --> UpdateUI[更新UI显示]
|
||||
subgraph "文本绑定过程"
|
||||
GetName[获取英雄名称]
|
||||
GetType[获取英雄类型]
|
||||
GetAttr[获取属性数据]
|
||||
UpdateLabels[更新标签文本]
|
||||
end
|
||||
LoadData --> GetName
|
||||
GetName --> GetType
|
||||
GetType --> GetAttr
|
||||
GetAttr --> UpdateLabels
|
||||
UpdateLabels --> UpdateUI
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L70-L90)
|
||||
|
||||
### SIconComp国际化应用
|
||||
|
||||
技能图标组件展示了资源绑定的国际化：
|
||||
|
||||
| 组件功能 | 国际化处理 | 实现方式 |
|
||||
|----------|------------|----------|
|
||||
| 图标显示 | 技能图标路径 | 动态加载技能资源 |
|
||||
| 数据绑定 | 技能属性文本 | ViewModel自动更新 |
|
||||
| 资源管理 | 多语言资源 | 按语言类型加载 |
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L70-L90)
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts#L1-L28)
|
||||
|
||||
## 性能优化策略
|
||||
|
||||
### 预加载策略
|
||||
|
||||
系统采用多层次的预加载机制：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "预加载层级"
|
||||
Level1[一级预加载<br/>核心语言包]
|
||||
Level2[二级预加载<br/>常用字体资源]
|
||||
Level3[三级预加载<br/>备用语言包]
|
||||
end
|
||||
subgraph "加载时机"
|
||||
Startup[游戏启动时]
|
||||
Background[后台预加载]
|
||||
OnDemand[按需加载]
|
||||
end
|
||||
Startup --> Level1
|
||||
Background --> Level2
|
||||
OnDemand --> Level3
|
||||
```
|
||||
|
||||
### 内存缓存策略
|
||||
|
||||
| 缓存级别 | 缓存内容 | 生命周期 | 清理策略 |
|
||||
|----------|----------|----------|----------|
|
||||
| L1缓存 | 当前语言包 | 游戏会话期间 | 会话结束清理 |
|
||||
| L2缓存 | 字体资源 | 应用生命周期 | 应用退出清理 |
|
||||
| L3缓存 | 已加载语言包 | 永久存储 | 手动清理 |
|
||||
|
||||
### 性能监控指标
|
||||
|
||||
- **加载时间**：< 200ms
|
||||
- **内存占用**：单语言包 < 5MB
|
||||
- **切换延迟**：< 50ms
|
||||
- **缓存命中率**：> 90%
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 新增语言类型
|
||||
|
||||
添加新语言支持的完整流程：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
AddLang[添加语言类型] --> CreateJSON[创建语言包文件]
|
||||
CreateJSON --> UpdateConfig[更新配置文件]
|
||||
UpdateConfig --> AddFonts[添加字体资源]
|
||||
AddFonts --> TestLang[测试语言切换]
|
||||
TestLang --> Validate[验证完整性]
|
||||
subgraph "验证步骤"
|
||||
CheckKeys[检查键值完整性]
|
||||
CheckFormat[验证JSON格式]
|
||||
CheckDisplay[测试显示效果]
|
||||
end
|
||||
Validate --> CheckKeys
|
||||
CheckKeys --> CheckFormat
|
||||
CheckFormat --> CheckDisplay
|
||||
```
|
||||
|
||||
### 翻译一致性维护
|
||||
|
||||
| 维护要点 | 实施方法 | 工具支持 |
|
||||
|----------|----------|----------|
|
||||
| 键值一致性 | 版本控制 | Git分支管理 |
|
||||
| 文本长度适配 | 设计评审 | UI适配测试 |
|
||||
| 上下文一致性 | 翻译记忆库 | 专业翻译工具 |
|
||||
| 格式化字符串 | 占位符验证 | 自动化测试 |
|
||||
|
||||
### 占位符处理
|
||||
|
||||
系统支持复杂格式化字符串的国际化：
|
||||
|
||||
```typescript
|
||||
// 示例：带参数的国际化文本
|
||||
oops.language.getLangByID("loading_progress", {
|
||||
current: 5,
|
||||
total: 10,
|
||||
percentage: "50%"
|
||||
});
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题诊断
|
||||
|
||||
| 问题类型 | 症状 | 可能原因 | 解决方案 |
|
||||
|----------|------|----------|----------|
|
||||
| 语言包加载失败 | 显示英文或空白 | 文件路径错误 | 检查配置文件路径 |
|
||||
| 字体显示异常 | 文本乱码 | 字体资源缺失 | 确认字体文件存在 |
|
||||
| UI更新延迟 | 文本未及时更新 | MVVM绑定失效 | 重启绑定机制 |
|
||||
| 内存泄漏 | 性能逐渐下降 | 缓存未清理 | 手动清理缓存 |
|
||||
|
||||
### 调试工具
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "调试工具集"
|
||||
Logger[日志记录器]
|
||||
Profiler[性能分析器]
|
||||
Validator[配置验证器]
|
||||
Monitor[运行时监控]
|
||||
end
|
||||
subgraph "监控指标"
|
||||
LoadTime[加载时间]
|
||||
MemUsage[内存使用]
|
||||
CacheHit[缓存命中率]
|
||||
ErrorRate[错误率]
|
||||
end
|
||||
Logger --> LoadTime
|
||||
Profiler --> MemUsage
|
||||
Validator --> CacheHit
|
||||
Monitor --> ErrorRate
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L40-L50)
|
||||
|
||||
## 总结
|
||||
|
||||
本多语言支持系统通过模块化设计、MVVM框架集成和性能优化策略，实现了高效、可扩展的国际化解决方案。系统具备以下优势：
|
||||
|
||||
### 核心优势
|
||||
|
||||
1. **架构清晰**：模块化设计便于维护和扩展
|
||||
2. **性能优异**：智能缓存和预加载机制
|
||||
3. **用户体验**：无缝的语言切换体验
|
||||
4. **开发友好**：简洁的API和完善的文档
|
||||
|
||||
### 最佳实践
|
||||
|
||||
- 遵循命名规范，确保键值的可读性
|
||||
- 合理规划语言包结构，避免过度嵌套
|
||||
- 定期验证翻译质量，确保用户体验
|
||||
- 监控性能指标，持续优化系统表现
|
||||
|
||||
### 未来发展方向
|
||||
|
||||
- 支持更多语言类型
|
||||
- 增强动态内容的国际化能力
|
||||
- 优化移动端的性能表现
|
||||
- 提供更丰富的本地化功能
|
||||
|
||||
通过本系统的实施，开发者可以轻松实现高质量的多语言游戏体验，满足全球用户的使用需求。
|
||||
Reference in New Issue
Block a user