cctrans

省下最多 67% 的 token：用母語讀 Claude Code，token 100% 按英文計費。

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Русский | हिन्दी

● I will refactor the auth module to use async tokens.
  ↳ 我將重構 auth 模組以使用非同步權杖。
  This touches 3 files and adds a retry layer.
  ↳ 這會影響 3 個檔案並加入重試層。

為 Claude Code 加上一層雙語對照:每行英文下方一行譯文(中/日/韓/俄/印地/西/葡/法/德),就在對話裡——僅作顯示,轉錄、模型上下文和你的 token 帳單 100% 保持英文。

✨ 特性

• 🪞 行內雙語顯示 —— 譯文隨回覆串流出現在每行英文下方,就在對話裡
• 🧩 三種排版 —— 逐行對照、按區塊成組(cctrans mode section),或整則回覆成組(cctrans mode message)
• 🔄 附加或替換 —— 在英文下方顯示譯文,或用 cctrans display replace 在原位只顯示譯文
• ❓ 問題對話翻譯 —— Claude Code 的互動式提問對話也會以你的語言顯示,而模型讀到的仍是你的英文答案
• 🧾 非破壞性 —— 轉錄與模型上下文保持純英文;skills、文件、程式碼不受影響
• 🆓 主對話零 token —— 翻譯走獨立低成本後端(也有免費選項),完全在 Claude Code 工作階段之外
• ⌨️ 輸入翻譯(beta) —— 用母語打字,模型按英文工作、按英文回覆(cctrans input on)
• 🌏 10 種目標語言 —— zh-Hans zh-Hant ja ko ru hi es pt fr de
• 🔌 6 個後端自動降級 —— OpenAI / Anthropic / DeepL / Azure / 免費 Google / 你自己的 Claude 訂閱
• 📁 專案層級覆寫 —— 在儲存庫裡放一個 .cc-translate.json,只為該專案切換語言/模式(或直接關閉)
• 🔒 金鑰隔離 —— API key 只存在 chmod-600 的檔案裡,從不讀終端機環境變數
• 🛟 故障安全 —— 任何錯誤或逾時都回退為純英文,絕不卡住工作階段
• 🩺 內建診斷 —— cctrans doctor 解釋為什麼沒在翻譯;cctrans stats 顯示你省下的 token
• 🎚️ 互動式設定 —— cctrans settings 開啟單螢幕編輯器(方向鍵操作);調節間距、標記、模型等等,涵蓋基礎與進階選項

🚀 快速開始

npm install -g cctrans@latest && cctrans install

安裝會註冊鉤子並開啟一個互動式設定編輯器(語言、顯示模式、後端、API key —— 隨時用 cctrans settings 重新開啟)。然後重新啟動 Claude Code——回覆變成雙語。隨時在 Claude Code 輸入框輸入 !cctrans off / !cctrans on 開關(! 是 CC 內建 bash 模式,不呼叫模型、不花 token)。

已經裝過? 用 npm install -g cctrans@latest 更新——從下一則回覆起生效(鉤子每個分塊都從磁碟重新執行);你的設定、金鑰和已註冊的鉤子原樣保留,無需重新設定。

git clone https://github.com/roy-jiang-opus/cctrans.git
cd cctrans
node bin/cctrans.js install

需要 ~/.local/bin 在 PATH 中,或使用別名:alias cctrans='node /path/to/cctrans/bin/cctrans.js'

🤔 為什麼做這個

兩個痛點,一個架構解決:

1. Claude Code 老是回英文。 Skills 與文件必須保持英文,即使在 CLAUDE.md 裡寫了「用中文回覆」,回覆仍會飄回英文。手動讓它重答一遍中文,既花一整輪模型呼叫,又污染對話歷史。

2. 用母語工作有一筆隱形的 token 稅——尤其在 Claude 上。 表達同樣的意思,非英語要多花 約 1.5–3 倍 token(Claude 的分詞器對非拉丁文字壓縮很差),而 Claude Code 的 5 小時視窗與每週額度都按 token 計——非英語工作階段燒額度快 1.5–3 倍。關鍵是,模型品質根本不是問題:Claude 多語言基準 >90%。痛點純粹是成本。

| | 日語 | 韓語 | 俄語 | 印地語 | 中文 | |---|---|---|---|---|---| | 相對英文的 token 開銷 | ~2–3× | ~2–3×+ | ~1.5× | ~2–3×+ | ~2–3× |

