cctrans 0.2.0 → 0.3.0

package/README.zh-Hant.md

@@ -1,8 +1,20 @@
-# cctranslate
+<div align="center">
+
+# cctrans
+
+**用母語讀 Claude Code——token 按英文計費。**
+
+[![npm version](https://img.shields.io/npm/v/cctrans?color=cb3837&logo=npm)](https://www.npmjs.com/package/cctrans)
+[![npm downloads](https://img.shields.io/npm/dm/cctrans?color=blue)](https://www.npmjs.com/package/cctrans)
+[![GitHub stars](https://img.shields.io/github/stars/roy-jiang-opus/cctrans?style=flat&logo=github)](https://github.com/roy-jiang-opus/cctrans)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![node](https://img.shields.io/node/v/cctrans)](package.json)
 
 [English](README.md) | [简体中文](README.zh-Hans.md) | **繁體中文** | [日本語](README.ja.md) | [한국어](README.ko.md) | [Русский](README.ru.md) | [हिन्दी](README.hi.md)
 
-為 Claude Code 加上一層**雙語對照**:每則回覆會在原始英文行下方自動補上一行譯文(中/日/韓/俄/印地),**就在對話裡**,一行英文一行譯文。
+</div>
+
+---
 
 ```
 ● I will refactor the auth module to use async tokens.
@@ -11,11 +23,41 @@
   ↳ 這會影響 3 個檔案並加入重試層。
 ```
 
-- **非破壞性**:畫面上多了譯文,但轉錄檔與模型看到的上下文**仍是純英文**——技術文件、skills、程式碼都不受影響。
-- **不污染歷史、不耗主對話 token**:翻譯由一個**獨立的低成本後端**完成,與你的 Claude Code 工作階段完全無關。
-- **一鍵開關**:預設常開;想讀純英文/程式碼時一鍵關閉。
+為 Claude Code 加上一層**雙語對照**:每行英文下方一行譯文(中/日/韓/俄/印地),**就在對話裡**——僅作顯示,轉錄、模型上下文和你的 token 帳單 100% 保持英文。
+
+## ✨ 特性
+
+- 🪞 **行內雙語顯示** —— 譯文隨回覆串流出現在每行英文下方,就在對話裡
+- 🧾 **非破壞性** —— 轉錄與模型上下文保持純英文;skills、文件、程式碼不受影響
+- 🆓 **主對話零 token** —— 翻譯走獨立低成本後端(也有免費選項),完全在 Claude Code 工作階段之外
+- ⌨️ **輸入翻譯(beta)** —— 用母語打字,模型按英文工作、按英文回覆(`cctrans input on`)
+- 🌏 **6 種目標語言** —— `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi`
+- 🔌 **6 個後端自動降級** —— OpenAI / Anthropic / DeepL / Azure / 免費 Google / 你自己的 Claude 訂閱
+- 🔒 **金鑰隔離** —— API key 只存在 chmod-600 的檔案裡,從不讀終端機環境變數
+- 🛟 **故障安全** —— 任何錯誤或逾時都回退為純英文,絕不卡住工作階段
+
+## 🚀 快速開始
+
+```bash
+npm install -g cctrans && cctrans install
+```
+
+安裝會註冊鉤子並引導你完成設定(語言 → 後端 → API key → 即時驗證)。然後**重新啟動 Claude Code**——回覆變成雙語。隨時在 Claude Code 輸入框輸入 `!cctrans off` / `!cctrans on` 開關(`!` 是 CC 內建 bash 模式,不呼叫模型、不花 token)。
+
+<details>
+<summary>從原始碼安裝</summary>
+
+```bash
+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'`
+
+</details>
 
-## 為什麼做這個
+## 🤔 為什麼做這個
 
 兩個痛點,一個架構解決:
 
@@ -33,7 +75,7 @@ Anthropic 關於按語言調整額度的 issue([#26401](https://github.com/anthr
 
 完整調研資料與來源:[MOTIVATION.md](MOTIVATION.md)。
 
-## 運作原理
+## ⚙️ 運作原理
 
 利用 Claude Code 原生的 **`MessageDisplay` 鉤子**(v2.1.152+):它在每則助理訊息渲染時觸發,把完成的文字片段(`delta`)交給鉤子;鉤子回傳的 `displayContent` **只替換螢幕顯示**,不改變儲存的訊息。
 
@@ -50,23 +92,7 @@ Claude 串流輸出英文
 
 > 已在 CC 2.1.169 實測:`delta` 是**互不重疊**的已完成片段(不是累積文字),普通 `\n` 即可讓兩種語言分行顯示,程式碼區塊/路徑/已是目標語言的行會自動跳過。
 
-## 安裝
-
-```bash
-npm install -g cctrans && cctrans install
-
-# from source:
-git clone https://github.com/roy-jiang-opus/cctranslate.git
-cd cctranslate
-node bin/cctrans.js install      # 註冊鉤子、連結 cctrans 到 ~/.local/bin,然後執行 setup 精靈
-```
-
-接著**重新啟動 Claude Code**(開新工作階段)讓鉤子生效。送出任意訊息,回覆就會雙語對照。
-
-> 需要 `~/.local/bin` 在 PATH 中;否則使用別名:
-> `alias cctrans='node /path/to/cctranslate/bin/cctrans.js'`
-
-## 使用
+## 🎛 指令
 
 | 指令 | 作用 |
 |------|------|
@@ -77,14 +103,13 @@ node bin/cctrans.js install      # 註冊鉤子、連結 cctrans 到 ~/.local/bi
 | `cctrans backends` | 列出所有引擎及其可用性 |
 | `cctrans setup` | 互動式精靈:語言、後端、API key |
 | `cctrans key [id] [value]` | 管理 `~/.cc-translate/keys.json` 中的 API key |
-| `cctrans input on` / `cctrans input off` | 把非英文輸入翻譯成英文(作為上下文傳給模型) |
+| `cctrans input on` / `cctrans input off` | **(beta)** 把非英文輸入翻譯成英文(作為上下文傳給模型) |
+| `cctrans input threshold <n>` | 觸發輸入翻譯的非拉丁字元數(預設 4) |
 | `cctrans last [N]` | 把最近(或往前第 N 則)回覆翻譯到終端機 |
 | `cctrans test <文字>` | 翻譯一段文字,驗證引擎 |
 | `cctrans install` / `cctrans uninstall` | 註冊 / 移除鉤子 |
 
-**最快的開關方式**:在 Claude Code 輸入框直接輸入 `!cctrans off` 或 `!cctrans on`(`!` 是 CC 內建的 bash 模式,不呼叫模型、不花 token)。
-
-## 翻譯後端
+## 🌐 翻譯後端
 
 | 後端 | 前提 | 速度 | 品質 | 說明 |
 |------|------|------|------|------|
@@ -101,7 +126,7 @@ API key **只**存放在 `~/.cc-translate/keys.json`(chmod 600)——用 `cctran
 
 其餘設定(後端、語言、標記、模型、Azure 端點)都在 `~/.cc-translate/state.json` 中——用 `cctrans` 指令修改或直接編輯檔案。
 
-## 多語言
+## 🗣 多語言
 
 目標語言支援 **CJK + 俄語 + 印地語**(非拉丁文字,可按 Unicode 區間零成本判斷「該行已是目標語言」並跳過):
 
@@ -116,19 +141,27 @@ cctrans lang zh-Hans  # 簡體中文(預設)
 
 中文採用 BCP-47 **文字碼**(`zh-Hans`/`zh-Hant`)——繁體是文字系統而非地區;`zh-CN` / `zh-TW` 仍可作為別名使用,會自動正規化。切換語言立即生效(鉤子每次呼叫都讀取狀態),不同語言的快取相互獨立。
 
-## 輸入翻譯
+## ⌨️ 輸入翻譯(beta)
+
+`cctrans input on` 啟用 `UserPromptSubmit` 鉤子:當你的輸入包含足夠多的非拉丁字元時(預設 4 個以上——按絕對數量計,檔案路徑和識別字不會稀釋觸發條件;用 `cctrans input threshold <n>` 調整),英文譯文會作為上下文附給模型並被視為權威指令,同時要求模型**用英文回覆**——這樣雙語 overlay 持續生效,對話上下文全程保持英文。(已在 CC 2.1.169 核實:鉤子無法改寫 prompt 本身,所以原文仍在歷史中,英文隨附。)英文輸入原樣通過;任何錯誤都安全回退為原樣送出。
 
-`cctrans input on` 啟用 `UserPromptSubmit` 鉤子:當你的輸入大多是非英文時,英文譯文會作為上下文附給模型並被視為權威指令——你繼續用母語打字,模型按英文工作。(已在 CC 2.1.169 核實:鉤子無法改寫 prompt 本身,所以原文仍在歷史中,英文隨附。)英文輸入原樣通過;任何錯誤都安全回退為原樣送出。
+> **Beta**:翻譯呼叫會在每條非英文輸入送出前阻塞約 0.5–1.5 秒。預設關閉;setup 精靈會詢問一次。回饋 → [issues](https://github.com/roy-jiang-opus/cctrans/issues)。
 
-## 行為與限制(已核實)
+## 📏 行為與限制(已核實)
 
 - 鉤子在**串流輸出中**按片段觸發,每段單獨翻譯並就地替換——所以譯文會隨英文逐段出現。
 - 鉤子有 **10 秒**逾時;本工具內部 9 秒保底。任何錯誤/逾時/超長(>9000 字元)都會**安全回退成原始英文**,絕不卡住工作階段。
 - 每行譯文按內容雜湊**快取**(`~/.cc-translate/cache`),重繪與重複文字零成本。
 - 用 `openai` 時每段約一次 API 呼叫(~$0.0001),串流輸出會比純英文多約 1 秒/段的延遲;`google` 較快但品質略低。
 
-## 解除安裝
+## 🔗 關注專案
 
-```bash
-node bin/cctrans.js uninstall    # 移除鉤子;重新啟動 Claude Code 生效
-```
+- ⭐ **Star / Watch** [github.com/roy-jiang-opus/cctrans](https://github.com/roy-jiang-opus/cctrans),第一時間獲取版本更新
+- 📦 **npm** —— [npmjs.com/package/cctrans](https://www.npmjs.com/package/cctrans) · 升級:`npm update -g cctrans`
+- 🗺 **路線圖** —— [ROADMAP.md](ROADMAP.md):已完成與計劃中的功能
+- 📚 **調研** —— [MOTIVATION.md](MOTIVATION.md):本專案背後的非英語 token 稅資料
+- 🐛 **Issue / 新語言請求** —— [github.com/roy-jiang-opus/cctrans/issues](https://github.com/roy-jiang-opus/cctrans/issues)
+
+## 📄 授權條款
+
+[MIT](LICENSE) © Roy Jiang

package/bin/cctrans.js

@@ -104,7 +104,7 @@ function uninstall() {
     if (Object.keys(s.hooks).length === 0) delete s.hooks;
     writeSettings(s);
   }
-  console.log(C.green('✓') + ' removed cctranslate hooks. Restart Claude Code to take effect.');
+  console.log(C.green('✓') + ' removed cctrans hooks. Restart Claude Code to take effect.');
 }
 
 function status() {
@@ -112,12 +112,12 @@ function status() {
   const installed = hookInstalled();
   const b = getBackend(st.backend);
   const lang = getLang(st.target);
-  console.log(C.bold('cctranslate status'));
+  console.log(C.bold('cctrans status'));
   console.log('  enabled : ' + (st.enabled ? C.green('ON') : C.red('OFF')));
   console.log('  hook    : ' + (installed ? C.green('installed') : C.red('not installed') + C.dim('  (run: cctrans install)')));
   console.log('  backend : ' + st.backend + (b ? (b.available() ? C.green('  (ready)') : C.red('  (missing: ' + b.needs + ')')) : C.red('  (unknown backend)')));
   console.log('  lang    : ' + st.target + (lang ? C.dim('  (' + lang.name + ')') : C.red('  (unsupported — see: cctrans lang)')));
-  console.log('  input   : ' + (st.inputEn ? C.green('ON') : 'off') + C.dim('  (prompt -> English; toggle: cctrans input on|off)'));
+  console.log('  input   : ' + (st.inputEn ? C.green('ON') : 'off') + C.dim('  (beta; prompt -> English; toggle: cctrans input on|off; triggers at ' + st.inputMinChars + '+ non-Latin chars)'));
   console.log('  keys    : ' + Object.keys(keys.readKeys()).length + ' in ' + keys.KEYS_FILE + C.dim('  (manage: cctrans key)'));
   console.log('  state   : ' + STATE_FILE);
 }
@@ -179,7 +179,8 @@ function help() {
 
 ${C.bold('Control')}
   cctrans on | off | toggle      turn the inline translation on/off
-  cctrans input on | off         translate non-English input to English (as context)
+  cctrans input on | off         (beta) translate non-English input to English (as context)
+  cctrans input threshold <n>    non-Latin chars that trigger input translation (default 4)
   cctrans status                 show current state
   cctrans lang [code]            show/set target language (zh-Hans, zh-Hant, ja, ko, ru, hi)
   cctrans backend <id>           choose translation engine
@@ -188,7 +189,7 @@ ${C.bold('Control')}
 ${C.bold('Setup')}
   cctrans install                register hooks (+ link cctrans), then run setup
   cctrans setup                  interactive wizard: language, backend, API keys
-                            (flags: --lang --backend --key --yes)
+                            (flags: --lang --backend --key --input --yes)
   cctrans key [id] [value]       manage API keys in ~/.cc-translate/keys.json
                             (ids: openai, anthropic, deepl, azure, azure-region)
   cctrans uninstall              remove the hooks
@@ -242,6 +243,7 @@ async function main() {
         lang: flag('--lang'),
         backend: flag('--backend'),
         key: flag('--key'),
+        input: flag('--input'),
         yes: rest.includes('--yes'),
       });
       break;
@@ -251,8 +253,17 @@ async function main() {
       const sub = rest[0];
       if (sub === 'on' || sub === 'off') setState({ inputEn: sub === 'on' });
       else if (sub === 'toggle') setState({ inputEn: !getState().inputEn });
+      else if (sub === 'threshold' && rest[1] !== undefined) {
+        const n = parseInt(rest[1], 10);
+        if (!Number.isInteger(n) || n < 1) {
+          console.error('usage: cctrans input threshold <n>   (non-Latin chars in a prompt that trigger translation; n >= 1)');
+          process.exit(1);
+        }
+        setState({ inputMinChars: n });
+      }
       const st = getState();
-      console.log('input translation (prompt -> English): ' + (st.inputEn ? C.green('ON') : C.red('OFF')) +
+      console.log('input translation ' + C.dim('(beta)') + ' (prompt -> English): ' + (st.inputEn ? C.green('ON') : C.red('OFF')) +
+        C.dim('  threshold: ' + st.inputMinChars + ' non-Latin chars (set: cctrans input threshold <n>)') +
         (inputHookInstalled() ? '' : C.red('  (hook not installed — run: cctrans install)')));
       break;
     }

package/hook/user-prompt-submit.js

@@ -16,7 +16,7 @@
 
 const { getState } = require('../src/config');
 const { translateLines } = require('../src/translate');
-const { nonLatinRatio } = require('../src/langs');
+const { nonLatinCount } = require('../src/langs');
 
 function passThrough() { process.exit(0); }
 
@@ -37,8 +37,11 @@ process.stdin.on('end', async () => {
   try { st = getState(); } catch (e) { return passThrough(); }
   if (!st.inputEn) return passThrough();
 
-  // Only act on prompts that are substantially non-English.
-  if (nonLatinRatio(prompt) < 0.2) return passThrough();
+  // Trigger on an absolute count of non-Latin chars (configurable:
+  // `cctrans input threshold <n>`), NOT a ratio — coding prompts are mostly
+  // Latin paths/identifiers, which would dilute a ratio below any threshold.
+  const min = Number.isInteger(st.inputMinChars) && st.inputMinChars > 0 ? st.inputMinChars : 4;
+  if (nonLatinCount(prompt) < min) return passThrough();
 
   const guard = setTimeout(passThrough, 9000);
   try {
@@ -52,7 +55,8 @@ process.stdin.on('end', async () => {
         hookEventName: 'UserPromptSubmit',
         additionalContext:
           'English translation of the user\'s prompt (translated by a local tool; ' +
-          'treat it as the canonical instruction):\n' + en,
+          'treat it as the canonical instruction). Respond in English — a local ' +
+          'overlay renders your reply bilingually for the user:\n' + en,
       },
     }));
     process.exit(0);

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "cctrans",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Bilingual inline translation overlay for Claude Code: a translated line (zh/ja/ko/ru/hi) under each English line, right in the conversation — non-destructive, zero main-loop tokens.",
   "license": "MIT",
   "author": "Roy Jiang",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/roy-jiang-opus/cctranslate.git"
+    "url": "git+https://github.com/roy-jiang-opus/cctrans.git"
   },
-  "homepage": "https://github.com/roy-jiang-opus/cctranslate#readme",
+  "homepage": "https://github.com/roy-jiang-opus/cctrans#readme",
   "bugs": {
-    "url": "https://github.com/roy-jiang-opus/cctranslate/issues"
+    "url": "https://github.com/roy-jiang-opus/cctrans/issues"
   },
   "keywords": [
     "claude-code",

package/src/config.js

@@ -29,7 +29,8 @@ function defaults() {
     anthropicModel: 'claude-haiku-4-5', // anthropic backend model
     azureEndpoint: 'https://api.cognitive.microsofttranslator.com',
     marker: '↳ ', // prefix on each translated line
-    inputEn: false, // input translation (prompt -> English) off until enabled
+    inputEn: false, // input translation (beta, prompt -> English) off until enabled
+    inputMinChars: 4, // non-Latin chars in a prompt that trigger input translation
   };
 }
 
@@ -52,6 +53,7 @@ function setState(patch) {
     azureEndpoint: next.azureEndpoint,
     marker: next.marker,
     inputEn: next.inputEn,
+    inputMinChars: next.inputMinChars,
   };
   const tmp = STATE_FILE + '.' + process.pid + '.tmp';
   fs.writeFileSync(tmp, JSON.stringify(persist, null, 2));

package/src/langs.js

@@ -52,10 +52,10 @@ const LANGS = {
 // supported non-English languages?" Used by the input-translation hook.
 const NON_LATIN = /[一-鿿㐀-䶿぀-ゟ゠-ヿ가-힯ᄀ-ᇿЀ-ӿऀ-ॿ]/g;
 
-function nonLatinRatio(text) {
-  const hits = (text.match(NON_LATIN) || []).length;
-  const nonspace = text.replace(/\s/g, '').length;
-  return nonspace === 0 ? 0 : hits / nonspace;
+// Absolute count, not a ratio: coding prompts are full of Latin paths and
+// identifiers that would dilute any ratio below a usable threshold.
+function nonLatinCount(text) {
+  return (text.match(NON_LATIN) || []).length;
 }
 
 // Region-code (and bare-zh) aliases -> canonical script codes.
@@ -91,4 +91,4 @@ function isProbablyTarget(line, code) {
   return nonspace > 0 && hits / nonspace >= 0.3;
 }
 
-module.exports = { LANGS, getLang, listLangs, isProbablyTarget, normalizeLang, nonLatinRatio };
+module.exports = { LANGS, getLang, listLangs, isProbablyTarget, normalizeLang, nonLatinCount };

package/src/setup.js

@@ -1,8 +1,8 @@
 'use strict';
-// Interactive setup wizard: language -> backend -> API-key entry -> live
-// verification -> save. Re-runnable via `cctrans setup`; non-interactive with
-// flags (--lang, --backend, --key, --yes). Keys go to keys.json only — the
-// shell environment is never read.
+// Interactive setup wizard: language -> backend -> API-key entry -> input
+// translation (beta) -> live verification -> save. Re-runnable via `cctrans
+// setup`; non-interactive with flags (--lang, --backend, --key, --input,
+// --yes). Keys go to keys.json only — the shell environment is never read.
 
 const readline = require('node:readline/promises');
 const { getState, setState } = require('./config');
@@ -32,7 +32,7 @@ async function runSetup(opts) {
   };
 
   try {
-    console.log(C.bold('cctranslate setup') + C.dim('  (re-run anytime: cctrans setup)'));
+    console.log(C.bold('cctrans setup') + C.dim('  (re-run anytime: cctrans setup)'));
 
     // 1. Target language
     let lang = opts.lang;
@@ -73,12 +73,24 @@ async function runSetup(opts) {
       }
     }
 
-    // 4. Save config
-    setState({ target: lang, backend });
+    // 4. Input translation (beta, opt-in): prompt -> English as context
+    let inputEn = typeof opts.input === 'string' ? opts.input === 'on' : getState().inputEn;
+    if (opts.input === undefined && rl) {
+      console.log('\n' + C.bold('Input translation') + ' ' + C.dim('(beta)') +
+        ' — type prompts in your language; an English translation is\n' +
+        'attached as context and the model is asked to reply in English (the original\n' +
+        'prompt stays in your history; adds ~0.5–1.5s per non-English prompt).');
+      const a = await ask('Enable input translation? (y/N)', inputEn ? 'y' : 'n');
+      inputEn = /^y(es)?$/i.test(a);
+    }
+
+    // 5. Save config
+    setState({ target: lang, backend, inputEn });
     console.log('\n' + C.green('✓') + ' saved: lang=' + lang + ' (' + getLang(lang).name + '), backend=' + backend +
+      ', input=' + (inputEn ? 'on' : 'off') +
       (b.available() ? '' : C.red('  (no key yet — will fall back to google)')));
 
-    // 5. Live verification
+    // 6. Live verification
     process.stdout.write(C.dim('verifying… '));
     try {
       const { displayContent } = await buildDisplayContent('Setup verification: translation works.\n', {
@@ -89,7 +101,10 @@ async function runSetup(opts) {
       console.log(C.red('verification failed: ' + e.message));
     }
 
-    console.log(C.dim('\nNext: restart Claude Code (new session). Toggle with `!cctrans off` / `!cctrans on`; input translation: `cctrans input on`.'));
+    console.log(C.dim('\nNext: restart Claude Code (new session). Toggle with `!cctrans off` / `!cctrans on`. ' +
+      (inputEn
+        ? 'Input translation (beta) is ON — disable: `cctrans input off`.'
+        : 'Input translation (beta): `cctrans input on`.')));
     return true;
   } finally {
     if (rl) rl.close();