claude-code-zh-cn

Claude Code 简体中文本地化插件

让终端里的 AI 编程助手说中文 🇨🇳

一条命令，把 Claude Code 的终端界面、等待提示、系统通知和默认回复切换为简体中文。

187 个趣味 spinner 动词，41 条中文提示，回复耗时中文化；另有 1895 条界面翻译。

macOS · Linux · WSL · Windows

一行远程安装 · 更新后自动修复 · 卸载不丢配置

效果预览

真实 Ghostty 录制：同一台 Mac、同一个 Claude Code 2.1.211，先运行安装前备份的原版可执行文件，再运行当前中文补丁版。动图只做缩放和前后切换，没有重绘或仿造终端内容。

安装前：

⠙ Photosynthesizing...

  Tip: Press Shift+Tab to switch between default, auto-accept edits, and plan modes

安装后：

⠙ 光合作用中...

  💡 按 Shift+Tab 在默认模式、自动接受编辑模式和 Plan 模式之间切换

更多画风：

⠙ 蹦迪中...          ⠙ 七荤八素中...         ⠙ 搞事情中...
⠙ 瞎忙活中...        ⠙ 花里胡哨中...         ⠙ 变魔术中...

  琢磨了 1分23秒

187 个趣味 spinner 动词，41 条中文提示，回复耗时中文化，AI 默认中文回复。装完即用。

30 秒安装

已经安装 Claude Code？运行：

curl -fsSL https://github.com/taekchef/claude-code-zh-cn/releases/latest/download/install-remote.sh | bash

重启 Claude Code，看到“思考中”“光合作用中”等中文提示即安装成功。还没有 claude 命令，请先安装 Claude Code。

安全边界：安装前会备份原文件。补丁、重打包或启动自检失败时会保留或恢复原文件；遇到暂未适配的新文案时，对应内容保持英文，不影响 Claude Code 正常启动。

如果它让你的 Claude Code 更顺手，欢迎点一下右上角 Star，这会帮助更多中文用户发现它。

为什么做这个？

Claude Code 是一个很棒的终端 AI 编程助手，但它没有中文界面。UI 文字主要硬编码在一个 13MB 的 cli.js 里，没有 i18n 基础设施。

官方短期内不太可能加中文支持。所以我做了这个插件，通过四层机制（设置注入 + Hook 系统 + 插件系统 + CLI Patch）实现中文化，自动检测安装方式，更新后自动修复。遇到还没验证过的新版本也不怕：插件会自动降级，翻不了的部分保持英文，CLI 绝不会坏。

安装说明

首屏命令会从本项目最新 GitHub Release 下载源码包，然后执行同一套 install.sh。它和官方安装器的区别：

远程安装会优先把本项目登记到 Claude Code 插件管理器；当前 CLI 不支持正式注册时，才启用等价的独立 Hook 兜底，不需要保留本地 clone。

如果你要改翻译或调试脚本，再用本地源码安装：

git clone https://github.com/taekchef/claude-code-zh-cn.git
cd claude-code-zh-cn
./install.sh

安装脚本会自动：

• ✅ 备份现有 ~/.claude/settings.json 和 cli.js（或原生二进制）
• ✅ 合并中文设置到 settings.json
• ✅ 检测到 CC Switch 通用配置缺少中文设置时，先询问用户；同意后才同步
• ✅ 优先通过 Claude Code 插件管理器登记 marketplace 并启用正式插件；注册不可用时才安装独立备用 Hook
• ✅ 已验证版本直接使用公开证据；更高 native 版本也先本机自检。可 patch 硬编码文字（1895 条翻译；代表版本 2.1.112 实测 1595 处有效 patch）
• ✅ 缺少 node-lief、native 格式变化、提取失败或自检失败时，只跳过 Layer 4；Layer 1~3 和 Claude Code 本体继续可用

Windows 原生安装

git clone https://github.com/taekchef/claude-code-zh-cn.git
cd claude-code-zh-cn
powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1

install.ps1 会自动完成与 install.sh 相同的步骤：正式插件注册、依赖检查、Settings 合并、CLI Patch 和失败回滚。需要 PowerShell 5.1+（Windows 10/11 自带）。

Windows native .exe 用户先装 node-lief：如果当前 Claude Code 是 2.1.113+ native .exe，请先运行 npm install -g node-lief 再装插件。未安装时 Layer 4 CLI Patch 会跳过，Layer 1~3 不受影响。也可以继续通过 WSL 使用 install.sh。

Claude Code 在 Windows 更新后，插件不会现场改写正在运行并被系统锁定的 claude.exe。先照常使用；方便时关闭所有 Claude Code 窗口，再回到本项目目录重跑上面的 install.ps1，安装器会完成补丁、启动自检和失败回滚。

各安装方式的中文化程度

native binary 说明：官方安装器和新版 npm 包装到的是 native 二进制。插件会提取其中的 JS → 翻译 → 写回，并做启动自检；补丁、重打包或自检失败会恢复原文件。macOS arm64 已验证 2.1.113 - 2.1.220 内的版本（完整清单见支持矩阵）；更高版本也会本机自检，需要 node-lief。macOS 可在新会话安全补丁；Windows 不热改运行中的 exe，更新后需关闭窗口并重跑 install.ps1。

安装脚本会自动检测安装方式，无需手动选择。

前置要求

• Node.js（CLI Patch 需要）
• 可选：jq（更精准的 JSON 合并）
• 可选：node-lief（native 二进制适配需要：npm install -g node-lief；旧版 npm cli.js 路径不需要）

验证

重启 Claude Code 后，发送任意请求。如果看到 spinner 显示“思考中”、“光合作用中”等中文，说明 Layer 1~3 已生效。

