cctrans 0.2.1 → 0.4.0

package/README.zh-Hant.md

@@ -1,8 +1,20 @@
+<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,42 @@
   ↳ 這會影響 3 個檔案並加入重試層。
 ```
 
-- **非破壞性**:畫面上多了譯文,但轉錄檔與模型看到的上下文**仍是純英文**——技術文件、skills、程式碼都不受影響。
-- **不污染歷史、不耗主對話 token**:翻譯由一個**獨立的低成本後端**完成,與你的 Claude Code 工作階段完全無關。
-- **一鍵開關**:預設常開;想讀純英文/程式碼時一鍵關閉。
+為 Claude Code 加上一層**雙語對照**:每行英文下方一行譯文(中/日/韓/俄/印地),**就在對話裡**——僅作顯示,轉錄、模型上下文和你的 token 帳單 100% 保持英文。
+
+## ✨ 特性
+
+- 🪞 **行內雙語顯示** —— 譯文隨回覆串流出現在每行英文下方,就在對話裡
+- 🧩 **兩種排版** —— 逐行對照,或 `cctrans mode section`:整塊英文先出,再跟一段成組譯文
+- 🧾 **非破壞性** —— 轉錄與模型上下文保持純英文;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 +76,7 @@ Anthropic 關於按語言調整額度的 issue([#26401](https://github.com/anthr
 
 完整調研資料與來源:[MOTIVATION.md](MOTIVATION.md)。
 
-## 運作原理
+## ⚙️ 運作原理
 
 利用 Claude Code 原生的 **`MessageDisplay` 鉤子**(v2.1.152+):它在每則助理訊息渲染時觸發,把完成的文字片段(`delta`)交給鉤子;鉤子回傳的 `displayContent` **只替換螢幕顯示**,不改變儲存的訊息。
 
@@ -50,41 +93,47 @@ Claude 串流輸出英文
 
 > 已在 CC 2.1.169 實測:`delta` 是**互不重疊**的已完成片段(不是累積文字),普通 `\n` 即可讓兩種語言分行顯示,程式碼區塊/路徑/已是目標語言的行會自動跳過。
 
-## 安裝
-
-```bash
-npm install -g cctrans && cctrans install
-
-# from source:
-git clone https://github.com/roy-jiang-opus/cctrans.git
-cd cctrans
-node bin/cctrans.js install      # 註冊鉤子、連結 cctrans 到 ~/.local/bin,然後執行 setup 精靈
-```
-
-接著**重新啟動 Claude Code**(開新工作階段)讓鉤子生效。送出任意訊息,回覆就會雙語對照。
-
-> 需要 `~/.local/bin` 在 PATH 中;否則使用別名:
-> `alias cctrans='node /path/to/cctrans/bin/cctrans.js'`
-
-## 使用
+## 🎛 指令
 
 | 指令 | 作用 |
 |------|------|
 | `cctrans on` / `cctrans off` / `cctrans toggle` | 開 / 關 / 切換翻譯 |
 | `cctrans status` | 檢視狀態(開關、鉤子、後端、語言) |
 | `cctrans lang [code]` | 檢視/切換目標語言:`zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans mode [line\|section]` | 排版:譯文跟在每行下方,或按區塊成組 |
 | `cctrans backend <id>` | 切換翻譯引擎 |
 | `cctrans backends` | 列出所有引擎及其可用性 |
-| `cctrans setup` | 互動式精靈:語言、後端、API key |
+| `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)。
+## 🧩 顯示模式
+
+`line`(預設)逐行對照:每行英文下方一行譯文,隨回覆串流出現。`section` 讓英文完全按 Claude 的串流輸出原樣呈現,在**一個區塊完成時**插入一段成組譯文——對列表很多的回覆要安靜得多:
 
-## 翻譯後端
+```
+Use these flags:
+↳ 使用以下参数：
+
+- Enable the cache
+- Set a small timeout
+- Prefer the batch API
+  ↳ 启用缓存
+  ↳ 设置较短的超时
+  ↳ 优先使用批量 API
+```
+
+```bash
+cctrans mode section   # 隨時切回:cctrans mode line
+```
+
+> section 模式下,一個區塊的譯文在**該區塊完成時**才出現,而不是邊串流邊出——後端慢時(如 `claude-code`,3–6 秒/次)這個停頓會比較明顯,所以這裡 API 後端體驗最好。某個區塊翻譯失敗時,英文不受影響,該區塊只是保持未翻譯。
+
+## 🌐 翻譯後端
 
 | 後端 | 前提 | 速度 | 品質 | 說明 |
 |------|------|------|------|------|
