# 需求文档：UI文案国际化（i18n）

## 引言

《坦克探险》微信小游戏需要支持中英文双语UI。根据用户所在区域自动展示对应语言的文案，中文地区显示中文，其他地区显示英文。

---

## 技术方案

### 1. i18n 模块结构

在 `js/i18n/` 目录下创建以下文件：

- **`I18n.js`** — 核心管理器，负责语言检测和文案获取
- **`zh.js`** — 中文语言包
- **`en.js`** — 英文语言包

### 2. 语言检测

通过微信 `wx.getSystemInfoSync().language` 自动检测：
- `zh_CN`、`zh_TW`、`zh_HK` 等以 `zh` 开头 → 使用中文
- 其他 → 使用英文（默认 fallback）

### 3. 使用方式

各场景文件通过 `const { t } = require('../i18n/I18n');` 引入翻译函数：
- 简单文案：`t('menu.title')` → `'坦克探险'` / `'Tank Adventure'`
- 带参数模板：`t('pvp.hp', { count: 3 })` → `'生命 x3'` / `'HP x3'`

### 4. Key 命名规范

按场景分组，使用点号分隔：
- `menu.*` — 主菜单
- `room.*` — 双人对战房间
- `teamRoom.*` — 3v3团队房间
- `pvp.*` — 双人对战游戏
- `team.*` — 3v3团队游戏
- `pvpResult.*` — 双人对战结算
- `teamResult.*` — 3v3团队结算
- `game.*` — 经典模式
- `common.*` — 通用文案

---

## 需求

### 需求 1：创建 i18n 核心模块

**用户故事：** 作为开发者，我需要一个 i18n 模块来管理多语言文案，支持自动语言检测和带参数的文案模板。

#### 验收标准

1. 创建 `js/i18n/I18n.js`，提供 `t(key, params)` 函数
2. 创建 `js/i18n/zh.js`，包含所有中文文案
3. 创建 `js/i18n/en.js`，包含所有英文文案
4. 通过 `wx.getSystemInfoSync().language` 自动检测语言
5. 支持 `{variable}` 占位符插值
6. 缺失 key 时 fallback 到英文，仍缺失则返回 key 本身

---

### 需求 2：主菜单场景（MenuScene）i18n 化

#### 验收标准

| Key | 中文 | 英文 |
|-----|------|------|
| `menu.title` | 坦克探险 | Tank Adventure |
| `menu.subtitle` | 经典坦克对战 | TANK WAR |
| `menu.classic` | 经典模式 | Classic |
| `menu.endless` | 无尽模式 | Endless |
| `menu.pvp` | 双人对战 | PVP |
| `menu.team3v3` | 3v3 对战 | 3v3 Battle |
| `menu.ranking` | 排行榜 | Ranking |
| `menu.settings` | 设置 | Settings |

---

### 需求 3：双人对战房间场景（RoomScene）i18n 化

#### 验收标准

| Key | 中文 | 英文 |
|-----|------|------|
| `room.title` | 双人对战 | PVP Battle |
| `room.idleHint` | 创建房间或输入房间号加入 | Create a room or join with a code |
| `room.create` | 创建房间 | Create Room |
| `room.join` | 加入房间 | Join Room |
| `room.connecting` | 连接中{dots} | Connecting{dots} |
| `room.roomCode` | 房间号： | Room Code: |
| `room.waiting` | 等待对手加入{dots} | Waiting for opponent{dots} |
| `room.shareHint` | 将房间号分享给好友 | Share the room code with your friend |
| `room.inputCode` | 输入房间号： | Enter Room Code: |
| `room.opponentFound` | 对手已找到！ | Opponent found! |
| `room.starting` | 即将开始... | Game starting... |
| `room.tapBack` | 点击任意位置返回 | Tap anywhere to go back |
| `common.back` | ← 返回 | ← Back |
| `common.joinBtn` | 加入 | Join |
| `common.cannotConnect` | 无法连接服务器 | Cannot connect to server |
| `common.connectFailed` | 连接失败 | Connection failed |
| `common.disconnected` | 与服务器断开连接 | Disconnected from server |

---

### 需求 4：3v3 团队房间场景（TeamRoomScene）i18n 化