Anthropic 關於按語言調整額度的 issue(#26401)已被關閉(not planned)——官方沒有解法。

所以最省錢且正確的設計正是本工具的做法: 工作階段全程保持英文(輸入、轉錄、模型上下文——主對話零額外 token),你的語言只出現在人需要讀的地方:每行英文下方一行僅作顯示的譯文,由獨立的低成本後端渲染。

完整調研資料與來源:MOTIVATION.md。

⚙️ 運作原理

利用 Claude Code 原生的 MessageDisplay 鉤子(v2.1.152+):它在每則助理訊息渲染時觸發,把完成的文字片段(delta)交給鉤子;鉤子回傳的 displayContent 只替換螢幕顯示,不改變儲存的訊息。

Claude 串流輸出英文
        │  每完成一行/段觸發一次(stdin: turn_id/message_id/index/final/delta)
        ▼
  hook/message-display.js  ──►  src/interleave.js  ──►  src/translate.js
   (讀 delta、查開關)          (區分散文/程式碼/已是目標語言)    (多後端 + 快取)
        │
        ▼  回傳 displayContent = "英文行\n↳ 譯文行"
   Claude Code 就地替換顯示(原文仍在轉錄/上下文中)

已在 CC 2.1.169 實測:delta 是互不重疊的已完成片段(不是累積文字),普通 \n 即可讓兩種語言分行顯示,程式碼區塊/路徑/已是目標語言的行會自動跳過。

🎛 指令

| 指令 | 作用 | |------|------| | cctrans on / cctrans off / cctrans toggle | 開 / 關 / 切換翻譯 | | cctrans status | 檢視狀態(開關、鉤子、後端、語言) | | cctrans lang [code] | 檢視/切換目標語言:zh-Hans zh-Hant ja ko ru hi es pt fr de | | cctrans mode [line\|section\|message] | 排版:逐行、按區塊,或整則回覆 | | cctrans display [append\|replace] | 在英文下方顯示譯文,或在原位替換它(line 模式) | | cctrans only [on\|off] | 只顯示譯文,隱藏英文(line 模式 + replace) | | cctrans dialog [on\|off] | 翻譯 Claude Code 的問題對話(預設開啟) | | cctrans settings | 開啟互動式設定編輯器(基礎 + 進階) | | cctrans backend <id> | 切換翻譯引擎 | | cctrans backends | 列出所有引擎及其可用性 | | cctrans doctor | 診斷:鉤子、Claude Code 版本、後端、金鑰、最近一次鉤子錯誤 | | cctrans stats | 已翻譯行數 + 估算省下的主對話 token | | cctrans cache [clear\|gc] | 翻譯快取:大小 / 清空 / 按上限清理 | | cctrans setup | 互動式精靈:語言、顯示模式、後端、API key | | cctrans key [id] [value] | 管理 ~/.cc-translate/keys.json 中的 API key | | cctrans input on / cctrans input off | (beta) 把非英文輸入翻譯成英文(作為上下文傳給模型) | | cctrans input threshold <n> | 觸發輸入翻譯的非拉丁字元數(預設 4) | | cctrans last [N] | 把最近(或往前第 N 則)回覆翻譯到終端機 | | cctrans test <文字> | 翻譯一段文字,驗證引擎 | | cctrans install / cctrans uninstall | 註冊 / 移除鉤子 |

🧩 顯示模式

line(預設)逐行對照:每行英文下方一行譯文,隨回覆串流出現。section 讓英文完全按 Claude 的串流輸出原樣呈現,在一個區塊完成時插入一段成組譯文——對列表很多的回覆要安靜得多。message 更進一步:整則回覆以純英文串流輸出,一段成組譯文在最後才出現:

Use these flags:
↳ 使用以下参数：

- Enable the cache
- Set a small timeout
- Prefer the batch API
  ↳ 启用缓存
  ↳ 设置较短的超时
  ↳ 优先使用批量 API

cctrans mode section   # 按區塊 · cctrans mode message —— 整則回覆 · cctrans mode line —— 切回預設

section/message 模式下,譯文在所在區塊(或整則回覆)完成時才出現,而不是邊串流邊出——後端慢時(如 claude-code,3–6 秒/次)這個停頓會比較明顯,所以這裡 API 後端體驗最好。某個區塊翻譯失敗時,英文不受影響,該區塊只是保持未翻譯。

附加或替換。 預設情況下譯文顯示在英文下方(雙語對照)。只想讀你自己的語言?cctrans display replace 改為在原位替換每行英文,只顯示譯文:

cctrans display replace   # 只顯示譯文 · cctrans display append —— 切回雙語

替換在 line 模式下生效(section/message 在設計上先把英文串流輸出,因此沒有可替換的對象)。無論哪種方式,轉錄和模型上下文都保持 100% 英文;無法翻譯的行會保留原文,所以絕不會有內容憑空消失。

只想要你自己的語言,完全不要英文? cctrans only on 正是為此提供的一鍵捷徑(它會設定 line 模式 + replace)。英文連一瞬都不會閃現 —— Claude Code 算繪出來的每一行都已是譯文 —— 而任何無法翻譯的行都會回退到它的英文;程式碼區塊原樣通過。cctrans only off 切回雙語。

❓ 問題對話

當 Claude Code 讓你從選項中挑選時(互動式問題對話),問題、選項標籤及其說明也會以你的語言顯示 —— 而你選中的答案送達模型時仍是英文,因此它的推理保持純英文:

 ☐ 颜色偏好
Which color do you prefer?
↳ 您更喜欢哪种颜色?
❯ 1. Red
     ↳ 红色
     A bold, vibrant color
     ↳ 大胆、鲜艳的颜色
   2. Blue
     ↳ 蓝色

這借助 Claude Code 的 PreToolUse/PostToolUse 鉤子實現(問題對話由工具輸入渲染,訊息覆蓋層構不到那裡)。它遵循你的 display 設定 —— append 模式下雙語,replace 模式下只顯示你的語言。預設開啟;用 cctrans dialog off 關閉。如果對話來不及翻譯,就原樣以英文顯示。

升級後? 更新後執行一次 cctrans install,以註冊新的對話鉤子。答案還原(讓模型讀到的答案保持英文)需要 Claude Code ≥ 2.1.121 —— cctrans doctor 會對更舊的版本發出警告。

🌐 翻譯後端

| 後端 | 前提 | 速度 | 品質 | 說明 | |------|------|------|------|------| | openai(有 key 時預設) | cctrans key openai | ~1.4s/段 | 高 | gpt-4o-mini 批次行翻譯,保留程式碼/路徑 | | anthropic | cctrans key anthropic | ~1s/段 | 高 | claude-haiku-4-5 + structured outputs,嚴格等長行陣列(約 $0.0005/段) | | deepl | cctrans key deepl(免費額度 50 萬字元/月) | ~0.5s/段 | 高 | 傳統 MT 品質天花板;陣列介面天然對齊行 | | azure | cctrans key azure(免費 200 萬字元/月) | ~0.5s/段 | 中高 | 可加 cctrans key azure-region | | google | 無 | ~0.3s/段 | 中 | 免費非官方介面;所有後端失敗時的保底 | | claude-code | claude CLI 已登入 | ~3-6s/段 | 高 | 走你的 Claude 訂閱(claude -p headless),零額外費用但明顯較慢 |

主後端失敗/逾時會自動降級到 google,任何情況下都不會卡住工作階段。每行譯文按「後端+語言+內容」雜湊快取。

API key 只存放在 ~/.cc-translate/keys.json(chmod 600)——用 cctrans setup / cctrans key 設定,或直接編輯該檔案。終端機環境變數永遠不會被讀取,本工具的 key 與終端機的 key 互不污染。

其餘設定(後端、語言、標記、模型、Azure 端點)都在 ~/.cc-translate/state.json 中——用 cctrans 指令修改或直接編輯檔案。

🗣 多語言

cctrans lang zh-Hans  # 簡體中文(預設)    cctrans lang zh-Hant  # 繁體中文
cctrans lang ja       # 日語                cctrans lang ko       # 韓語
cctrans lang ru       # 俄語                cctrans lang hi       # 印地語
cctrans lang es       # 西班牙語            cctrans lang pt       # 葡萄牙語
cctrans lang fr       # 法語                cctrans lang de       # 德語

CJK + 俄語 + 印地語(非拉丁文字)可按 Unicode 區間零成本判斷「該行已是目標語言」並跳過;西班牙語 / 葡萄牙語 / 法語 / 德語(拉丁文字)則改用保守的停用詞啟發式——即使某行已是目標語言仍被重新翻譯,同一性檢查也會抑制原樣回顯,最壞情況只是浪費一次後端呼叫,絕不會出現錯行。注意拉丁文字語言省下的 token 較少(相對英文約 1.1–1.2×,非拉丁文字為 1.5–3×——見 MOTIVATION.md);對這些語言而言,吸引力主要是雙語顯示本身。

中文採用 BCP-47 文字碼(zh-Hans/zh-Hant)——繁體是文字系統而非地區;zh-CN / zh-TW 仍可作為別名使用,會自動正規化。切換語言立即生效(鉤子每次呼叫都讀取狀態),不同語言的快取相互獨立。

📁 專案層級覆寫

在儲存庫根目錄(工作目錄的任一上層目錄皆可)放一個 .cc-translate.json,即可只為該專案覆寫全域設定:

{ "target": "ja", "mode": "section" }

或用 { "enabled": false } 為特定專案關閉 overlay。可覆寫的欄位:enabled、target、mode、backend、marker、model、inputEn、inputMinChars。機密不可覆寫——key 仍只存放在 ~/.cc-translate/keys.json,端點設定也刻意只在全域層級生效。在專案裡執行 cctrans status 和 cctrans doctor 都會顯示專案覆寫是否生效。請把 clone 下來的儲存庫裡的 .cc-translate.json 視為其程式碼的一部分:例如,它可以為在該儲存庫中進行的工作切換後端(包括會消耗你訂閱額度的 claude-code)。

🩺 疑難排解

overlay 在設計上是故障安全的:任何錯誤都降級為純英文,而不是卡住工作階段——這也意味著失敗是無聲的。當什麼都沒在翻譯時:

cctrans doctor

它會檢查鉤子註冊(包括舊版安裝留下的失效路徑)、Claude Code 版本(MessageDisplay 需要 ≥ 2.1.152)、設定的後端及其 key、即時連線(含延遲),以及最近一次鉤子錯誤(鉤子在串流途中失敗時會把錯誤記錄到 ~/.cc-translate/last-error.json)。想看看 overlay 為你做了什麼:

cctrans stats    # 已翻譯行數 + 估算省下的主對話 token
cctrans cache    # 翻譯快取大小;clear / gc 管理(預設 200 MB 上限)

⌨️ 輸入翻譯(beta)

cctrans input on 啟用 UserPromptSubmit 鉤子:當你的輸入包含足夠多的非拉丁字元時(預設 4 個以上——按絕對數量計,檔案路徑和識別字不會稀釋觸發條件;用 cctrans input threshold <n> 調整),英文譯文會作為上下文附給模型並被視為權威指令,同時要求模型用英文回覆——這樣雙語 overlay 持續生效,對話上下文全程保持英文。(已在 CC 2.1.169 核實:鉤子無法改寫 prompt 本身,所以原文仍在歷史中,英文隨附。)英文輸入原樣通過;任何錯誤都安全回退為原樣送出。

Beta:翻譯呼叫會在每條非英文輸入送出前阻塞約 0.5–1.5 秒。預設關閉;setup 精靈會詢問一次。回饋 → issues。

📏 行為與限制(已核實)

• 鉤子在串流輸出中按片段觸發,每段單獨翻譯並就地替換——所以譯文會隨英文逐段出現。
• 鉤子有 10 秒逾時;本工具內部 9 秒保底。任何錯誤/逾時/超長(>9000 字元)都會安全回退成原始英文,絕不卡住工作階段。
• 每行譯文按內容雜湊快取(~/.cc-translate/cache,200 MB 上限,每日清理),重繪與重複文字零成本。所有模式共享同一快取。
• section/message 模式下,進行中區塊的文字會緩衝在 ~/.cc-translate/msgstate(落盤暴露面與快取相同);訊息完成後該檔案即刪除,逾期殘留檔案 24 小時後清理。
• 用 openai 時每段約一次 API 呼叫(~$0.0001),串流輸出會比純英文多約 1 秒/段的延遲;google 較快但品質略低。
• Markdown 表格保持完整:表格原樣透傳(從而保留 Claude Code 原生的框線渲染),並在其緊後展示一份翻譯後的表格副本——不再因逐行插入譯文而把表格列拆散。

🔗 關注專案

• ⭐ Star / Watch github.com/roy-jiang-opus/cctrans,第一時間獲取版本更新
• 📦 npm —— npmjs.com/package/cctrans · 升級:npm install -g cctrans@latest
• 🗺 路線圖 —— ROADMAP.md:已完成與計劃中的功能
• 📚 調研 —— MOTIVATION.md:本專案背後的非英語 token 稅資料
• 🐛 Issue / 新語言請求 —— github.com/roy-jiang-opus/cctrans/issues

📄 授權條款

MIT © Roy Jiang