SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场claude-localize

claude-localize

办公与效率

查看项目

更新于 10-27 17:13

技能介绍

Claude Desktop 中文汉化（claude-localize）用于把本机安装的 Claude Desktop 桌面客户端汉化为简体中文，并可随时恢复英文原版。其核心理念是自适应：Claude Desktop 更新频繁，写死路径和正则的工具容易失效，本技能改为运行时探测，先读当前安装版本的 i18n 目录结构、语言加载机制和翻译覆盖率，再决定怎么打补丁，因此即使 Claude 改了内部结构，也能现场判断、调整。目前实现平台为 macOS，Windows 见 references/windows.md（规划中）。

【工作原理】Claude Desktop 的界面文案分两层。前端 UI（Electron 渲染层）文案在 Contents/Resources/ion-dist/i18n/{locale}.json，key 是英文原文的哈希，运行时按当前 locale 动态加载对应文件；因为 key 是内容哈希，只要英文原文没变，旧译文就还能对上，这让“内置精校译文 + 只翻新增”成为可能。桌面/原生层（菜单、托盘、原生弹窗）在 Contents/Resources/{locale}.json 和 {locale}.lproj/Localizable.strings。

汉化的关键有三点：一是把中文译文写进 app 真正加载的 locale 文件，实际生效的 locale 由账号/服务端决定，且 app 会把它回写进 config.json，所以光设 config.locale=zh-CN 不管用、会被覆盖，因此本技能直接覆盖 en-US.json（以及 zh-CN.json/zh.json），未译 key 仍回退英文，原始英文存为 en-US.original.json 以备恢复与重复打补丁；二是必须开启 Claude 的开发者模式（Settings → Developer），否则 app 可能加载远程 claude.ai 网页版，本地译文文件根本不会被读取；三是桌面/原生层需写 Contents/Resources/zh-CN.json 和 .lproj/Localizable.strings。

关于语言白名单：新版 Claude 仍有“支持的 locale 列表”数组，只是从 index-.js 搬进了内容哈希的 chunk（如 assets/v1/ccc72bfa9-.js）。早期只扫 index-*.js 会漏看它、误以为无需改 JS，导致 zh-CN 从没被登记成真正的 locale、汉化全靠覆盖 en-US.json 硬撑，一旦某机器协商出的 locale 没有对应 i18n 文件就 404、渲染层永不就绪，出现白屏。现在技能扫描全部 *.js 找到该数组并注入 zh-CN，并为整组中文别名都写好 i18n 文件、换入前自检，从根上杜绝白屏。

因为修改了 app 包内文件会让 macOS 代码签名失效，所以必须重签名（macOS 15+ 还需带 hardened runtime + 关闭 library validation，否则改过的 Electron app 无法启动），这一步脚本已封装。确定性的活（备份、合并 JSON、注入白名单、重签名、改配置、校验）都在 scripts/patch_macos.py 里，唯一需要模型动脑的是翻译新增文案。

【前置确认】开始前需向用户确认：这会修改 /Applications/Claude.app，需要输入一次系统管理员密码（在 apply/restore 的换入步骤会弹出 macOS 原生密码框）；会先完整备份原版到 ~/Library/Application Support/ClaudeCN/backups/，可随时 restore 恢复；汉化后 Claude 会自动重启；开启开发者模式是前提，先让用户在 Claude 内打开 Settings → Developer → 开发者模式，否则 app 加载远程网页版、本地汉化不生效。

