zw/keyboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2d02e059562fc6cde26a9a14a4cf6fc5202a1572
keyboard/docs/keyboard-language-layout-handover.md
CodeST 781e557e80 1
2026-03-02 09:19:06 +08:00

9.5 KiB
Raw Blame History

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 View Git Blame Copy Permalink