@@ -101,7 +150,7 @@ API key **只**存放在 `~/.cc-translate/keys.json`(chmod 600)——用 `cctran
 
 其餘設定(後端、語言、標記、模型、Azure 端點)都在 `~/.cc-translate/state.json` 中——用 `cctrans` 指令修改或直接編輯檔案。
 
-## 多語言
+## 🗣 多語言
 
 目標語言支援 **CJK + 俄語 + 印地語**(非拉丁文字,可按 Unicode 區間零成本判斷「該行已是目標語言」並跳過):
 
@@ -116,19 +165,28 @@ cctrans lang zh-Hans  # 簡體中文(預設)
 
 中文採用 BCP-47 **文字碼**(`zh-Hans`/`zh-Hant`)——繁體是文字系統而非地區;`zh-CN` / `zh-TW` 仍可作為別名使用,會自動正規化。切換語言立即生效(鉤子每次呼叫都讀取狀態),不同語言的快取相互獨立。
 
-## 輸入翻譯
+## ⌨️ 輸入翻譯(beta)
 
-`cctrans input on` 啟用 `UserPromptSubmit` 鉤子:當你的輸入大多是非英文時,英文譯文會作為上下文附給模型並被視為權威指令——你繼續用母語打字,模型按英文工作。(已在 CC 2.1.169 核實:鉤子無法改寫 prompt 本身,所以原文仍在歷史中,英文隨附。)英文輸入原樣通過;任何錯誤都安全回退為原樣送出。
+`cctrans input on` 啟用 `UserPromptSubmit` 鉤子:當你的輸入包含足夠多的非拉丁字元時(預設 4 個以上——按絕對數量計,檔案路徑和識別字不會稀釋觸發條件;用 `cctrans input threshold <n>` 調整),英文譯文會作為上下文附給模型並被視為權威指令,同時要求模型**用英文回覆**——這樣雙語 overlay 持續生效,對話上下文全程保持英文。(已在 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`),重繪與重複文字零成本。
+- 每行譯文按內容雜湊**快取**(`~/.cc-translate/cache`),重繪與重複文字零成本。兩種模式共享同一快取。
+- section 模式下,進行中區塊的文字會緩衝在 `~/.cc-translate/msgstate`(落盤暴露面與快取相同);訊息完成後該檔案即刪除,逾期殘留檔案 24 小時後清理。
 - 用 `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/ROADMAP.md

@@ -2,11 +2,14 @@
 
 ## Shipped
 
+### ✅ Section display mode — grouped translation per block
+`cctrans mode section` (default stays `line`): English streams untouched, and a block's translation is spliced in as one grouped `↳` block when the block completes (blank line / code fence / already-target line / end of message) — much quieter for list-heavy replies. Design notes: section boundaries are properties of the **text**, never of delta chunking (deltas batch arbitrarily — verified live), which makes repaint replay byte-identical; the open block buffers in `~/.cc-translate/msgstate` (atomic writes, removed on message end, 24h GC); state is committed **before** translation, so a crash/timeout can only drop a block's translation, never misplace it. Headings close their own section (a displaced `## ↳ 译` would render as a real heading). Translation stays per-line, so both modes share the sha1 cache and the backends are untouched. The boundary machinery trivially supports a future `message` granularity (flush at final only).
+
 ### ✅ Input translation — write in your language, send in English
 `cctrans input on` enables a `UserPromptSubmit` hook: prompts that are mostly non-English get an English translation attached as `additionalContext`, which the model treats as the canonical instruction. Implementation note: Claude Code hooks provably cannot rewrite the prompt itself (verified against the 2.1.169 **and 2.1.170** binaries — the `UserPromptSubmit`/`UserPromptExpansion` output schemas only allow `additionalContext` and block), so attach-as-context is the strongest available form; the original prompt stays in history with the English alongside. If a future CC release adds a prompt-rewrite field, switching to true replacement is a one-line change in `hook/user-prompt-submit.js`.
 
 ### ✅ Interactive setup wizard