【使用流程】所有命令在 skill 目录下用 python3 scripts/patch_macos.py <子命令> 运行（脚本会自动定位 Claude.app；非标准路径用 --app 指定）。

  1. 探测（detect）：运行 python3 scripts/patch_macos.py detect，读 JSON 输出，重点看 version（当前 Claude 版本）、i18n_dir / assets_dir（若为 null 说明结构变了，应停下读 references/mechanism.md 自适应排查，不要硬来）、whitelist.needs_js_patch（是否还需把 zh-CN 注入“支持 locale 列表”数组，locale_list_files 列出命中该数组的 JS，scanned_js 是扫描总数）、coverage（内置精校译文对当前版本的覆盖率 pct 和待翻译数量 untranslated）、patched（是否已汉化）、has_backup（是否已有备份）。

  2. 准备增量（prepare）：运行 python3 scripts/patch_macos.py prepare，它会把“当前版本里、内置精校译文还没覆盖的新增 key”写到 .work/untranslated.json（形如 {"哈希key": "English source"}），输出里有 untranslated_count。如果 untranslated_count 为 0，跳过第 3 步直接 apply。

  3. 翻译增量（由模型完成）：读 .work/untranslated.json，把每个英文值翻译成自然、地道的简体中文，key 保持不变，结果写到 .work/delta-zh.json（同样的 {key: 中文} 结构）。翻译要求：先读 assets/glossary.md 的术语表，保证与现有译文用词一致（如 Artifacts、Connectors、Cowork、MCP 等的固定译法）；保留占位符与标记，如 {name}、{count}、%s、{0}、ICU 复数语法 {count, plural, ...}、HTML 标签 <b>...</b>、Markdown、换行 \n、以及原文首尾空格；句子风格简洁、符合中文软件习惯，UI 按钮/菜单用短词（如 "Copy"→"复制"）；数量大时可分批翻，或用子 agent 并行翻，但务必合并成一个完整的 delta-zh.json。翻完后强烈建议把 delta-zh.json 合并回 assets/zh-CN.base.json，这样下次跑就不用重翻。想要快而不求全，可以跳过翻译直接 apply，未翻的 key 会回退英文，覆盖率即 detect 报的 pct。

  4. 应用（apply）：运行 python3 scripts/patch_macos.py apply，它依次：备份（版本变了会自动重新备份，绝不降级）→ 复制 app 到临时目录 → 合并译文（en-US 兜底 + 精校 base + 本次 delta）写入前端/桌面/statsig → 探测并按需注入白名单 → 重签名 → 关闭 Claude → 弹密码框把汉化版换入 /Applications → 写 locale=zh-CN → 重启 Claude。输出 JSON 含 ok、coverage_pct、whitelist 处理结果。

  5. 校验并汇报：看 apply 输出 ok: true；让用户确认 Claude 重启后界面变中文了，这一步也顺带验证了本版本的加载机制，若没生效，去读 references/mechanism.md 的“排查”一节；给用户一份简短中文汇报：版本、覆盖率、是否需开发者模式、如何恢复。

【恢复英文原版】用户只要说「恢复 Claude 英文 / 恢复原版」即可触发，或直接运行 python3 scripts/patch_macos.py restore。它从备份还原（同样弹一次密码框），清掉 locale 配置并重启 Claude。备份在 ~/Library/Application Support/claude-localize/backups/（旧 GUI 的 ClaudeCN/backups/ 也会自动识别复用），独立于 app、不随更新丢失，目录里附 请勿删除_README.txt。就算备份被误删也不会卡住：Claude.app 可从 claude.ai 免费重装即恢复官方原版，而聊天记录和登录都存在 ~/Library/Application Support/Claude/（与 app 分开），重装不丢；restore 找不到备份时会直接给出这个提示，而不是报错卡死。防降级保护：若当前 Claude 已不是本工具汉化的状态、且备份是更旧版本（通常意味着 Claude 自己更新过），restore 会中止并提示，避免把 Claude 降级，确需回到备份版本时加 --force。

【关于 Claude 自动更新】Claude Desktop 用 Squirrel.Mac 自动更新，更新时会校验代码签名。汉化后的 app 是 ad-hoc 重签的，签名身份与 Anthropic 官方不一致，因此汉化期间 Claude 的自动更新基本会被跳过/失败（更新包的官方签名与当前 ad-hoc 签名不匹配），这是安全的，Claude 只是停在当前版本，不损坏、不丢数据。想升级新版：先 restore 回官方英文版 → 让 Claude 自动更新 → 再跑一次汉化。skill 是自适应的，会读取新版结构、补译新增文案后重新应用。

【让基准译文自增长（维护者推荐）】翻译完一次增量后，把它并进内置基准，使覆盖率单调提升、避免重复劳动，可用脚本合并 assets/zh-CN.base.json 与 .work/delta-zh.json。如果这个 skill 同时是 ClaudeCN GUI 项目的“翻译引擎”，更新后的 assets/zh-CN.base.json 可以回灌到 GUI 的 translations/zh-CN.json 重新打包发布。

【当结构变了 / 出错时】不要硬套步骤。references/mechanism.md 记录了 Claude Desktop i18n 的完整机制和自适应排查清单（i18n 目录找不到、locale 文件名变了、白名单又出现了、签名后无法启动等）。先读它，再用 detect 的原始信息判断，必要时直接读 app 内的 index-*.js 现场分析。

【平台】macOS：本文件 + scripts/patch_macos.py。Windows：见 references/windows.md（规划中——原理相同，差别在提权方式 takeown/icacls、无需重签名、locale 配置在 %APPDATA%\Claude\config.json）。