keyboard/docs/keyboard-language-layout-implementation-summary.md

键盘多语言/多布局功能实现总结

已完成的工作

1. 配置中心外置 ✅

• ✅ 创建 /Shared/Resource/kb_input_profiles.json 配置文件
• ✅ 创建 KBInputProfileManager 管理器（Shared）
• ✅ 支持的语言和布局：
  • 英语：QWERTY
  • 西班牙语：QWERTY / AZERTY / QWERTZ
  • 葡萄牙语：QWERTY
  • 繁体中文：拼音（繁体）/ 注音全键盘 / 注音标准
  • 印尼语：QWERTY
  • 简体中文：QWERTY

2. 布局 JSON 配置补充 ✅

• ✅ 在 kb_keyboard_layout_config.json 中新增：
  • letters_azerty：AZERTY 布局（西班牙语）
  • letters_qwertz：QWERTZ 布局（西班牙语）
  • letters_bopomofo_full：繁体注音全键盘布局
  • letters_bopomofo_standard：繁体注音标准布局

3. 扩展侧布局切换 ✅

• ✅ 创建 KBKeyboardLayoutResolver（扩展侧）
  • 从 App Group 读取 profileId
  • 根据 profileId 解析对应的 layoutJsonId
  • 根据 profileId 解析对应的联想引擎类型
• ✅ 修改 KBKeyboardView：
  • 新增 currentLayoutJsonId 属性
  • 新增 reloadLayoutWithProfileId: 方法
  • 初始化时从 App Group 读取 profileId 并加载对应布局
• ✅ 修改 KBKeyBoardMainView：
  • 新增 reloadLayoutWithProfileId: 方法
• ✅ 修改 KeyboardViewController：
  • 新增 kb_checkAndApplyLayoutIfNeeded 方法
  • 在 viewDidLoad 和 viewDidLayoutSubviews 中检查并应用布局
  • 检测到 profileId 变化时自动切换布局

4. 主 App 配置管理器集成 ✅

• ✅ 修改 KBPersonInfoVC.m：
  • 使用 KBInputProfileManager 替代硬编码配置
  • 皮肤下发逻辑使用配置管理器

5. 繁体联想引擎分流 ✅

• ✅ 扩展 KBSuggestionEngine：
  • 新增 KBSuggestionEngineType 枚举
  • 支持 4 种引擎类型：Latin / PinyinSimplified / PinyinTraditional / Bopomofo
  • 实现 setEngineTypeFromString: 方法
  • 实现各引擎类型的联想逻辑（基础框架）
• ✅ 修改 KeyboardViewController：
  • 实现 kb_updateSuggestionEngineType: 方法
  • 切换布局时自动切换联想引擎

待完成的工作

1. 将新增文件添加到 Xcode 工程 ⚠️

操作指南: 参考 docs/xcode-file-addition-guide.md

需要添加的文件：

• Shared/Resource/kb_input_profiles.json（主 App + 扩展）
• Shared/KBInputProfileManager.h（主 App + 扩展）
• Shared/KBInputProfileManager.m（主 App + 扩展）
• CustomKeyboard/Manager/KBKeyboardLayoutResolver.h（扩展）
• CustomKeyboard/Manager/KBKeyboardLayoutResolver.m（扩展）

2. 完善联想引擎实现 ⚠️

当前状态: 已实现基础框架，但联想词库需要完善

需要完善的部分:

• 繁体拼音联想：实现拼音到繁体字的映射
• 注音联想：实现注音符号到繁体字的映射
• 简体拼音联想：实现拼音到简体字的映射
• 加载更完整的中文词库

建议实现方式:

1. 创建拼音/注音到汉字的映射表（可以使用 JSON 或 plist 文件）
2. 在 kb_traditionalPinyinSuggestionsForPrefix: 中实现拼音匹配逻辑
3. 在 kb_bopomofoSuggestionsForPrefix: 中实现注音匹配逻辑
4. 可以考虑集成第三方拼音/注音输入法库

3. 本地化资源补齐 ⚠️

需要新增并接入：

• es.lproj/Localizable.strings（西班牙语）
• pt.lproj/Localizable.strings（葡萄牙语）
• zh-Hant.lproj/Localizable.strings（繁体中文）
• id.lproj/Localizable.strings（印尼语）

并在 project.pbxproj 中更新 knownRegions。

4. 完整测试 ⚠️

测试清单: 参考 docs/testing-checklist.md

主要测试项：

• 主 App 语言选择流程
• 扩展侧布局切换
• 联想引擎切换
• 皮肤下发
• 异常情况处理
• 性能测试
• 回归测试

主流程测试

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

扩展侧测试

1. 切换到西班牙语 AZERTY：
   • 键盘第一行应显示 azertyuiop
2. 切换到西班牙语 QWERTZ：
   • 键盘第一行应显示 qwertzuiop
3. 切换到繁体注音全键盘：
   • 键盘应显示注音符号
   • 联想功能应使用注音引擎
4. 切换到繁体拼音：
   • 键盘应显示 QWERTY 布局
   • 联想应显示繁体字

数据落盘测试

确认 App Group 键值写入：

• AppGroup_SelectedKeyboardLanguageCode
• AppGroup_SelectedKeyboardLayoutVariant
• AppGroup_SelectedKeyboardProfileId

皮肤测试

切换语言后确认已发布对应的默认皮肤请求。

关键文件清单

新增文件

1. /Shared/Resource/kb_input_profiles.json
2. /Shared/KBInputProfileManager.h
3. /Shared/KBInputProfileManager.m
4. /CustomKeyboard/Manager/KBKeyboardLayoutResolver.h
5. /CustomKeyboard/Manager/KBKeyboardLayoutResolver.m

修改文件

1. /CustomKeyboard/Resource/kb_keyboard_layout_config.json
2. /CustomKeyboard/View/KBKeyboardView.h
3. /CustomKeyboard/View/KBKeyboardView.m
4. /CustomKeyboard/View/KBKeyBoardMainView.h
5. /CustomKeyboard/View/KBKeyBoardMainView.m
6. /CustomKeyboard/KeyboardViewController.m
7. /keyBoard/Class/Me/VC/KBPersonInfoVC.m

注意事项

1. 繁体注音布局：注音符号的排列顺序需要根据实际台湾键盘标准调整
2. 联想引擎：繁体注音联想是核心功能，需要重点实现
3. 回退机制：如果 profileId 不合法，应回退到 en_US_qwerty
4. 布局 JSON 缺失：如果布局 JSON 不存在，不要崩溃，回退到默认布局
5. 皮肤 zip 缺失：皮肤 zip 缺失时不应阻断输入流程

下一步建议

1. 优先级 1：实现繁体联想引擎分流（最关键）
2. 优先级 2：将新增文件添加到 Xcode 工程并编译测试
3. 优先级 3：补齐本地化资源
4. 优先级 4：完整回归测试

给下一个 AI 的任务描述

"请完成繁体中文联想引擎分流功能：在 KBSuggestionEngine.m 中实现 pinyin_traditional（繁体拼音）和 bopomofo（注音）两种联想引擎，并在 KeyboardViewController.m 的 kb_updateSuggestionEngineType: 方法中调用。同时将新增的文件添加到 Xcode 工程中，确保编译通过并进行完整测试。"