-`cctrans install` registers both hooks and launches the wizard; `cctrans setup` re-runs it anytime. Walks through target language → backend selection → key entry for the chosen backend → live translation verification. Non-interactive flags: `--lang`, `--backend`, `--key`, `--yes`.
+`cctrans install` registers both hooks and launches the wizard; `cctrans setup` re-runs it anytime. Walks through target language → display mode → backend selection → key entry for the chosen backend → live translation verification. Non-interactive flags: `--lang`, `--mode`, `--backend`, `--key`, `--yes`.
 
 ### ✅ Per-tool API-key config (no env cross-pollution)
 Keys live **only** in `~/.cc-translate/keys.json` (chmod 600, atomic writes), managed via `cctrans key <id> [value|--clear]`, the setup wizard, or direct file edits. Shell environment variables are **never** consulted — no overrides, no opt-in. All non-secret settings (backend, language, marker, models, Azure endpoint) live in `~/.cc-translate/state.json`. The only env vars the tool reads are internal plumbing: `CCTRANS_HOME` / `CCTRANS_TRANSCRIPT` (tests) and `CCTRANS_DISABLE` / `CCTRANS_DEBUG_STDIN` (hook internals).

package/bin/cctrans.js

@@ -13,8 +13,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const { getState, setState, STATE_FILE } = require('../src/config');
-const { buildDisplayContent } = require('../src/interleave');
+const { getState, setState, STATE_FILE, MODES, sweepMsgState } = require('../src/config');
+const { buildDisplayContent, planSections, renderSections } = require('../src/interleave');
 const { findTranscript, extractReply } = require('../src/transcript');
 const { listBackends, getBackend } = require('../src/backends');
 const { getLang, listLangs, normalizeLang } = require('../src/langs');
@@ -117,7 +117,10 @@ function status() {
   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('  mode    : ' + st.mode + C.dim(st.mode === 'section'
+    ? '  (grouped per block; translation appears when the block completes)'
+    : '  (translation under each English line)'));
+  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);
 }
