# Keyboard 多语言/多布局功能交接文档（给下一个 AI）

## 1. 背景与目标

### 1.1 需求目标
主 App 需要支持：
1. 新增语言：西班牙语、葡萄牙语、繁体中文、印尼语。
2. 切换语言时，键盘输入配置（语言 + 布局）同步切换。
3. 支持多布局语言：
   - 西班牙语：`QWERTY / AZERTY / QWERTZ`
   - 繁体中文（台湾）：`拼音（繁体） / 注音全键盘 / 注音标准`
4. 主 App 切换语言后，给键盘扩展下发该语言默认皮肤（zip 方案）。
5. 交互要求（最新确认）：
   - 在 `Input Language` 界面：
     - 若该语言无多布局：底部显示 `Confirm`，点击后才生效。
     - 若该语言有多布局：隐藏 `Confirm`，进入 `Choose Layout`。
   - 在 `Choose Layout` 界面：底部显示 `Confirm`，点击后才生效。
   - 只有点击 `Confirm` 才触发切换逻辑。

---

## 2. 当前已完成内容（本次已落地）

> 说明：下面这些改动已经在代码中完成。

### 2.1 语言常量与默认支持语言扩展

#### 文件
- `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/KBLocalizationManager.h`
- `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/KBLocalizationManager.m`

#### 已做内容
新增语言常量：
- `KBLanguageCodeTraditionalChinese = @"zh-Hant"`
- `KBLanguageCodeSpanish = @"es"`
- `KBLanguageCodePortuguese = @"pt"`
- `KBLanguageCodeIndonesian = @"id"`

并扩展 `KBDefaultSupportedLanguageCodes()`：
- `en, zh-Hans, zh-Hant, es, pt, id`

---

### 2.2 App Group 键盘配置键新增

#### 文件
- `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/KBConfig.h`

#### 已做内容
新增共享键：
- `AppGroup_SelectedKeyboardProfileId`
- `AppGroup_SelectedKeyboardLanguageCode`
- `AppGroup_SelectedKeyboardLayoutVariant`

用于主 App 写入、扩展读取当前输入配置。

---

### 2.3 个人资料页接入“输入语言”流程（含二级布局页 + Confirm 交互）

#### 文件
- `/Users/mac/Desktop/项目/公司/KeyBoard/keyBoard/Class/Me/VC/KBPersonInfoVC.m`

#### 已做内容
1. 在 section0 新增一行：`Input Language`。
2. 在该文件内新增两个页面类（当前是内嵌实现）：
   - `KBKeyboardLanguageSelectVC`
   - `KBKeyboardLayoutSelectVC`
3. 交互逻辑改为“先选后确认”：
   - 点击列表项仅更新 pending 选中态。
   - 仅点击底部 `Confirm` 才触发 `onSelect`。
4. 语言页按钮显示规则：
   - 单布局语言：显示 `Confirm`。
   - 多布局语言：隐藏 `Confirm`，进入布局页。
5. 选择确认后执行主流程：
   - 写 App Group：`languageCode + layoutVariant + profileId`
   - `[[KBLocalizationManager shared] setCurrentLanguageCode: persist:YES]`
   - 下发默认皮肤请求（`KBSkinInstallBridge publishBundleSkinRequestWithId`）
   - 提示后调用 `setupRootVC` 重建首页。

---

### 2.4 新增文案 key（中英文）

#### 文件
- `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/Localization/en.lproj/Localizable.strings`
- `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/Localization/zh-Hans.lproj/Localizable.strings`

#### 已做内容
新增：
- `"Input Language"`
- `"Choose Layout"`
- `"Multiple Keyboard Layouts"`

---

## 3. 当前实现的配置模型（暂时硬编码在 VC）

> 当前为快速落地，语言-布局-profile 映射硬编码在 `KBPersonInfoVC.m` 的 `languageConfigs` 方法。

### 已配置项
1. `English`:
   - `en_US_qwerty`
2. `Español`:
   - `es_ES_qwerty`
   - `es_ES_azerty`
   - `es_ES_qwertz`
3. `Português`:
   - `pt_PT_qwerty`
4. `繁體中文（台灣）`:
   - `zh_Hant_TW_pinyin`
   - `zh_Hant_TW_bopomofo_full`
   - `zh_Hant_TW_bopomofo_standard`
5. `Bahasa Indonesia`:
   - `id_ID_qwerty`

---

## 4. 默认皮肤下发（当前已接）

#### 入口
`KBPersonInfoVC.m` -> `publishDefaultSkinIfNeededForLanguageCode:`

#### 当前映射
- `zh-Hant` -> `normal_hei_them.zip`
- `es/pt/id/en` -> `normal_them.zip`

#### 调用方式
通过：
- `KBSkinInstallBridge publishBundleSkinRequestWithId:name:zipName:iconShortNames:`

> 注意：这是“发布请求”，扩展侧消费请求逻辑在现有 Theme 类中已存在。

---

## 5. 尚未完成（必须由下一个 AI 继续）

> 目前只完成了“主 App 选择流程 + 数据写入 + 皮肤请求发布”。
> **扩展侧还没有按 `profileId` 真正切换键盘 JSON 布局**。

### 5.1 扩展按 profileId 加载布局 JSON（核心待办）

#### 目标
扩展读取 App Group 的：
- `AppGroup_SelectedKeyboardProfileId`

然后路由到对应 `layoutJsonId`，并加载实际键盘布局。

#### 建议实现
1. 新建 `KBKeyboardLayoutResolver`（扩展侧）
   - 输入：`profileId`
   - 输出：`layoutConfigName`（或 JSON 节点路径）
