Claude Desktop Zh Localize

Claude Desktop 中文补丁 · 汉化工作流

本项目是 Claude Desktop 的本地中文补丁。界面文本通过三层机制汉化，新增翻译时必须按目标文本的性质选择正确的层，三层全部落位后统一验证。

三层汉化机制

桌面壳层文本（极少）放 resources/desktop-zh-*.json。

工作流

第 1 步：定位 i18n key

在已安装应用的英文语言包中按值精确匹配（项目词表只保留当前版本存在的 key）：

pythonCopy code
import json
en = json.load(open("/Applications/Claude.app/Contents/Resources/ion-dist/i18n/en-US.json"))
for text in ["Theme", "Chat font"]:
    print(text, {k for k, v in en.items() if v == text})

• 精确匹配不到时用小写子串模糊搜索，并去前端 bundle（/Applications/Claude.app/Contents/Resources/ion-dist/assets/v1/*.js；新版 Claude 可能改名或换层级，安装脚本会自动探测，找不到时在 ion-dist 下递归搜含 index-*.js 的目录）里确认组件写法。
• 截图里的文本往往是多个 DOM 节点拼出来的（链接前后各一个 text node），要分别找。

第 2 步：确定三地译文

zh-CN / zh-TW / zh-HK 各写一份，遵守下方术语表。同一个英文值若有多个 key，全部都要写。

第 3 步：写入词表

关键机制（实测踩坑后确认）：配置窗口（配置第三方推理）和主窗口首页走 react-intl + 语言包 key，DOM 注入层对它们无效！因此每条翻译必须同时写入：

1. frontend-zh-*.json（必须有 key——在 en-US.json 里按值反查；只写硬编码对在该窗口不生效）；
2. frontend-hardcoded-zh-*.json（覆盖在线 DOM 层与本地 bundle 静态替换）。

用脚本一次性更新三个 frontend-zh-*.json（dict，key: 译文）和三个 frontend-hardcoded-zh-*.json（list of [source, target]）。硬编码词表注意：

• 弯引号与直引号各写一条（can't 与 can't 是两个不同源串）；
• 链接前后拆分的文本节点，前导节点要写"带尾随空格"和"不带"两条，例如 "...within Anthropic's guidelines. Learn more" 的前半句 Claude will keep these in mind ... within 需单独成条；
• 被 <code> 片段拆开的句子（如 "when enabled is true"）：key 的译文直接含反引号整体翻译（"当 `enabled` 为 true 时……"），DOM 层则需按静态分段逐段映射；
• CSS 大写显示的标题（如页面显示 NETWORK PROXY）实际 key 值可能是 Network proxy，按 key 原值匹配；
• 源文与译文相同的条目会被丢弃（见陷阱 1），不能"原样保留"。

第 4 步：动态文本写正则规则

凡含数字/日期/变量的句子（Delete 3 chats?、Updated Aug 19、Past 3 months）不能靠静态映射，必须在两处同步加规则：

1. scripts/patch_claude_zh_cn.py：在 build_online_dom_translation_script() 的 G=[...] 数组加 [/^...$/,"译文 $1"]；可变的措辞先在函数开头的 if lang_code == "zh-CN": / else: 分支里定义文本变量。
2. scripts/install_windows.ps1：$template = @'...'@ 模板中加同款规则；新文本变量走 __PLACEHOLDER__ 占位符——(a) 在模板首行 const L=...,XXX=__XXX__; 声明；(b) 在函数体用 $xxxText = if ($Language -eq "zh-CN") { "...$1..." } else { "..." }定义（PowerShell 双引号串中$1要写成 ``$1 ``）；(c) ConvertTo-Json -Compress 后追加到函数末尾的 .Replace("__XXX__", $xxxTextJson) 链。

写完正则先用 Node 快速验证匹配：

bashCopy code
node -e 'const G=[[/^Past (\d+) months?$/,"过去 $1 个月"]];for(const s of ["Past 3 months","Past 1 month"]){const m=s.match(G[0][0]);console.log(s,"->",m?G[0][1].replace("$1",m[1]):"NO MATCH")}'

第 5 步：验证

bashCopy code
# 三地映射命中 + 废弃键检查（有未命中即退出码 1）
python3 skills/claude-desktop-zh-localize/scripts/verify_mapping.py "Theme" "Past 3 months" ...

# 语法检查
python3 -m py_compile scripts/patch_claude_zh_cn.py scripts/patch_linux_asar.py

verify_mapping.py 默认读 /Applications/Claude.app，可用 CLAUDE_APP=/path/to/Claude.app 覆盖。需要端到端确认时再跑 python3 scripts/patch_claude_zh_cn.py --user-home "$HOME" --dry-run（约 5 分钟，非必需）。

第 6 步：Computer Use 视觉回归验证（可选但推荐）

用户要求"测试页面"、"看看汉化效果"，或批量补词之后需要真机确认时执行：重跑安装脚本把词表打进 /Applications/Claude.app，再用 computer-use 逐页截图核对。完整分步手册（含权限前置条件、bootstrap 代码、逐页核对清单、判定标准）见 references/computer-use-verification.md，执行前必读。

第 7 步：提交

默认不主动提交；用户要求提交时：从 main 切 feat/... 分支 → git add resources scripts → commit（feat: ...）→ push → gh pr create → 报告 PR 链接，等用户确认后再 merge。

陷阱清单（都真实踩过）

1. 源文 == 译文的条目会被静默丢弃。is_online_dom_translation_entry() 要求 source != target，所以 "Pull requests" 这类想保留英文的词必须给出真译文（如"拉取请求"）。
2. 含 { 或换行的文本进不了 DOM 映射（长度上限 1000）。ICU 复数串如 {count, plural, ...} will be permanently deleted 只能写进硬编码词表（对本地 bundle 生效），在线 DOM 侧必须配正则：[/^(\d+) items? will be permanently deleted\./, ...]。
3. DOM 文本节点会在链接处被拆开，整句静态映射匹配不上。处理方式见第 3 步的前导节点变体。
4. macOS 与 Windows 引擎必须同步。只改 Python 不改 ps1，Windows 在线页面会漏翻；反之亦然。
5. 不要往 frontend-zh-*.json 写 en-US.json 里不存在的 key——合并时会被忽略并计入 extra old keys，验证要求该值恒为 0。
6. 硬编码词表是 dict 合并语义（后写覆盖同源文），重复添加无害，但弯/直引号、带不带空格是不同 key。
7. ⚠️ 通用单词/数据标识符严禁进硬编码词表。硬编码替换会命中 JS 源码里该词的所有带引号出现，包括数据上下文。真实事故："Pin"→固定 把 icon:"Pin" 图标名改成中文（图标全坏）；"Engineering"→工程 把 workFunction:"Engineering" 服务端数据值和 Ax=["...",...] 角色数组改掉，与未替换的 unquoted 对象键 Engineering:[...] 失配 → f["工程"] undefined → 连接器页崩溃（TypeError: e is not iterable）。判定规则：单词若同时是 (a) 图标/组件名、(b) 服务端数据值、(c) 对象键/switch-case/数组元素，就绝不能进硬编码词表——改用 react-intl key（frontend-zh-*.json）提供翻译。若已发生污染：在前端 bundle（默认 ion-dist/assets/v1/*.js，脚本会自动探测实际目录）中把 "中文" 批量还原为英文原词（UI 显示由 intl catalog 提供，不受影响），不要碰 app.asar（M 映射的键值对是合法的）与 i18n catalog。
8. 主进程菜单翻译自 2.9939.2 起改走 desktop 语言包（intl catalog）：菜单缺失翻译时应用会把 Missing message: "<id>" ... (default message (英文)) as fallback 打到 stderr——前台启动应用收集该日志即可拿到完整的未翻译菜单 key 清单（71 个），写入 desktop-zh-*.json 后由 install_desktop_locale 合并进 Contents/Resources/zh-CN.json。
9. ⚠️ 2.9939.2（Electron 44）两大挂死：patch_online_locale_lock（DesktopIntl 锁，任何形态包括可重入标志位）与菜单运行时补丁都会让主进程在菜单构建后、窗口创建前陷入 JS 深度递归——进程活着但永远无窗口、AX 超时。两者都已加版本门控（>= 2.9939.2 跳过注入），新版菜单由 desktop 语言包覆盖。若需诊断：sample <pid> 看主线程是否陷入 JS 深度递归（成千层重复栈帧）。
10. 应用启动时会把 Claude-3p/config.json 的 locale 归一化为系统语言。修 locale 的正确顺序：杀应用 → 改配置 → 启动；运行时改会被回写覆盖。界面整体回退英文时重跑补丁脚本即可。
11. 手工 codesign --force --deep --sign - 会清空 entitlements（丢失 com.apple.security.virtualization），导致补丁校验失败。必须用补丁自带的 resign_app（从原二进制读取并保留授权），或从最近一个由补丁签名的备份恢复。

术语对照表

不确定的术语先在现有词表里 grep 既有译法，保持一致优先。