@@ -150,17 +153,30 @@ function backends() {
 }
 
 function colorizeForTerminal(displayContent, marker) {
+  // Match the marker after optional structure prefixes too ("## ↳", "> ↳",
+  // list-indent "  ↳") so grouped section blocks color consistently.
+  const zhLine = new RegExp('^\\s*(?:#{1,6}\\s+|(?:>\\s*)+)?\\s*' + marker.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
   return displayContent
     .split('\n')
-    .map((l) => (l.startsWith(marker) ? C.cyan(l) : l))
+    .map((l) => (zhLine.test(l) ? C.cyan(l) : l))
     .join('\n');
 }
 
 async function renderText(text) {
   const st = getState();
-  const { displayContent } = await buildDisplayContent(text, {
-    target: st.target, backend: st.backend, model: st.model, marker: st.marker, timeoutMs: 12000,
-  });
+  let displayContent;
+  if (st.mode === 'section') {
+    // The whole text is one final delta, so `cctrans test`/`last` exercise
+    // section mode end-to-end.
+    const planned = planSections(text, { inFence: false, buf: [], target: st.target, final: true });
+    displayContent = await renderSections(planned, {
+      target: st.target, backend: st.backend, model: st.model, marker: st.marker, timeoutMs: 12000,
+    });
+  } else {
+    displayContent = (await buildDisplayContent(text, {
+      target: st.target, backend: st.backend, model: st.model, marker: st.marker, timeoutMs: 12000,
+    })).displayContent;
+  }
   if (displayContent == null) { process.stdout.write(text + '\n'); return; }
   process.stdout.write(colorizeForTerminal(displayContent, st.marker) + '\n');
 }
@@ -179,16 +195,18 @@ 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 mode [line|section]    layout: translation under each line, or grouped per block
   cctrans backend <id>           choose translation engine
   cctrans backends               list engines + availability
 
 ${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)
+  cctrans setup                  interactive wizard: language, display mode, backend, API keys
+                            (flags: --lang --mode --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
@@ -203,8 +221,8 @@ ${C.dim('Tip: toggle from inside Claude Code by typing  !cctrans off  /  !cctran
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
   switch (cmd) {
-    case 'on': setState({ enabled: true }); console.log(C.green('✓ translation ON')); break;
-    case 'off': setState({ enabled: false }); console.log('✓ translation ' + C.red('OFF')); break;
+    case 'on': setState({ enabled: true }); sweepMsgState(24 * 60 * 60 * 1000); console.log(C.green('✓ translation ON')); break;
+    case 'off': setState({ enabled: false }); sweepMsgState(0); console.log('✓ translation ' + C.red('OFF')); break;
     case 'toggle': { const s = getState(); const n = setState({ enabled: !s.enabled }); console.log('✓ translation ' + (n.enabled ? C.green('ON') : C.red('OFF'))); break; }
     case 'backend': {
       const id = rest[0];
@@ -218,6 +236,20 @@ async function main() {
       break;
     }
     case 'backends': backends(); break;
+    case 'mode': {
+      const m = rest[0];
+      if (!m) {
+        const st = getState();
+        console.log('mode = ' + st.mode + C.dim('  (available: line — translation under each English line; section — grouped per block)'));
+        break;
+      }
+      if (!MODES.includes(m)) { console.error('usage: cctrans mode <' + MODES.join('|') + '>'); process.exit(1); }
+      setState({ mode: m });
+      console.log(C.green('✓') + ' mode = ' + m + C.dim(m === 'section'
+        ? '  (English streams as-is; each block\'s translation appears when the block completes)'
+        : '  (translation under each English line)'));
+      break;
+    }
     case 'lang': {
       const code = rest[0];
       if (!code) { const st = getState(); console.log('lang = ' + st.target + C.dim('  (available: ' + listLangs().join(', ') + '; aliases: zh-CN, zh-TW)')); break; }
@@ -240,8 +272,10 @@ async function main() {
       const flag = (name) => { const i = rest.indexOf(name); return i > -1 ? rest[i + 1] : undefined; };
       await require('../src/setup').runSetup({
         lang: flag('--lang'),
+        mode: flag('--mode'),
         backend: flag('--backend'),
         key: flag('--key'),
+        input: flag('--input'),
         yes: rest.includes('--yes'),
       });
       break;
@@ -251,8 +285,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/message-display.js

@@ -6,39 +6,67 @@
 //   delta = the newly completed lines of the streaming assistant message.
 //           Deltas are non-overlapping; a code fence (```) can span deltas.
 // stdout (JSON, exit 0): { hookSpecificOutput: { hookEventName: "MessageDisplay",
-//                          displayContent: "<EN line>\n↳ <ZH line> ..." } }
+//                          displayContent: "..." } }
 //   displayContent REPLACES the delta on screen. Display-only: the transcript
 //   and the model's context keep the original English.
 //
+// Two layouts (state.json "mode"):
+//   line     — every prose line gets its "↳ 译" immediately (buildDisplayContent)
+//   section  — English passes through untouched; prose lines buffer in msgstate
+//              and a grouped ZH block is spliced in when the section closes
+//              (planSections + renderSections)
+//
 // Safety contract: on disabled / empty / error / timeout, emit NOTHING and
 // exit 0 so Claude Code renders the original English delta unchanged. This hook
 // must never break or stall the user's session.
 
 const fs = require('fs');
 const path = require('path');
-const { getState, BASE } = require('../src/config');
-const { buildDisplayContent } = require('../src/interleave');
+const { getState, MSGSTATE_DIR, sweepMsgState } = require('../src/config');
+const { buildDisplayContent, planSections, renderSections } = require('../src/interleave');
 
 function showOriginal() { process.exit(0); } // no stdout => CC keeps the original delta
 
-// Per-message code-fence state, so "inside a ``` block?" carries across the
-// deltas of one message. Reset at index 0 (also covers full repaints, which
-// re-send the message from index 0); removed when the message completes.
-const MSGDIR = path.join(BASE, 'msgstate');
-function fenceFile(id) { return path.join(MSGDIR, String(id).replace(/[^\w.-]/g, '_') + '.json'); }
-function loadFence(id, index) {
-  if (!id || index === 0) return false;
-  try { return !!JSON.parse(fs.readFileSync(fenceFile(id), 'utf8')).inFence; } catch (e) { return false; }
+// Per-message state, so "inside a ``` block?" and the open section's buffered
+// lines carry across the deltas of one message (fresh process per delta).
+// Reset at index 0 (also covers full repaints, which re-send the message from
+// index 0); removed when the message completes. Schema {v, mode, index,
+// inFence, buf}; a version/mode mismatch or unparseable file reads as fresh.
+const STATE_V = 2;
+function stateFile(id) { return path.join(MSGSTATE_DIR, String(id).replace(/[^\w.-]/g, '_') + '.json'); }
+function loadMsgState(id, index, mode) {
+  const fresh = { inFence: false, buf: [] };
+  if (!id || index === 0) return fresh;
+  try {
+    const st = JSON.parse(fs.readFileSync(stateFile(id), 'utf8'));
+    if (st.v !== STATE_V || st.mode !== mode) return fresh;
+    // Index gap = an earlier delta crashed before saving. Drop the buffer so
+    // two sections can never be translated as one block at a later boundary;
+    // keep the fence flag best-effort (same exposure line mode has today).
+    if (st.index !== index - 1) return { inFence: !!st.inFence, buf: [] };
+    return { inFence: !!st.inFence, buf: Array.isArray(st.buf) ? st.buf : [] };
+  } catch (e) { return fresh; }
 }
-function saveFence(id, index, inFence, final) {
+function saveMsgState(id, index, mode, inFence, buf, final) {
   if (!id) return;
   try {
-    if (final) { try { fs.unlinkSync(fenceFile(id)); } catch (e) {} return; }
-    fs.mkdirSync(MSGDIR, { recursive: true });
-    fs.writeFileSync(fenceFile(id), JSON.stringify({ index, inFence }));
+    if (final) { try { fs.unlinkSync(stateFile(id)); } catch (e) {} return; }
+    fs.mkdirSync(MSGSTATE_DIR, { recursive: true });
+    const f = stateFile(id);
+    const tmp = f + '.' + process.pid + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify({ v: STATE_V, mode, index, inFence, buf }));
+    fs.renameSync(tmp, f); // atomic: buf files are big enough for torn writes to matter
+    if (index === 0) sweepMsgState(24 * 60 * 60 * 1000); // GC files leaked by killed sessions
   } catch (e) {}
 }
 
+function emit(displayContent) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'MessageDisplay', displayContent: displayContent },
+  }));
+  process.exit(0);
+}
+
 let data = '';
 process.stdin.on('data', (d) => (data += d));
 process.stdin.on('end', async () => {
@@ -49,7 +77,6 @@ process.stdin.on('end', async () => {
   try { inp = JSON.parse(data); } catch (e) { return showOriginal(); }
 
   const delta = typeof inp.delta === 'string' ? inp.delta : '';
-  if (!delta) return showOriginal();
 
   // Recursion guard: the claude-code backend spawns `claude -p` with
   // CCTRANS_DISABLE=1 so a child Claude process can never re-enter this hook.
@@ -62,22 +89,48 @@ process.stdin.on('end', async () => {
   const id = inp.message_id;
   const index = typeof inp.index === 'number' ? inp.index : 0;
   const final = inp.final === true;
-  const inFence0 = loadFence(id, index);
+
+  if (st.mode === 'section') {
+    const ms = loadMsgState(id, index, 'section');
+    // An empty delta still flushes when it is the final one and lines are buffered.
+    if (!delta && !(final && ms.buf.length)) return showOriginal();
+    const guard = setTimeout(showOriginal, 9000);
+    try {
+      const planned = planSections(delta, { inFence: ms.inFence, buf: ms.buf, target: st.target, final: final });
+      // Commit state BEFORE translating (flushed sections already pruned from
+      // buf): a crash/timeout past this point can only drop a section's
+      // translation, never replay it at a wrong position.
+      saveMsgState(id, index, 'section', planned.inFence, planned.buf, final);
+      if (!planned.flushes.length) { clearTimeout(guard); return showOriginal(); }
+      const displayContent = await renderSections(planned, {
+        target: st.target, backend: st.backend, model: st.model, marker: st.marker,
+        timeoutMs: 5500, // smaller than line mode's 8000 so the google fallback keeps ~3s under the 9s guard
+      });
+      clearTimeout(guard);
+      if (displayContent == null) return showOriginal();
+      emit(displayContent);
+    } catch (e) {
+      clearTimeout(guard);
+      return showOriginal();
+    }
+    return;
+  }
+
+  // line mode
+  if (!delta) return showOriginal();
+  const ms = loadMsgState(id, index, 'line');
 
   // Guard below Claude Code's 10s MessageDisplay timeout so we always exit clean.
   const guard = setTimeout(showOriginal, 9000);
   try {
     const { displayContent, inFence } = await buildDisplayContent(delta, {
       target: st.target, backend: st.backend, model: st.model,
-      marker: st.marker, timeoutMs: 8000, inFence: inFence0,
+      marker: st.marker, timeoutMs: 8000, inFence: ms.inFence,
     });
     clearTimeout(guard);
-    saveFence(id, index, inFence, final); // persist even when nothing was translated
+    saveMsgState(id, index, 'line', inFence, [], final); // persist even when nothing was translated
     if (displayContent == null) return showOriginal();
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: { hookEventName: 'MessageDisplay', displayContent: displayContent },
-    }));
-    process.exit(0);
+    emit(displayContent);
   } catch (e) {
     clearTimeout(guard);
     return showOriginal();

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,6 +1,6 @@
 {
   "name": "cctrans",
-  "version": "0.2.1",
+  "version": "0.4.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",
@@ -39,6 +39,6 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/fence.js"
+    "test": "node test/fence.js && node test/markdown.js && node test/section.js"
   }
 }

package/src/config.js

@@ -14,6 +14,23 @@ const HOME = os.homedir();
 const BASE = process.env.CCTRANS_HOME || path.join(HOME, '.cc-translate');
 const STATE_FILE = path.join(BASE, 'state.json');
 const CACHE_DIR = path.join(BASE, 'cache');
+const MSGSTATE_DIR = path.join(BASE, 'msgstate');
+
+// Display layouts. Validate against this list everywhere (CLI, setup, hook) so
+// a future granularity (e.g. 'message') is a one-line addition.
+const MODES = ['line', 'section'];
+
+// Remove per-message state files older than maxAgeMs (0 = all). Sessions
+// killed mid-message leave their file behind; swept here and on index-0 saves.
+function sweepMsgState(maxAgeMs) {
+  try {
+    const cutoff = Date.now() - (maxAgeMs || 0);
+    for (const f of fs.readdirSync(MSGSTATE_DIR)) {
+      const p = path.join(MSGSTATE_DIR, f);
+      try { if (fs.statSync(p).mtimeMs <= cutoff) fs.unlinkSync(p); } catch (e) {}
+    }
+  } catch (e) {}
+}
 
 function ensureDirs() {
   try { fs.mkdirSync(CACHE_DIR, { recursive: true }); } catch (e) {}
@@ -29,7 +46,9 @@ 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
+    mode: 'line', // display layout: 'line' (ZH under each line) or 'section' (grouped per block)
+    inputEn: false, // input translation (beta, prompt -> English) off until enabled
+    inputMinChars: 4, // non-Latin chars in a prompt that trigger input translation
   };
 }
 
@@ -51,7 +70,9 @@ function setState(patch) {
     anthropicModel: next.anthropicModel,
     azureEndpoint: next.azureEndpoint,
     marker: next.marker,
+    mode: next.mode,
     inputEn: next.inputEn,
+    inputMinChars: next.inputMinChars,
   };
   const tmp = STATE_FILE + '.' + process.pid + '.tmp';
   fs.writeFileSync(tmp, JSON.stringify(persist, null, 2));
@@ -59,4 +80,4 @@ function setState(patch) {
   return next;
 }
 
-module.exports = { HOME, BASE, STATE_FILE, CACHE_DIR, ensureDirs, getState, setState, defaults };
+module.exports = { HOME, BASE, STATE_FILE, CACHE_DIR, MSGSTATE_DIR, MODES, ensureDirs, getState, setState, defaults, sweepMsgState };