cctrans 0.2.1 → 0.3.0

package/README.md

@@ -1,8 +1,20 @@
+<div align="center">
+
 # cctrans
 
+**Read Claude Code in your language — pay tokens in English.**
+
+[![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.zh-Hans.md) | [繁體中文](README.zh-Hant.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Русский](README.ru.md) | [हिन्दी](README.hi.md)
 
-A **bilingual overlay** for Claude Code: every reply gets a translated line (Chinese / Japanese / Korean / Russian / Hindi) under each original English line, **right in the conversation**.
+</div>
+
+---
 
 ```
 ● I will refactor the auth module to use async tokens.
@@ -11,11 +23,41 @@ A **bilingual overlay** for Claude Code: every reply gets a translated line (Chi
   ↳ 这涉及 3 个文件并添加重试层。
 ```
 
-- **Non-destructive**: the translation only appears on screen — the transcript and the model's context **stay pure English**, so skills, docs, and code are unaffected.
-- **No history pollution, no main-loop tokens**: translation runs through a **separate cheap backend**, completely outside your Claude Code session.
-- **One-key toggle**: on by default; switch it off instantly when you want plain English.
+A **bilingual overlay** for Claude Code: a translated line (Chinese / Japanese / Korean / Russian / Hindi) under each English line, **right in the conversation** — display-only, so the transcript, the model's context, and your token bill stay 100% English.
+
+## ✨ Features
+
+- 🪞 **Inline bilingual display** — the translation appears under each English line, in the conversation itself, streaming along with the reply
+- 🧾 **Non-destructive** — transcript and model context stay pure English; skills, docs, and code are untouched
+- 🆓 **Zero main-loop tokens** — translation runs through a separate cheap backend (or a free one), completely outside your Claude Code session
+- ⌨️ **Input translation (beta)** — type prompts in your language; the model works — and replies — in English (`cctrans input on`)
+- 🌏 **6 target languages** — `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi`
+- 🔌 **6 backends with auto-fallback** — OpenAI / Anthropic / DeepL / Azure / free Google / your own Claude subscription
+- 🔒 **Key isolation** — API keys live only in a chmod-600 file; shell env vars are never read
+- 🛟 **Fail-safe** — any error or timeout falls back to plain English; it never blocks your session
+
+## 🚀 Quick start
+
+```bash
+npm install -g cctrans && cctrans install
+```
+
+The install registers the hooks and walks you through setup (language → backend → API key → live verification). Then **restart Claude Code** — replies become bilingual. Toggle anytime by typing `!cctrans off` / `!cctrans on` inside Claude Code (`!` is CC's built-in bash mode — no model call, no tokens).
+
+<details>
+<summary>Install from source</summary>
+
+```bash
+git clone https://github.com/roy-jiang-opus/cctrans.git
+cd cctrans
+node bin/cctrans.js install
+```
+
+Requires `~/.local/bin` on your PATH, or use an alias: `alias cctrans='node /path/to/cctrans/bin/cctrans.js'`
+
+</details>
 
-## Why
+## 🤔 Why
 
 Two problems, one architecture:
 
@@ -33,7 +75,7 @@ Anthropic's tracking issue for language-adjusted limits ([#26401](https://github
 
 Full research notes with sources: [MOTIVATION.md](MOTIVATION.md).
 
-## How it works
+## ⚙️ How it works
 
 Built on Claude Code's native **`MessageDisplay` hook** (v2.1.152+): it fires while each assistant message renders, handing the hook each completed text chunk (`delta`); the `displayContent` the hook returns **replaces the on-screen rendering only**, never the stored message.
 
@@ -50,23 +92,7 @@ Claude streams English
 
 > Verified on CC 2.1.169: deltas are **non-overlapping** completed chunks (not accumulated text), a plain `\n` renders the two languages on separate lines, and code blocks / paths / already-translated lines are skipped automatically.
 
-## Install
-
-```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      # registers the hooks, links cctrans into ~/.local/bin, then runs the setup wizard
-```
-
-Then **restart Claude Code** (new session) so the hook loads. Send any message — replies become bilingual.
-
-> Requires `~/.local/bin` on your PATH; otherwise use an alias:
-> `alias cctrans='node /path/to/cctrans/bin/cctrans.js'`
-
-## Usage
+## 🎛 Commands
 
 | Command | What it does |
 |---------|--------------|
@@ -77,14 +103,13 @@ Then **restart Claude Code** (new session) so the hook loads. Send any message
 | `cctrans backends` | list engines and their availability |
 | `cctrans setup` | interactive wizard: language, backend, API keys |
 | `cctrans key [id] [value]` | manage API keys in `~/.cc-translate/keys.json` |
-| `cctrans input on` / `cctrans input off` | translate non-English input to English (sent as context) |
+| `cctrans input on` / `cctrans input off` | **(beta)** translate non-English input to English (sent as context) |
+| `cctrans input threshold <n>` | non-Latin characters that trigger input translation (default 4) |
 | `cctrans last [N]` | translate the latest (or N-back) reply to the terminal |
 | `cctrans test <text>` | translate ad-hoc text to verify the engine |
-| `cctrans install` / `cctrans uninstall` | register / remove the hook |
+| `cctrans install` / `cctrans uninstall` | register / remove the hooks |
 
-**Fastest toggle**: type `!cctrans off` or `!cctrans on` inside Claude Code's input box (`!` is CC's built-in bash mode — no model call, no tokens).
-
-## Translation backends
+## 🌐 Translation backends
 
 | Backend | Requires | Speed | Quality | Notes |
 |---------|----------|-------|---------|-------|
@@ -101,7 +126,7 @@ API keys live **only** in `~/.cc-translate/keys.json` (chmod 600) — set them w
 
 All other settings (backend, language, marker, models, Azure endpoint) live in `~/.cc-translate/state.json` — change them via `cctrans` commands or edit the file directly.
 
-## Languages
+## 🗣 Languages
 
 Target languages cover **CJK + Russian + Hindi** (non-Latin scripts, so "this line is already in the target language" can be detected for free via Unicode ranges and skipped):
 
@@ -116,19 +141,27 @@ cctrans lang zh-Hans  # Simplified Chinese (default)
 
 Chinese uses BCP-47 **script** codes (`zh-Hans`/`zh-Hant`) — Traditional Chinese is a script, not a region; `zh-CN` / `zh-TW` are accepted as aliases and normalized. Switching takes effect immediately (the hook re-reads state on every call); each language has its own cache.
 
-## Input translation
+## ⌨️ Input translation (beta)
+
+`cctrans input on` enables a `UserPromptSubmit` hook: when your prompt contains enough non-Latin text (default 4+ characters — an absolute count, so file paths and identifiers never dilute the trigger; tune with `cctrans input threshold <n>`), an English translation is attached as context the model treats as the canonical instruction, and the model is asked to **reply in English** — so the bilingual overlay keeps working and your conversation context stays English end-to-end. (Verified on CC 2.1.169: hooks cannot rewrite the prompt itself, so the original stays in history with the English alongside.) English prompts pass through untouched; any error falls back to sending your prompt as-is.
 
-`cctrans input on` enables a `UserPromptSubmit` hook: when your prompt is mostly non-English, an English translation is attached as context the model treats as the canonical instruction — you keep typing in your language, the model works in English. (Verified on CC 2.1.169: hooks cannot rewrite the prompt itself, so the original stays in history with the English alongside.) English prompts pass through untouched; any error falls back to sending your prompt as-is.
+> **Beta**: the translation call blocks prompt submission for ~0.5–1.5 s per non-English prompt. Off by default; the setup wizard asks once. Feedback → [issues](https://github.com/roy-jiang-opus/cctrans/issues).
 
-## Behavior & limits (verified)
+## 📏 Behavior & limits (verified)
 
 - The hook fires **per chunk during streaming**; each chunk is translated and replaced in place — translations appear progressively alongside the English.
 - The hook has a **10-second** timeout; this tool guards at 9s internally. Any error / timeout / oversized chunk (>9,000 chars) **falls back safely to the original English** — it never stalls the session.
 - Every translated line is **cached** by content hash (`~/.cc-translate/cache`); repaints and repeated text cost nothing.
 - With `openai`, each chunk is roughly one API call (~$0.0001) and adds about 1s of latency vs. plain English; `google` is faster with slightly lower quality.
 
-## Uninstall
+## 🔗 Stay in the loop
 
-```bash
-node bin/cctrans.js uninstall    # removes the hook; restart Claude Code to take effect
-```
+- ⭐ **Star / Watch** [github.com/roy-jiang-opus/cctrans](https://github.com/roy-jiang-opus/cctrans) to get release updates
+- 📦 **npm** — [npmjs.com/package/cctrans](https://www.npmjs.com/package/cctrans) · upgrade with `npm update -g cctrans`
+- 🗺 **Roadmap** — [ROADMAP.md](ROADMAP.md): what's shipped, what's next
+- 📚 **Research** — [MOTIVATION.md](MOTIVATION.md): the non-English token-tax data behind this project
+- 🐛 **Issues / language requests** — [github.com/roy-jiang-opus/cctrans/issues](https://github.com/roy-jiang-opus/cctrans/issues)
+
+## 📄 License
+
+[MIT](LICENSE) © Roy Jiang

package/README.ru.md

@@ -1,8 +1,20 @@
+<div align="center">
+
 # cctrans
 
+**Читайте Claude Code на родном языке — платите за токены по-английски.**
+
+[![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.zh-Hant.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | **Русский** | [हिन्दी](README.hi.md)
 
-**Двуязычный оверлей** для Claude Code: в каждом ответе под каждой строкой оригинального английского текста появляется строка перевода (китайский / японский / корейский / русский / хинди) — **прямо в диалоге**.
+</div>
+
+---
 
 ```
 ● I will refactor the auth module to use async tokens.
@@ -11,11 +23,41 @@
   ↳ Это затрагивает 3 файла и добавляет слой повторных попыток.
 ```
 
-- **Неразрушающий**: перевод появляется только на экране — транскрипт и контекст модели **остаются чисто английскими**, так что skills, документация и код не затрагиваются.
-- **Не загрязняет историю, не тратит токены основного цикла**: перевод выполняется через **отдельный дешёвый бэкенд**, полностью вне вашей сессии Claude Code.
-- **Переключение одной командой**: включён по умолчанию; мгновенно выключается, когда нужен чистый английский.
+**Двуязычный оверлей** для Claude Code: строка перевода (китайский / японский / корейский / русский / хинди) под каждой английской строкой, **прямо в диалоге** — только для отображения, поэтому транскрипт, контекст модели и ваш счёт за токены остаются на 100% английскими.
+
+## ✨ Возможности
+
+- 🪞 **Встроенное двуязычное отображение** — перевод появляется под каждой английской строкой по мере стриминга ответа
+- 🧾 **Неразрушающий** — транскрипт и контекст модели остаются чисто английскими; skills, документация и код не затронуты
+- 🆓 **Ноль токенов основного цикла** — перевод идёт через отдельный дешёвый (или бесплатный) бэкенд, полностью вне сессии Claude Code
+- ⌨️ **Перевод ввода (beta)** — печатайте на родном языке, модель работает — и отвечает — на английском (`cctrans input on`)
+- 🌏 **6 целевых языков** — `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi`
+- 🔌 **6 бэкендов с автооткатом** — OpenAI / Anthropic / DeepL / Azure / бесплатный Google / ваша подписка Claude
+- 🔒 **Изоляция ключей** — API-ключи только в файле chmod-600; переменные окружения никогда не читаются
+- 🛟 **Отказоустойчивость** — любая ошибка или таймаут откатывается к чистому английскому; сессия никогда не блокируется
+
+## 🚀 Быстрый старт
+
+```bash
+npm install -g cctrans && cctrans install
+```
+
+Установка регистрирует хуки и проводит через настройку (язык → бэкенд → API-ключ → живая проверка). Затем **перезапустите Claude Code** — ответы станут двуязычными. Переключайте в любой момент, набрав `!cctrans off` / `!cctrans on` в поле ввода Claude Code (`!` — встроенный bash-режим CC: без вызова модели, без токенов).
+
+<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 @@ Issue Anthropic о лимитах с поправкой на язык ([#26401](
 
 Полные заметки исследования с источниками: [MOTIVATION.md](MOTIVATION.md).
 
-## Как это работает
+## ⚙️ Как это работает
 
 Использует нативный хук **`MessageDisplay`** Claude Code (v2.1.152+): он срабатывает при рендеринге каждого сообщения ассистента, передавая хуку завершённый фрагмент текста (`delta`); возвращаемый хуком `displayContent` **заменяет только отображение на экране**, не меняя сохранённое сообщение.
 
@@ -51,23 +93,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/cctrans.git
-cd cctrans
-node bin/cctrans.js install      # регистрирует хуки, линкует cctrans в ~/.local/bin, затем запускает мастер настройки
-```
-
-Затем **перезапустите Claude Code** (новая сессия), чтобы хук загрузился. Отправьте любое сообщение — ответы станут двуязычными.
-
-> Требуется `~/.local/bin` в PATH; иначе используйте алиас:
-> `alias cctrans='node /path/to/cctrans/bin/cctrans.js'`
-
-## Использование
+## 🎛 Команды
 
 | Команда | Действие |
 |---------|----------|
@@ -78,14 +104,13 @@ node bin/cctrans.js install      # регистрирует хуки, линку
 | `cctrans backends` | список движков и их доступность |
 | `cctrans setup` | интерактивный мастер: язык, бэкенд, API-ключи |
 | `cctrans key [id] [value]` | управление ключами в `~/.cc-translate/keys.json` |
-| `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` | зарегистрировать / удалить хук |
+| `cctrans install` / `cctrans uninstall` | зарегистрировать / удалить хуки |
 
-**Самый быстрый способ переключения**: набрать `!cctrans off` или `!cctrans on` прямо в поле ввода Claude Code (`!` — встроенный bash-режим CC: без вызова модели, без токенов).
-
-## Бэкенды перевода
+## 🌐 Бэкенды перевода
 
 | Бэкенд | Требует | Скорость | Качество | Примечание |
 |--------|---------|----------|----------|------------|
@@ -102,7 +127,7 @@ API-ключи хранятся **только** в `~/.cc-translate/keys.json`
 
 Остальные настройки (бэкенд, язык, маркер, модели, эндпоинт Azure) находятся в `~/.cc-translate/state.json` — меняйте их командами `cctrans` или правьте файл напрямую.
 
-## Языки
+## 🗣 Языки
 
 Целевые языки — **CJK + русский + хинди** (нелатинские письменности, поэтому «строка уже на целевом языке» определяется бесплатно по диапазонам Unicode и пропускается):
 
@@ -117,19 +142,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>`), английский перевод прикрепляется как контекст, который модель считает каноничной инструкцией, и модель просят **отвечать на английском** — так двуязычный оверлей продолжает работать, а контекст разговора остаётся английским от начала до конца. (Проверено на CC 2.1.169: хуки не могут переписать сам промпт, поэтому оригинал остаётся в истории рядом с английским.) Английский ввод проходит без изменений; при любой ошибке промпт безопасно отправляется как есть.
 
-`cctrans input on` включает хук `UserPromptSubmit`: когда ваш промпт в основном не на английском, английский перевод прикрепляется как контекст, который модель считает каноничной инструкцией — вы продолжаете печатать на родном языке, модель работает на английском. (Проверено на CC 2.1.169: хуки не могут переписать сам промпт, поэтому оригинал остаётся в истории рядом с английским.) Английский ввод проходит без изменений; при любой ошибке промпт безопасно отправляется как есть.
+> **Beta**: вызов перевода блокирует отправку каждого неанглийского промпта на ~0.5–1.5 с. По умолчанию выключено; мастер настройки спросит один раз. Отзывы → [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): данные о неанглийском «токенном налоге», лёгшие в основу проекта
+- 🐛 **Issues / запросы языков** — [github.com/roy-jiang-opus/cctrans/issues](https://github.com/roy-jiang-opus/cctrans/issues)
+
+## 📄 Лицензия
+
+[MIT](LICENSE) © Roy Jiang

package/README.zh-Hans.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-Hant.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/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'`
-
-## 使用
+## 🎛 命令
 
 | 命令 | 作用 |
 |------|------|
@@ -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