zw/keyboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a61f505f70cb49c761dba16855a561711f4f9a7c
keyboard/docs/keyboard-language-layout-handover.md

300 lines
9.5 KiB
Markdown
Raw Normal View History

1
2026-03-02 09:19:06 +08:00
# 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`。”
Reference in New Issue Copy Permalink