不确定 Layer 4 是否生效、或 UI 仍是英文时，运行诊断脚本（会检测安装形态、settings、patch 记录和 patch.log 里的失败原因，并给出下一步命令）：

./doctor.sh                                            # macOS / Linux / WSL（仓库内）
bash ~/.claude/plugins/claude-code-zh-cn/bin/doctor    # 只有已安装插件时

powershell -NoProfile -ExecutionPolicy Bypass -File .\doctor.ps1   # Windows

加 --json 得到机器可读输出；退出码 0 = 无阻塞项，1 = 需要处理。

如果是请求报错（403、空响应、ECONNREFUSED 等）而不是界面英文，那通常是 provider / 代理 / 网关链路问题，不是汉化没生效。可以把报错原文交给 doctor 分流：

./doctor.sh --runtime-error 'API returned an empty or malformed response (HTTP 200)' --json

更新

Claude Code 更新后，npm / macOS native 安装会在首次会话启动时自动检测版本变更并重新 patch；Windows native 会保留原版可用，并提示关闭窗口后重跑安装器。新版先本机自检；只有格式、依赖、提取或自检失败才跳过原生 Layer 4，不会让 CLI 失效。

插件本体发布新 Release 后，正式安装态由 Claude Code 插件管理器更新。独立兜底安装只做限时检查并提示，不会在会话启动途中原地覆盖自身；本地源码安装用户在会话结束后运行 git pull && ./install.sh（Windows：git pull 后重跑 install.ps1）。

卸载

远程安装用户可直接运行：

curl -fsSL https://github.com/taekchef/claude-code-zh-cn/releases/latest/download/uninstall-remote.sh | bash

本地源码安装用户运行 ./uninstall.sh（Windows：powershell -File uninstall.ps1）。精准移除插件注入的设置，保留你的其他配置不变。

支持范围

• 版本号不是运行门禁：高于已知 native 下限、且仍能被识别的新版会先在本机临时提取、翻译、重打包并执行启动自检；通过后才替换。已有词条继续中文，新文案原样保留英文。
• 失败不伤 CLI：补丁、重打包或启动自检任一步失败，都会保留或恢复原文件；失败只影响中文覆盖，不影响 Claude Code 使用。
• Windows 不热改运行中的 exe：Claude Code 更新后先保持原版可用；关闭所有 Claude Code 窗口，再按 Windows 安装命令重跑 install.ps1，由安装器补丁并自检。
• 格式变化才停手：如果未来版本不再是可识别的 native 格式、依赖缺失、提取失败或启动自检失败，只跳过 Layer 4，Layer 1~3 继续生效。
• 矩阵只记录证据：纯上游兼容证据可以更新支持矩阵，不要求插件升版；只有插件代码、翻译或 manifest 变化才发布新版。
• 已验证版本完整清单（含个别未收录版本）见 docs/support-matrix.md，由脚本自动生成。
• Claude Code 从 2.1.113 起 npm 主包切换为 native binary，不再包含旧的 cli.js；要最完整的翻译请用 npm install -g @anthropic-ai/claude-code@2.1.112。

发布边界：正式安装态由 Claude Code 插件管理器更新；旧环境的独立兜底安装只跟随本插件已发布 Release，不会跟随 main 上未发布的提交。Claude Code 本体升级不要求中文插件同步升版本；DISABLE_AUTOUPDATER / DISABLE_UPDATER 仍由 Claude Code 本体处理。

特色：187 个趣味动词翻译

原版 Claude Code 的 spinner 有一堆故意搞怪的英文动词（Flibbertigibbeting、Photosynthesizing、Moonwalking...），我们全部按原味翻译了：

完整 187 个翻译见 verbs/zh-CN.json

覆盖了什么

技术原理

Claude Code CLI 是一个 13MB 的单文件压缩包（cli.js，或 native 二进制内嵌 JS），UI 文字硬编码其中，没有 i18n 基础设施。本项目通过四层机制实现中文化：

Layer 1：内置设置（稳定，更新后不丢失）

• language: 控制 AI 回复语言
• spinnerTipsOverride: 替换等待提示文字
• spinnerVerbs: 替换 spinner 动词

Layer 2：Hook 系统（稳定，更新后不丢失）

• SessionStart: 会话启动时注入中文上下文指令 + 委托插件管理器检查更新 + 检测版本自动重 patch
• Notification: 拦截系统通知并翻译

Layer 3：插件系统（稳定，更新后不丢失）

• 标准 Claude Code 插件格式
• 提供 Chinese Output Style

Layer 4：CLI Patch（自动维护，优雅降级）

• 基于 Node.js 的字符串字面量扫描器，先扫描真实双引号字符串 token，再逐条替换
• 显式排除注释、模板字符串、正则字面量中的 "，避免误改代码结构
• 从 cli-translations.json 读取翻译，按长度降序批量替换
• 覆盖：状态消息、按钮文字、错误提示、设置页面、导航、快捷键说明等

Layer 1~3 完全不受 Claude Code 更新影响。Layer 4 的优雅降级闭环：

1. 备份：patch 前保留同版本干净原文备份，re-patch 一律从备份恢复干净基底，杜绝 patch 叠 patch
2. 逐条独立：单条翻译匹配不上就跳过（新版本改了文字 → 那条保持英文，其余照常）
3. 事务自检：npm patch 必须通过 JS 语法校验；native patch 必须通过提取、重打包和真实 --version 启动自检。任一步失败都保留或恢复原文件
4. 错误可见：失败写入插件目录 patch.log，doctor 可读取诊断

稳定性：Layer