300 lines
9.5 KiB
Markdown
300 lines
9.5 KiB
Markdown
# 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`。”
|
||
|