2. 修改布局加载入口（建议）
   - `CustomKeyboard/View/KBKeyboardView.m`
   - `CustomKeyboard/KeyboardViewControllerHelp/KeyboardViewController+Layout.m`
3. 更新布局配置 JSON
   - `/Users/mac/Desktop/项目/公司/KeyBoard/CustomKeyboard/Resource/kb_keyboard_layout_config.json`
   - 补齐：
     - `latin_es_qwerty`
     - `latin_es_azerty`
     - `latin_es_qwertz`
     - `zh_hant_pinyin_qwerty`
     - `zh_hant_bpmf_full`
     - `zh_hant_bpmf_standard`

---

### 5.2 繁体联想引擎分流（重点）

#### 现状风险
当前联想引擎偏英文/拉丁逻辑，繁体注音联想未打通。

#### 目标
- `zh_Hant_TW_pinyin` -> 繁体拼音联想引擎
- `zh_Hant_TW_bopomofo_*` -> 注音联想引擎

#### 建议改动位置
- `CustomKeyboard/Manager/KBSuggestionEngine.m`
- `CustomKeyboard/KeyboardViewControllerHelp/KeyboardViewController+Suggestions.m`

---

### 5.3 InputProfile 配置中心外置（技术债）

#### 现状
配置硬编码在 `KBPersonInfoVC.m`，不利于扩展复用。

#### 建议
1. 新建共享配置文件：
   - `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/Resource/kb_input_profiles.json`
2. 新建管理器：
   - `KBInputProfileManager`（Shared）
3. 主 App 与扩展统一走此管理器，避免重复映射。

---

### 5.4 本地化资源补齐

#### 现状
仅 `en/zh-Hans` 两套 strings 完整。新增语言目录尚未补齐。

#### 待办
新增并接入：
- `es.lproj`
- `pt.lproj`
- `zh-Hant.lproj`
- `id.lproj`

并在 `project.pbxproj` 中更新 `knownRegions` 与变体组。

---

## 6. 关键行为说明（给接手 AI）

### 6.1 触发逻辑时机
- 现在是“仅 Confirm 才触发”。
- 禁止在 `didSelectRowAtIndexPath` 里直接调用最终切换。

### 6.2 导航回退逻辑
- `openLanguageSelector` 里 `vc.onSelect` 会回调到 `KBPersonInfoVC` 并执行：
  - `applyInputProfileWithLanguageCode:layoutVariant:profileId:`
  - `popToViewController:weakSelf`

### 6.3 兼容注意
- 如果 profile 不合法要回退到 `en_US_qwerty`。
- 如果布局 JSON 不存在，不要崩溃，回退默认布局。
- 皮肤 zip 缺失时不阻断输入流程。

---

## 7. 建议下一步实施顺序（给下一个 AI）

1. **先做扩展布局切换最小闭环**
   - 扩展读取 `profileId`
   - 根据映射切换到不同布局 JSON
2. **再做繁体联想分流**
   - pinyin_traditional / bopomofo 两套策略
3. **再做配置中心外置**
   - 把硬编码配置迁移到 `Shared/Resource/kb_input_profiles.json`
4. **最后补齐多语言 strings + 工程配置**
   - 避免 UI 出现 key 原样文本

---

## 8. 回归测试清单（手测）

### 8.1 主流程
1. 进入个人资料页，看到 `Input Language` 行。
2. 进入语言页，选单布局语言（如葡语）：
   - 底部 `Confirm` 显示
   - 点击语言行不触发切换
   - 点击 `Confirm` 后才触发切换
3. 进入语言页，选多布局语言（如西语/繁体）：
   - 底部 `Confirm` 隐藏
   - 进入 `Choose Layout`
   - 在 `Choose Layout` 点击布局行不触发切换
   - 点击 `Confirm` 后才触发切换

### 8.2 数据落盘
确认 App Group 键值写入：
- `AppGroup_SelectedKeyboardLanguageCode`
- `AppGroup_SelectedKeyboardLayoutVariant`
- `AppGroup_SelectedKeyboardProfileId`

### 8.3 皮肤请求
切语言后确认已发布 pending 皮肤请求（扩展可消费）。

### 8.4 异常回退
- profileId 空值
- layoutVariant 空值
- zip 名不存在
都不应导致崩溃。

---

## 9. 已知问题 / 风险

1. 目前语言配置写在 `KBPersonInfoVC.m`，应尽快抽离。
2. 扩展侧尚未接 profileId -> layout JSON，当前只是主 App 流程完成。
3. 本次环境无法可靠运行 xcodebuild 完整编译验证（沙箱限制）。
4. `KBLocalized(@"Choose")` 在现有 strings 中可能无 key，可能出现英文 key 原样显示（建议补 key）。

---

## 10. 本次变更文件清单

1. `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/KBConfig.h`
2. `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/KBLocalizationManager.h`
3. `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/KBLocalizationManager.m`
4. `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/Localization/en.lproj/Localizable.strings`
5. `/Users/mac/Desktop/项目/公司/KeyBoard/Shared/Localization/zh-Hans.lproj/Localizable.strings`
6. `/Users/mac/Desktop/项目/公司/KeyBoard/keyBoard/Class/Me/VC/KBPersonInfoVC.m`

---

## 11. 给下一个 AI 的一句话任务描述（可直接复制）

“请基于现有主 App 已完成的语言/布局选择与 Confirm 触发流程，继续完成扩展侧按 `AppGroup_SelectedKeyboardProfileId` 切换键盘 JSON 布局，并实现繁体拼音与注音（全键盘/标准）的联想引擎分流，同时将 `KBPersonInfoVC.m` 中硬编码语言配置抽离到 `Shared/Resource/kb_input_profiles.json + KBInputProfileManager`。”