#### 验收标准

| Key | 中文 | 英文 |
|-----|------|------|
| `teamRoom.title` | 3v3 团队对战 | 3v3 Team Battle |
| `teamRoom.chooseMode` | 选择游戏方式 | Choose how to play |
| `teamRoom.createTeam` | 🎮 组队开黑 | 🎮 Create Team |
| `teamRoom.soloMatch` | ⚡ 快速匹配 | ⚡ Quick Match |
| `teamRoom.teamId` | 队伍：{id} | Team: {id} |
| `teamRoom.leader` | 队长 | Leader |
| `teamRoom.ready` | ✓ 已准备 | ✓ Ready |
| `teamRoom.notReady` | 未准备 | Not Ready |
| `teamRoom.emptySlot` | 空位 | Empty |
| `teamRoom.invite` | 📨 邀请好友 | 📨 Invite |
| `teamRoom.startMatch` | 🔍 开始匹配 | 🔍 Start Match |
| `teamRoom.disband` | 解散队伍 | Disband |
| `teamRoom.readyBtn` | ✓ 准备 | ✓ Ready |
| `teamRoom.cancelReady` | 取消准备 | Cancel Ready |
| `teamRoom.leaveTeam` | 退出队伍 | Leave Team |
| `teamRoom.matching` | 匹配中{dots} | Matching{dots} |
| `teamRoom.waitTime` | 已等待 {seconds} 秒 | Waited {seconds}s |
| `teamRoom.cancelMatch` | 取消匹配 | Cancel Match |
| `teamRoom.matchFound` | 对手已找到！ | Match found! |
| `teamRoom.enterBattle` | 即将进入战斗... | Entering battle... |
| `teamRoom.tapBack` | 点击任意位置返回 | Tap anywhere to go back |
| `teamRoom.shareTitle` | 坦克3v3，速来开黑！ | Tank 3v3, join the battle! |
| `common.kicked` | 你已被踢出队伍 | You have been kicked from the team |

---

### 需求 5：双人对战游戏场景（PvpGameScene）i18n 化

#### 验收标准

| Key | 中文 | 英文 |
|-----|------|------|
| `pvp.playerLabel` | P{slot} (我方) | P{slot} (You) |
| `pvp.hp` | 生命 x{count} | HP x{count} |
| `pvp.kills` | 击杀：{count} | Kills: {count} |
| `common.paused` | 暂停 | PAUSED |
| `common.tapContinue` | 点击继续 | Tap to continue |
| `pvp.youWin` | 你赢了！ | YOU WIN! |
| `pvp.draw` | 平局 | DRAW |
| `pvp.youLose` | 你输了 | YOU LOSE |

---

### 需求 6：3v3 团队对战游戏场景（TeamGameScene）i18n 化

#### 验收标准

| Key | 中文 | 英文 |
|-----|------|------|
| `team.teamA` | A队 | Team A |
| `team.teamB` | B队 | Team B |
| `team.myTeam` | 我方：{team}队 | You: {team} Team |
| `team.killDeath` | 杀:{kills} 亡:{deaths} | K:{kills} D:{deaths} |
| `team.respawn` | {seconds}秒后重生 | Respawning in {seconds}s |
| `team.victory` | 胜利！ | VICTORY! |
| `team.defeat` | 失败 | DEFEAT |
| `team.baseHpSummary` | A队：{hpA} 生命  \|  B队：{hpB} 生命 | Team A: {hpA} HP  \|  Team B: {hpB} HP |
| `team.disconnectTitle` | ⚠ 连接断开 | ⚠ Connection Lost |
| `team.reconnecting` | 重连中{dots} ({attempts}/{max}) | Reconnecting{dots} ({attempts}/{max}) |
| `team.reconnectHint` | 请稍候，您的坦克将由AI代管 | Please wait, your tank will be controlled by AI |

---

### 需求 7：双人对战结算场景（PvpResultScene）i18n 化

#### 验收标准

