SuperAPI AI 工具集

cmux-localization

编程与开发

查看项目

更新于 10-16 00:04

技能介绍

用途:该技能用于 cmux 中任何面向用户字符串的改动,确保界面文案、设置行、菜单、快捷键元数据、schema/配置文本、文档、命令与帮助文本、弹窗、提示等都被正确本地化,并完成本地化审计。

主要能力与流程:贡献者修改或新增用户可见文案后,运行 ./scripts/localize-changes。该命令会比较当前工作区与主线基线,发现变更的 Swift 本地化键和英文 Web 消息,为 macOS 目录准备简单的新增或修改条目,并在 git 元数据下生成机器可读的翻译包。填写简单翻译的 value,或复数/变体条目的 localization,然后再次运行同一命令。若英文变更后已有翻译仍正确,用相同文本填入 value,翻译包会记住该确认,后续运行不再标记为待审。完成的 macOS 行通过 scripts/localization_catalog.py merge 导入,scripts/localization_catalog.py check 是最终权威校验器。可用 --base <ref> 指定其他比较基线,用 --work-file <path> 让翻译助手看到翻译包;默认翻译包位于工作区之外。

硬性规则:每个面向用户的字符串都必须本地化,SwiftUI 的 Text()、Button()、弹窗标题、提示、菜单或对话框中不得使用裸字符串字面量。Swift/AppKit/SwiftUI 使用 String(localized: "key.name", defaultValue: "English text"),键位于 Resources/Localizable.xcstrings。每个功能 PR 需包含 scripts/localization_catalog.py 要求的所有受支持 macOS 语言的翻译条目(当前为 en、de、fr、ar、es、zh-Hant、zh-Hans、ko、ja),除非有精确的省略记录;en 和 ja 条目始终必需。defaultValue、英文回退文本、schema 描述和照抄英文不算本地化。有意保持不变的字符串需记录在 scripts/localization-allowed-omissions.json,并注明确切来源和省略类别。与英文拼写相同的正确翻译需要为该键和语言记录 identityLocales 例外,翻译条目仍然必需。Web/文档内容需更新 web/i18n/routing.ts 声明的每个语言,并配套 web/messages/<locale>.json 条目及任何内联翻译的数据结构。

审计清单:完成涉及 UI、设置行、菜单、快捷键元数据、schema/配置文本、文档、命令/帮助文本、弹窗或提示的任务前,先运行 ./scripts/localize-changes 并解决所有报告的翻译行或需人工关注项;枚举变更的面向用户界面;确认每个界面都有目录键和所有受支持 macOS 语言的翻译值,除非精确省略记录允许缺失(省略记录仍要求 en 和 ja);解析涉及的本地化文件并跨语言比较变更的消息键;对变更的 Swift/TS/TSX/文档文件运行 rg 查找新引入的裸英文;在最终交接中说明执行了哪些审计,或明确说明无法验证的内容。Resources/Localizable.xcstrings、Resources/InfoPlist.xcstrings 及关联的 macOS 包目录必须通过 python3 scripts/localization_catalog.py check。新键必须包含全部九种 macOS 语言条目,除非有精确省略记录;en 和 ja 仍必需。保留 printf 占位符,计数类字符串在源有计数时使用复数变体。

计数与复数:计数类字符串记录在 scripts/localization-plurals.json,包含英文源和选择复数的参数编号。每个必需的复数类别都必须有翻译文本。当多个计数变化或计数不是第一个参数时使用 substitutions。阿拉伯语需要 zero/one/two/few/many/other;法语和西班牙语包含 many。所有消息保持在目录的 strings 对象内,以便 Xcode 编译。复数替换中共享拼写的词使用 identityLocales 对象,包含 reason 和显式 values 列表。

限制与参考:目录归属不明确、某个键的 Swift 调用点(无论是否变更)对 defaultValue 不一致、类似计数的新字符串、不支持的 Swift 字面量形式以及无效生成的翻译都会停止并给出具体的人工关注项。新增键盘快捷键还需文档和设置条目,参见 ../cmux-keyboard-shortcuts/SKILL.md。详细参考见 references/audit-workflow.md。