claude-code-zh-cn

Claude Code 简体中文本地化插件

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

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

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

🚀 姊妹项目：我还做了一个 codex-code-zh-cn —— Codex CLI 简体中文版。 和这个一样的用法：直接输入 codex 就是中文界面，还能在会话里用 /chinese、/english 随时切换语言。欢迎来试试！

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，这会帮助更多中文用户发现它。

⭐ 会话内切换语言（v2.12.0+）

装好之后，直接在 Claude Code 输入框输入并回车：

切换由 UserPromptSubmit Hook 拦截处理，不消耗任何 token，结果立刻显示。 界面硬编码文案需要重启 Claude Code 后完全生效；语言设置与 spinner 动词/提示随即更新。

⭐ 临时切回英文或卸载

需要对照英文教程时，输入 /english 即可切回（见上节）。如果想彻底卸载汉化：

macOS、Linux 或 WSL 远程安装用户运行：

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

本地源码安装用户运行 ./uninstall.sh。Windows 用户先关闭所有 Claude Code 窗口；如果插件市场安装时没有保留本项目目录，先下载源码，再运行卸载脚本：

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

已有本地源码的 Windows 用户直接在原目录运行最后一行即可。卸载脚本会还原 CLI 备份，移除中文设置、Hook 和插件注册，同时保留其他 Claude Code 配置。重启 Claude Code 后即为英文界面。

卸载脚本无法判断 language、spinnerTipsEnabled、spinnerTipsOverride、spinnerVerbs 是插件写入还是你手动配置，因此会统一删除。如果你手动维护过这些字段，请先自行备份需要保留的值。

如果安装时同意把中文设置同步到 CC Switch，还需在 CC Switch 的 Claude“通用配置”中删除本插件添加的 language、spinnerTipsEnabled、spinnerTipsOverride、spinnerVerbs，否则下次切换供应商时这些设置可能再次写回。如果这些字段原本就是你手动配置的，请只暂时关闭“写入通用配置”，不要删除。

要重新启用中文，macOS、Linux 或 WSL 重新运行上面的 30 秒安装 命令；Windows 在刚才的源码目录重新运行 install.ps1。

为什么做这个？

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

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

安装说明

推荐：插件市场安装（macOS / Linux / Windows 通用）

最快的方式——不依赖本地仓库，两条命令搞定。三平台通用，只要已经有 claude 命令：

# 1. 添加本项目的插件市场
claude plugin marketplace add --scope user https://github.com/taekchef/claude-code-zh-cn

# 2. 安装中文本地化插件
claude plugin install claude-code-zh-cn@claude-code-zh-cn --scope user

装好后重启一次 Claude Code：session-start hook 会自动把 spinner 动词/提示/界面中文化配置合并进 settings.json，并自动 patch 已验证版本的 CLI 硬编码文字。

完整覆盖检查：安装后可直接运行 zh-cn-setup skill（在 Claude Code 里说「帮我运行 zh-cn-setup」）。它会补齐安全的 settings 配置、报告 CLI patch 与 CC Switch 状态，并为 skill 描述等不能在当前进程内安全完成的操作给出可复制的终端命令。

spinner/界面仍是英文？ 如果重启后 spinner 仍是英文，也可运行增强安装 skill：在 Claude Code 里说「帮我运行 zh-cn-setup」或手动执行：

node "${CLAUDE_PLUGIN_ROOT}/skills/zh-cn-setup/scripts/setup.js"

该脚本会从插件内置数据补齐缺失的 spinner 配置、检测并同步 CC Switch 通用配置（需授权）、报告 patch 状态，并输出 skill 描述汉化命令。只补齐缺失项，绝不覆盖你已有的手动配置。

Skill 描述默认不自动改写：同一个 description 既显示在菜单里，也用于 model 判断是否触发 skill。先运行脚本输出的 --dry-run 命令检查范围，再执行翻译命令。CC Switch 管理的 skill 若不在 ~/.claude 下，请把其真实目录通过 ZH_CN_SKILL_I18N_EXTRA_ROOTS 传入；Windows 多个目录用分号分隔，macOS/Linux 用冒号分隔。译文会保留英文备份，可用 node "${CLAUDE_PLUGIN_ROOT}/skill-i18n/restore.js" --all 还原。

CC Switch 数据库里的 skill 描述仍是英文？ ZH_CN_SKILL_I18N_EXTRA_ROOTS 只翻译 SKILL.md 文件本体，不会写 CC Switch 的 ~/.cc-switch/cc-switch.db。检测到 skills 表中描述仍为英文、但对应 SKILL.md 已翻译为中文时，zh-cn-setup skill 会提示运行可选工具 cc-switch-descriptions.js：默认只读预览，--apply 才写入（自动备份数据库并输出还原命令）：node "${CLAUDE_PLUGIN_ROOT}/skills/zh-cn-setup/scripts/cc-switch-descriptions.js"。CC Switch 管理界面、Claude Code /skills 面板与 model 自动触发共用同一份 description，请先预览再决定。

Windows native .exe 用户：如果当前 Claude Code 是 2.1.113+ native .exe，patch 需要先 npm install -g node-lief。未安装时 Layer 4 CLI Patch 会跳过（spinner/界面中文化等 Layer 1~3 不受影响）。

完整安装脚本（本地开发 / 离线 / 旧版 Claude Code）

首屏命令会从本项目最新 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 硬编码文字（2065 条翻译；代表版本 2.1.112 实测 1695 处有效 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.226 内的版本（完整清单见支持矩阵）；更高版本也会本机自检，需要 node-lief。Linux x64 glibc 仅启用 2.1.220，需要 node-lief >=1.3.0，不尝试 provisional latest。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