| Key | 中文 | 英文 |
|-----|------|------|
| `pvpResult.title` | 对战结果 | MATCH RESULT |
| `pvpResult.victory` | 🏆 胜利！ | 🏆 VICTORY! |
| `pvpResult.draw` | ⚔️ 平局 | ⚔️ DRAW |
| `pvpResult.defeat` | 💀 失败 | 💀 DEFEAT |
| `pvpResult.kills` | 击杀 | Kills |
| `pvpResult.lives` | 生命 | Lives |
| `pvpResult.timeRemaining` | 剩余时间：{time} | Time remaining: {time} |
| `pvpResult.rematch` | 再来一局 | Rematch |
| `pvpResult.backMenu` | 返回菜单 | Back to Menu |

---

### 需求 8：3v3 团队结算场景（TeamResultScene）i18n 化

#### 验收标准

| Key | 中文 | 英文 |
|-----|------|------|
| `teamResult.title` | 3v3 对战结果 | 3v3 MATCH RESULT |
| `teamResult.victory` | 🏆 胜利！ | 🏆 VICTORY! |
| `teamResult.defeat` | 💀 失败 | 💀 DEFEAT |
| `teamResult.teamAHp` | A队：{hp} 生命 | Team A: {hp} HP |
| `teamResult.teamBHp` | B队：{hp} 生命 | Team B: {hp} HP |
| `teamResult.baseDestroyed` | 基地被摧毁 | Base Destroyed |
| `teamResult.disconnectedReason` | 断线 | Disconnected |
| `teamResult.teamAHeader` | A队 | Team A |
| `teamResult.teamBHeader` | B队 | Team B |
| `teamResult.myTeamSuffix` |  (我方) |  (You) |
| `teamResult.player` | 玩家 | Player |
| `teamResult.k` | 杀 | K |
| `teamResult.d` | 亡 | D |
| `teamResult.a` | 助 | A |
| `teamResult.dmg` | 伤害 | DMG |
| `teamResult.bot` | 🤖 机器人 | 🤖 Bot |
| `teamResult.duration` | 对战时长：{time} | Match duration: {time} |
| `teamResult.mvp` | ⭐ MVP：{name}（{kills} 击杀） | ⭐ MVP: {name} ({kills} kills) |
| `teamResult.rankUp` | 📈 积分 +{points} | 📈 Rank +{points} |
| `teamResult.mvpBonus` | （MVP加成 +5） | (MVP bonus +5) |
| `teamResult.rankDown` | 📉 积分 -{points} | 📉 Rank -{points} |
| `teamResult.rematch` | 再来一局 | Rematch |
| `teamResult.backMenu` | 返回菜单 | Back to Menu |

---

### 需求 9：经典模式游戏场景（GameScene）i18n 化

#### 验收标准

| Key | 中文 | 英文 |
|-----|------|------|
| `game.level` | 第 {level} 关 | Level {level} |
| `game.hp` | 生命 x{count} | HP x{count} |
| `game.fireLevel` | LV{level} | LV{level} |
| `game.enemies` | 敌人: {count} | Enemies: {count} |
| `game.score` | {score}分 | {score}pts |
| `game.gameOver` | 游戏结束 | GAME OVER |
| `game.stageClear` | 关卡通过！ | STAGE CLEAR! |

---

## 边界情况与技术约束

### 边界情况

1. **中文字体渲染**：Canvas 中使用 `'Arial'` 字体渲染中文时，微信小游戏环境下系统会自动 fallback 到系统中文字体，无需额外处理。
2. **文案长度变化**：中英文文案长度不同，替换后需确认UI布局不会溢出或错位。
3. **`GameScene` 中的字符串比较**：`text === '游戏结束'` 改为 `text === t('game.gameOver')`，确保逻辑不受语言影响。
4. **错误消息来源**：部分错误消息可能来自服务端（如 `data.message`），本次仅替换客户端硬编码的文案。

### 技术约束

1. 所有文案替换涉及 `js/scenes/` 目录下的场景文件和新建的 `js/i18n/` 模块。
2. 替换操作不应影响游戏逻辑，仅修改展示层的字符串。
3. 不需要在设置页面增加语言切换选项，完全依赖微信系统语言自动检测。

### 成功标准

1. 中文区域用户看到全中文UI，非中文区域用户看到全英文UI。
2. 替换后游戏功能正常，无因文案修改导致的逻辑错误。
3. 文案在各场景中布局合理，无溢出或错位现象。