cctrans 0.1.0 → 0.2.0

package/README.md

@@ -15,6 +15,24 @@ A **bilingual overlay** for Claude Code: every reply gets a translated line (Chi
 - **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.
 
+## Why
+
+Two problems, one architecture:
+
+**1. Claude Code keeps replying in English.** Skills and docs must stay English, and even with a "reply in my language" rule in CLAUDE.md, replies drift back to English. Re-asking for a translation costs a full model turn and pollutes the conversation history.
+
+**2. Working in your language has a hidden token tax — on Claude specifically.** Expressing the same meaning costs **~1.5–3× more tokens** than English (Claude's tokenizer compresses non-Latin scripts poorly), and Claude Code's 5-hour window and weekly caps are measured in tokens — so non-English sessions burn your plan 1.5–3× faster. Crucially, **answer quality is not the problem**: Claude scores >90% on multilingual benchmarks. The pain is purely cost.
+
+| | ja | ko | ru | hi | zh |
+|---|---|---|---|---|---|
+| Token cost vs English | ~2–3× | ~2–3×+ | ~1.5× | ~2–3×+ | ~2–3× |
+
+Anthropic's tracking issue for language-adjusted limits ([#26401](https://github.com/anthropics/claude-code/issues/26401)) was closed *not planned* — there is no first-party remedy.
+
+**So the cheapest correct design is exactly what this tool does:** the session stays English end-to-end (prompts, transcript, model context — zero extra main-loop tokens), and your language exists only where the human needs it: a display-only translated line under each English line, rendered by a separate cheap backend.
+
+Full research notes with sources: [MOTIVATION.md](MOTIVATION.md).
+
 ## 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.
@@ -35,72 +53,72 @@ Claude streams English
 ## Install
 
 ```bash
-npm install -g cctrans && tt install
+npm install -g cctrans && cctrans install
 
 # from source:
 git clone https://github.com/roy-jiang-opus/cctranslate.git
 cd cctranslate
-node bin/tt.js install      # registers the hooks, links tt into ~/.local/bin, then runs the setup wizard
+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 tt='node /path/to/cctranslate/bin/tt.js'`
+> `alias cctrans='node /path/to/cctranslate/bin/cctrans.js'`
 
 ## Usage
 
 | Command | What it does |
 |---------|--------------|
-| `tt on` / `tt off` / `tt toggle` | turn translation on / off / toggle |
-| `tt status` | show state (toggle, hook, backend, language) |
-| `tt lang [code]` | show/set target language: `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
-| `tt backend <id>` | switch translation engine |
-| `tt backends` | list engines and their availability |
-| `tt setup` | interactive wizard: language, backend, API keys |
-| `tt key [id] [value]` | manage API keys in `~/.cc-translate/keys.json` |
-| `tt input on` / `tt input off` | translate non-English input to English (sent as context) |
-| `tt last [N]` | translate the latest (or N-back) reply to the terminal |
-| `tt test <text>` | translate ad-hoc text to verify the engine |
-| `tt install` / `tt uninstall` | register / remove the hook |
-
-**Fastest toggle**: type `!tt off` or `!tt on` inside Claude Code's input box (`!` is CC's built-in bash mode — no model call, no tokens).
+| `cctrans on` / `cctrans off` / `cctrans toggle` | turn translation on / off / toggle |
+| `cctrans status` | show state (toggle, hook, backend, language) |
+| `cctrans lang [code]` | show/set target language: `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans backend <id>` | switch translation engine |
+| `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 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 |
+
+**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
 
 | Backend | Requires | Speed | Quality | Notes |
 |---------|----------|-------|---------|-------|
-| `openai` (default when key present) | `tt key openai` | ~1.4s/chunk | high | `gpt-4o-mini` batched line translation, preserves code/paths |
-| `anthropic` | `tt key anthropic` | ~1s/chunk | high | `claude-haiku-4-5` + structured outputs, strict same-length line arrays (~$0.0005/chunk) |
-| `deepl` | `tt key deepl` (free tier: 500k chars/mo) | ~0.5s/chunk | high | best traditional MT; array API aligns lines natively |
-| `azure` | `tt key azure` (free: 2M chars/mo) | ~0.5s/chunk | mid-high | optionally `tt key azure-region` |
+| `openai` (default when key present) | `cctrans key openai` | ~1.4s/chunk | high | `gpt-4o-mini` batched line translation, preserves code/paths |
+| `anthropic` | `cctrans key anthropic` | ~1s/chunk | high | `claude-haiku-4-5` + structured outputs, strict same-length line arrays (~$0.0005/chunk) |
+| `deepl` | `cctrans key deepl` (free tier: 500k chars/mo) | ~0.5s/chunk | high | best traditional MT; array API aligns lines natively |
+| `azure` | `cctrans key azure` (free: 2M chars/mo) | ~0.5s/chunk | mid-high | optionally `cctrans key azure-region` |
 | `google` | nothing | ~0.3s/chunk | mid | free unofficial endpoint; **the fallback when everything else fails** |
 | `claude-code` | `claude` CLI logged in | ~3-6s/chunk | high | runs on your **Claude subscription** (`claude -p` headless) — zero extra cost but noticeably slower |
 
 If the primary backend fails or times out, the chain **falls back to google** — the session is never blocked. Every translated line is cached by backend + language + content hash.
 
-API keys live **only** in `~/.cc-translate/keys.json` (chmod 600) — set them with `tt setup` / `tt key`, or edit the file directly. Shell environment variables are never read, so this tool's keys and your terminal's keys can't contaminate each other.
+API keys live **only** in `~/.cc-translate/keys.json` (chmod 600) — set them with `cctrans setup` / `cctrans key`, or edit the file directly. Shell environment variables are never read, so this tool's keys and your terminal's keys can't contaminate each other.
 
-All other settings (backend, language, marker, models, Azure endpoint) live in `~/.cc-translate/state.json` — change them via `tt` commands or edit the file directly.
+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
 
 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):
 
 ```bash
-tt lang ja       # Japanese
-tt lang ko       # Korean
-tt lang ru       # Russian
-tt lang hi       # Hindi
-tt lang zh-Hant  # Traditional Chinese
-tt lang zh-Hans  # Simplified Chinese (default)
+cctrans lang ja       # Japanese
+cctrans lang ko       # Korean
+cctrans lang ru       # Russian
+cctrans lang hi       # Hindi
+cctrans lang zh-Hant  # Traditional Chinese
+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
 
-`tt 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.
+`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.
 
 ## Behavior & limits (verified)
 
@@ -112,5 +130,5 @@ Chinese uses BCP-47 **script** codes (`zh-Hans`/`zh-Hant`) — Traditional Chine
 ## Uninstall
 
 ```bash
-node bin/tt.js uninstall    # removes the hook; restart Claude Code to take effect
+node bin/cctrans.js uninstall    # removes the hook; restart Claude Code to take effect
 ```

package/README.ru.md

@@ -15,6 +15,24 @@
 - **Не загрязняет историю, не тратит токены основного цикла**: перевод выполняется через **отдельный дешёвый бэкенд**, полностью вне вашей сессии Claude Code.
 - **Переключение одной командой**: включён по умолчанию; мгновенно выключается, когда нужен чистый английский.
 
+## Зачем это нужно
+
+Две проблемы, одна архитектура:
+
+**1. Claude Code упорно отвечает по-английски.** Skills и документация должны оставаться английскими, и даже с правилом «отвечай по-русски» в CLAUDE.md ответы сползают обратно в английский. Просить перевод заново — это целый ход модели и замусоренная история диалога.
+
+**2. Работа на родном языке несёт скрытый «токенный налог» — именно на Claude.** Одно и то же значение стоит **в ~1.5–3 раза больше токенов**, чем по-английски (токенизатор Claude плохо сжимает нелатинские письменности), а 5-часовое окно и недельные лимиты Claude Code измеряются в токенах — неанглийские сессии сжигают тариф в 1.5–3 раза быстрее. Главное: **качество ответов — не проблема**: Claude набирает >90% в мультиязычных бенчмарках. Боль — чисто в стоимости.
+
+| | японский | корейский | русский | хинди | китайский |
+|---|---|---|---|---|---|
+| Стоимость токенов vs английский | ~2–3× | ~2–3×+ | ~1.5× | ~2–3×+ | ~2–3× |
+
+Issue Anthropic о лимитах с поправкой на язык ([#26401](https://github.com/anthropics/claude-code/issues/26401)) закрыт как *not planned* — официального решения нет.
+
+**Поэтому самый дешёвый и правильный дизайн — ровно то, что делает этот инструмент:** сессия остаётся английской от начала до конца (промпты, транскрипт, контекст модели — ноль лишних токенов основного цикла), а ваш язык существует только там, где его читает человек: строка перевода только-для-отображения под каждой английской строкой, отрисованная отдельным дешёвым бэкендом.
+
+Полные заметки исследования с источниками: [MOTIVATION.md](MOTIVATION.md).
+
 ## Как это работает
 
 Использует нативный хук **`MessageDisplay`** Claude Code (v2.1.152+): он срабатывает при рендеринге каждого сообщения ассистента, передавая хуку завершённый фрагмент текста (`delta`); возвращаемый хуком `displayContent` **заменяет только отображение на экране**, не меняя сохранённое сообщение.
@@ -36,72 +54,72 @@ Claude стримит английский текст
 ## Установка
 
 ```bash
-npm install -g cctrans && tt install
+npm install -g cctrans && cctrans install
 
 # from source:
 git clone https://github.com/roy-jiang-opus/cctranslate.git
 cd cctranslate
-node bin/tt.js install      # регистрирует хуки, линкует tt в ~/.local/bin, затем запускает мастер настройки
+node bin/cctrans.js install      # регистрирует хуки, линкует cctrans в ~/.local/bin, затем запускает мастер настройки
 ```
 
 Затем **перезапустите Claude Code** (новая сессия), чтобы хук загрузился. Отправьте любое сообщение — ответы станут двуязычными.
 
 > Требуется `~/.local/bin` в PATH; иначе используйте алиас:
-> `alias tt='node /path/to/cctranslate/bin/tt.js'`
+> `alias cctrans='node /path/to/cctranslate/bin/cctrans.js'`
 
 ## Использование
 
 | Команда | Действие |
 |---------|----------|
-| `tt on` / `tt off` / `tt toggle` | включить / выключить / переключить перевод |
-| `tt status` | показать состояние (переключатель, хук, бэкенд, язык) |
-| `tt lang [code]` | показать/задать целевой язык: `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
-| `tt backend <id>` | сменить движок перевода |
-| `tt backends` | список движков и их доступность |
-| `tt setup` | интерактивный мастер: язык, бэкенд, API-ключи |
-| `tt key [id] [value]` | управление ключами в `~/.cc-translate/keys.json` |
-| `tt input on` / `tt input off` | переводить неанглийский ввод на английский (отправляется как контекст) |
-| `tt last [N]` | перевести последний (или N-й с конца) ответ в терминал |
-| `tt test <текст>` | перевести произвольный текст для проверки движка |
-| `tt install` / `tt uninstall` | зарегистрировать / удалить хук |
-
-**Самый быстрый способ переключения**: набрать `!tt off` или `!tt on` прямо в поле ввода Claude Code (`!` — встроенный bash-режим CC: без вызова модели, без токенов).
+| `cctrans on` / `cctrans off` / `cctrans toggle` | включить / выключить / переключить перевод |
+| `cctrans status` | показать состояние (переключатель, хук, бэкенд, язык) |
+| `cctrans lang [code]` | показать/задать целевой язык: `zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans backend <id>` | сменить движок перевода |
+| `cctrans backends` | список движков и их доступность |
+| `cctrans setup` | интерактивный мастер: язык, бэкенд, API-ключи |
+| `cctrans key [id] [value]` | управление ключами в `~/.cc-translate/keys.json` |
+| `cctrans input on` / `cctrans input off` | переводить неанглийский ввод на английский (отправляется как контекст) |
+| `cctrans last [N]` | перевести последний (или N-й с конца) ответ в терминал |
+| `cctrans test <текст>` | перевести произвольный текст для проверки движка |
+| `cctrans install` / `cctrans uninstall` | зарегистрировать / удалить хук |
+
+**Самый быстрый способ переключения**: набрать `!cctrans off` или `!cctrans on` прямо в поле ввода Claude Code (`!` — встроенный bash-режим CC: без вызова модели, без токенов).
 
 ## Бэкенды перевода
 
 | Бэкенд | Требует | Скорость | Качество | Примечание |
 |--------|---------|----------|----------|------------|
-| `openai` (по умолчанию при наличии ключа) | `tt key openai` | ~1.4с/фрагмент | высокое | `gpt-4o-mini`, пакетный перевод строк, сохраняет код/пути |
-| `anthropic` | `tt key anthropic` | ~1с/фрагмент | высокое | `claude-haiku-4-5` + structured outputs, строгие массивы строк равной длины (~$0.0005/фрагмент) |
-| `deepl` | `tt key deepl` (бесплатно: 500 тыс. симв./мес) | ~0.5с/фрагмент | высокое | лучший классический MT; массивный API нативно выравнивает строки |
-| `azure` | `tt key azure` (бесплатно: 2 млн симв./мес) | ~0.5с/фрагмент | среднее+ | опционально `tt key azure-region` |
+| `openai` (по умолчанию при наличии ключа) | `cctrans key openai` | ~1.4с/фрагмент | высокое | `gpt-4o-mini`, пакетный перевод строк, сохраняет код/пути |
+| `anthropic` | `cctrans key anthropic` | ~1с/фрагмент | высокое | `claude-haiku-4-5` + structured outputs, строгие массивы строк равной длины (~$0.0005/фрагмент) |
+| `deepl` | `cctrans key deepl` (бесплатно: 500 тыс. симв./мес) | ~0.5с/фрагмент | высокое | лучший классический MT; массивный API нативно выравнивает строки |
+| `azure` | `cctrans key azure` (бесплатно: 2 млн симв./мес) | ~0.5с/фрагмент | среднее+ | опционально `cctrans key azure-region` |
 | `google` | ничего | ~0.3с/фрагмент | среднее | бесплатный неофициальный эндпоинт; **резерв при отказе остальных** |
 | `claude-code` | выполнен вход в `claude` CLI | ~3-6с/фрагмент | высокое | работает на вашей **подписке Claude** (`claude -p` headless) — без доплат, но заметно медленнее |
 
 При сбое/таймауте основного бэкенда цепочка **автоматически откатывается на google** — сессия никогда не блокируется. Каждая переведённая строка кэшируется по хэшу «бэкенд + язык + содержимое».
 
-API-ключи хранятся **только** в `~/.cc-translate/keys.json` (chmod 600) — задавайте их через `tt setup` / `tt key` или редактируйте файл напрямую. Переменные окружения оболочки никогда не читаются, поэтому ключи инструмента и ключи терминала не загрязняют друг друга.
+API-ключи хранятся **только** в `~/.cc-translate/keys.json` (chmod 600) — задавайте их через `cctrans setup` / `cctrans key` или редактируйте файл напрямую. Переменные окружения оболочки никогда не читаются, поэтому ключи инструмента и ключи терминала не загрязняют друг друга.
 
-Остальные настройки (бэкенд, язык, маркер, модели, эндпоинт Azure) находятся в `~/.cc-translate/state.json` — меняйте их командами `tt` или правьте файл напрямую.
+Остальные настройки (бэкенд, язык, маркер, модели, эндпоинт Azure) находятся в `~/.cc-translate/state.json` — меняйте их командами `cctrans` или правьте файл напрямую.
 
 ## Языки
 
 Целевые языки — **CJK + русский + хинди** (нелатинские письменности, поэтому «строка уже на целевом языке» определяется бесплатно по диапазонам Unicode и пропускается):
 
 ```bash
-tt lang ja       # японский
-tt lang ko       # корейский
-tt lang ru       # русский
-tt lang hi       # хинди
-tt lang zh-Hant  # традиционный китайский
-tt lang zh-Hans  # упрощённый китайский (по умолчанию)
+cctrans lang ja       # японский
+cctrans lang ko       # корейский
+cctrans lang ru       # русский
+cctrans lang hi       # хинди
+cctrans lang zh-Hant  # традиционный китайский
+cctrans lang zh-Hans  # упрощённый китайский (по умолчанию)
 ```
 
 Для китайского используются **коды письменности** BCP-47 (`zh-Hans`/`zh-Hant`) — традиционный китайский это письменность, а не регион; `zh-CN` / `zh-TW` принимаются как алиасы и нормализуются автоматически. Смена языка применяется мгновенно (хук перечитывает состояние при каждом вызове); кэши языков независимы.
 
 ## Перевод ввода
 
-`tt input on` включает хук `UserPromptSubmit`: когда ваш промпт в основном не на английском, английский перевод прикрепляется как контекст, который модель считает каноничной инструкцией — вы продолжаете печатать на родном языке, модель работает на английском. (Проверено на CC 2.1.169: хуки не могут переписать сам промпт, поэтому оригинал остаётся в истории рядом с английским.) Английский ввод проходит без изменений; при любой ошибке промпт безопасно отправляется как есть.
+`cctrans input on` включает хук `UserPromptSubmit`: когда ваш промпт в основном не на английском, английский перевод прикрепляется как контекст, который модель считает каноничной инструкцией — вы продолжаете печатать на родном языке, модель работает на английском. (Проверено на CC 2.1.169: хуки не могут переписать сам промпт, поэтому оригинал остаётся в истории рядом с английским.) Английский ввод проходит без изменений; при любой ошибке промпт безопасно отправляется как есть.
 
 ## Поведение и ограничения (проверено)
 
@@ -113,5 +131,5 @@ tt lang zh-Hans  # упрощённый китайский (по умолчан
 ## Удаление
 
 ```bash
-node bin/tt.js uninstall    # удаляет хук; вступает в силу после перезапуска Claude Code
+node bin/cctrans.js uninstall    # удаляет хук; вступает в силу после перезапуска Claude Code
 ```

package/README.zh-Hans.md

@@ -15,6 +15,24 @@
 - **不污染历史、不耗主对话 token**:翻译由一个**独立的便宜后端**完成,跟你的 Claude Code 会话完全无关。
 - **一个键开关**:默认常开;读纯英文/代码时一键关掉。
 
+## 为什么做这个
+
+两个痛点,一个架构解决:
+
+**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](https://github.com/anthropics/claude-code/issues/26401))已被关闭(*not planned*)——官方没有解法。
+
+**所以最省钱且正确的设计正是本工具的做法:** 会话全程保持英文(输入、转录、模型上下文——主对话零额外 token),你的语言只出现在人需要读的地方:每行英文下面一行仅作显示的译文,由独立的便宜后端渲染。
+
+完整调研数据与来源:[MOTIVATION.md](MOTIVATION.md)。
+
 ## 工作原理
 
 利用 Claude Code 原生的 **`MessageDisplay` 钩子**(v2.1.152+):它在每条助手消息渲染时触发,把完成的文本片段(`delta`)交给钩子;钩子返回的 `displayContent` **替换屏幕显示**,但不改变存储的消息。
@@ -35,72 +53,72 @@ Claude 流式输出英文
 ## 安装
 
 ```bash
-npm install -g cctrans && tt install
+npm install -g cctrans && cctrans install
 
 # from source:
 git clone https://github.com/roy-jiang-opus/cctranslate.git
 cd cctranslate
-node bin/tt.js install      # 注册钩子、链接 tt 到 ~/.local/bin,然后运行 setup 向导
+node bin/cctrans.js install      # 注册钩子、链接 cctrans 到 ~/.local/bin,然后运行 setup 向导
 ```
 
 然后**重启 Claude Code**(开新会话)让钩子生效。发任意消息,回复就会双语对照。
 
 > 需要 `~/.local/bin` 在 PATH 里;否则用别名:
-> `alias tt='node /path/to/cctranslate/bin/tt.js'`
+> `alias cctrans='node /path/to/cctranslate/bin/cctrans.js'`
 
 ## 使用
 
 | 命令 | 作用 |
 |------|------|
-| `tt on` / `tt off` / `tt toggle` | 开 / 关 / 切换翻译 |
-| `tt status` | 查看状态(开关、钩子、后端、语言) |
-| `tt lang [code]` | 查看/切换目标语言:`zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
-| `tt backend <id>` | 切换翻译引擎 |
-| `tt backends` | 列出所有引擎及其可用性 |
-| `tt setup` | 交互式向导:语言、后端、API key |
-| `tt key [id] [value]` | 管理 `~/.cc-translate/keys.json` 里的 API key |
-| `tt input on` / `tt input off` | 把非英文输入翻译成英文(作为上下文发给模型) |
-| `tt last [N]` | 把最近(或往前第 N 条)回复翻译到终端 |
-| `tt test <文本>` | 翻译一段文本,验证引擎 |
-| `tt install` / `tt uninstall` | 注册 / 移除钩子 |
-
-**最快的开关方式**:在 Claude Code 输入框里直接输入 `!tt off` 或 `!tt on`(`!` 是 CC 的内置 bash 模式,不调用模型、不花 token)。
+| `cctrans on` / `cctrans off` / `cctrans toggle` | 开 / 关 / 切换翻译 |
+| `cctrans status` | 查看状态(开关、钩子、后端、语言) |
+| `cctrans lang [code]` | 查看/切换目标语言:`zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans backend <id>` | 切换翻译引擎 |
+| `cctrans backends` | 列出所有引擎及其可用性 |
+| `cctrans setup` | 交互式向导:语言、后端、API key |
+| `cctrans key [id] [value]` | 管理 `~/.cc-translate/keys.json` 里的 API key |
+| `cctrans input on` / `cctrans input off` | 把非英文输入翻译成英文(作为上下文发给模型) |
+| `cctrans last [N]` | 把最近(或往前第 N 条)回复翻译到终端 |
+| `cctrans test <文本>` | 翻译一段文本,验证引擎 |
+| `cctrans install` / `cctrans uninstall` | 注册 / 移除钩子 |
+
+**最快的开关方式**:在 Claude Code 输入框里直接输入 `!cctrans off` 或 `!cctrans on`(`!` 是 CC 的内置 bash 模式,不调用模型、不花 token)。
 
 ## 翻译后端
 
 | 后端 | 前提 | 速度 | 质量 | 说明 |
 |------|------|------|------|------|
-| `openai`(有 key 时默认) | `tt key openai` | ~1.4s/段 | 高 | `gpt-4o-mini` 批量行翻译,保留代码/路径 |
-| `anthropic` | `tt key anthropic` | ~1s/段 | 高 | `claude-haiku-4-5` + structured outputs,严格等长行数组(约 $0.0005/段) |
-| `deepl` | `tt key deepl`(免费档 50 万字符/月) | ~0.5s/段 | 高 | 传统 MT 质量天花板;数组接口天然对齐行 |
-| `azure` | `tt key azure`(免费 200 万字符/月) | ~0.5s/段 | 中高 | 可加 `tt key azure-region` |
+| `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)——用 `tt setup` / `tt key` 设置,或直接编辑该文件。终端环境变量永远不会被读取,本工具的 key 和终端的 key 互不污染。
+API key **只**存放在 `~/.cc-translate/keys.json`(chmod 600)——用 `cctrans setup` / `cctrans key` 设置,或直接编辑该文件。终端环境变量永远不会被读取,本工具的 key 和终端的 key 互不污染。
 
-其余设置(后端、语言、标记、模型、Azure 端点)都在 `~/.cc-translate/state.json` 里——用 `tt` 命令修改或直接编辑文件。
+其余设置(后端、语言、标记、模型、Azure 端点)都在 `~/.cc-translate/state.json` 里——用 `cctrans` 命令修改或直接编辑文件。
 
 ## 多语言
 
 目标语言支持 **CJK + 俄语 + 印地语**(非拉丁文字,可按 Unicode 区间零成本判断"该行已是目标语言"并跳过):
 
 ```bash
-tt lang ja       # 日语
-tt lang ko       # 韩语
-tt lang ru       # 俄语
-tt lang hi       # 印地语
-tt lang zh-Hant  # 繁体中文
-tt lang zh-Hans  # 简体中文(默认)
+cctrans lang ja       # 日语
+cctrans lang ko       # 韩语
+cctrans lang ru       # 俄语
+cctrans lang hi       # 印地语
+cctrans lang zh-Hant  # 繁体中文
+cctrans lang zh-Hans  # 简体中文(默认)
 ```
 
 中文采用 BCP-47 **文字码**(`zh-Hans`/`zh-Hant`)——繁体是文字系统而非地区;`zh-CN` / `zh-TW` 仍可作为别名使用,会自动归一化。切换语言即刻生效(钩子每次调用都读状态),不同语言的缓存相互独立。
 
 ## 输入翻译
 
-`tt input on` 启用 `UserPromptSubmit` 钩子:当你的输入大部分是非英文时,英文译文会作为上下文附给模型并被视为权威指令——你继续用母语打字,模型按英文工作。(已在 CC 2.1.169 核实:钩子无法改写 prompt 本身,所以原文仍在历史里,英文随附。)英文输入原样通过;任何错误都安全回退为原样发送。
+`cctrans input on` 启用 `UserPromptSubmit` 钩子:当你的输入大部分是非英文时,英文译文会作为上下文附给模型并被视为权威指令——你继续用母语打字,模型按英文工作。(已在 CC 2.1.169 核实:钩子无法改写 prompt 本身,所以原文仍在历史里,英文随附。)英文输入原样通过;任何错误都安全回退为原样发送。
 
 ## 行为与限制(已核实)
 
@@ -112,5 +130,5 @@ tt lang zh-Hans  # 简体中文(默认)
 ## 卸载
 
 ```bash
-node bin/tt.js uninstall    # 移除钩子;重启 Claude Code 生效
+node bin/cctrans.js uninstall    # 移除钩子;重启 Claude Code 生效
 ```

package/README.zh-Hant.md

@@ -15,6 +15,24 @@
 - **不污染歷史、不耗主對話 token**:翻譯由一個**獨立的低成本後端**完成,與你的 Claude Code 工作階段完全無關。
 - **一鍵開關**:預設常開;想讀純英文/程式碼時一鍵關閉。
 
+## 為什麼做這個
+
+兩個痛點,一個架構解決:
+
+**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](https://github.com/anthropics/claude-code/issues/26401))已被關閉(*not planned*)——官方沒有解法。
+
+**所以最省錢且正確的設計正是本工具的做法:** 工作階段全程保持英文(輸入、轉錄、模型上下文——主對話零額外 token),你的語言只出現在人需要讀的地方:每行英文下方一行僅作顯示的譯文,由獨立的低成本後端渲染。
+
+完整調研資料與來源:[MOTIVATION.md](MOTIVATION.md)。
+
 ## 運作原理
 
 利用 Claude Code 原生的 **`MessageDisplay` 鉤子**(v2.1.152+):它在每則助理訊息渲染時觸發,把完成的文字片段(`delta`)交給鉤子;鉤子回傳的 `displayContent` **只替換螢幕顯示**,不改變儲存的訊息。
@@ -35,72 +53,72 @@ Claude 串流輸出英文
 ## 安裝
 
 ```bash
-npm install -g cctrans && tt install
+npm install -g cctrans && cctrans install
 
 # from source:
 git clone https://github.com/roy-jiang-opus/cctranslate.git
 cd cctranslate
-node bin/tt.js install      # 註冊鉤子、連結 tt 到 ~/.local/bin,然後執行 setup 精靈
+node bin/cctrans.js install      # 註冊鉤子、連結 cctrans 到 ~/.local/bin,然後執行 setup 精靈
 ```
 
 接著**重新啟動 Claude Code**(開新工作階段)讓鉤子生效。送出任意訊息,回覆就會雙語對照。
 
 > 需要 `~/.local/bin` 在 PATH 中;否則使用別名:
-> `alias tt='node /path/to/cctranslate/bin/tt.js'`
+> `alias cctrans='node /path/to/cctranslate/bin/cctrans.js'`
 
 ## 使用
 
 | 指令 | 作用 |
 |------|------|
-| `tt on` / `tt off` / `tt toggle` | 開 / 關 / 切換翻譯 |
-| `tt status` | 檢視狀態(開關、鉤子、後端、語言) |
-| `tt lang [code]` | 檢視/切換目標語言:`zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
-| `tt backend <id>` | 切換翻譯引擎 |
-| `tt backends` | 列出所有引擎及其可用性 |
-| `tt setup` | 互動式精靈:語言、後端、API key |
-| `tt key [id] [value]` | 管理 `~/.cc-translate/keys.json` 中的 API key |
-| `tt input on` / `tt input off` | 把非英文輸入翻譯成英文(作為上下文傳給模型) |
-| `tt last [N]` | 把最近(或往前第 N 則)回覆翻譯到終端機 |
-| `tt test <文字>` | 翻譯一段文字,驗證引擎 |
-| `tt install` / `tt uninstall` | 註冊 / 移除鉤子 |
-
-**最快的開關方式**:在 Claude Code 輸入框直接輸入 `!tt off` 或 `!tt on`(`!` 是 CC 內建的 bash 模式,不呼叫模型、不花 token)。
+| `cctrans on` / `cctrans off` / `cctrans toggle` | 開 / 關 / 切換翻譯 |
+| `cctrans status` | 檢視狀態(開關、鉤子、後端、語言) |
+| `cctrans lang [code]` | 檢視/切換目標語言:`zh-Hans` `zh-Hant` `ja` `ko` `ru` `hi` |
+| `cctrans backend <id>` | 切換翻譯引擎 |
+| `cctrans backends` | 列出所有引擎及其可用性 |
+| `cctrans setup` | 互動式精靈:語言、後端、API key |
+| `cctrans key [id] [value]` | 管理 `~/.cc-translate/keys.json` 中的 API key |
+| `cctrans input on` / `cctrans input off` | 把非英文輸入翻譯成英文(作為上下文傳給模型) |
+| `cctrans last [N]` | 把最近(或往前第 N 則)回覆翻譯到終端機 |
+| `cctrans test <文字>` | 翻譯一段文字,驗證引擎 |
+| `cctrans install` / `cctrans uninstall` | 註冊 / 移除鉤子 |
+
+**最快的開關方式**:在 Claude Code 輸入框直接輸入 `!cctrans off` 或 `!cctrans on`(`!` 是 CC 內建的 bash 模式,不呼叫模型、不花 token)。
 
 ## 翻譯後端
 
 | 後端 | 前提 | 速度 | 品質 | 說明 |
 |------|------|------|------|------|
-| `openai`(有 key 時預設) | `tt key openai` | ~1.4s/段 | 高 | `gpt-4o-mini` 批次行翻譯,保留程式碼/路徑 |
-| `anthropic` | `tt key anthropic` | ~1s/段 | 高 | `claude-haiku-4-5` + structured outputs,嚴格等長行陣列(約 $0.0005/段) |
-| `deepl` | `tt key deepl`(免費額度 50 萬字元/月) | ~0.5s/段 | 高 | 傳統 MT 品質天花板;陣列介面天然對齊行 |
-| `azure` | `tt key azure`(免費 200 萬字元/月) | ~0.5s/段 | 中高 | 可加 `tt key azure-region` |
+| `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)——用 `tt setup` / `tt key` 設定,或直接編輯該檔案。終端機環境變數永遠不會被讀取,本工具的 key 與終端機的 key 互不污染。
+API key **只**存放在 `~/.cc-translate/keys.json`(chmod 600)——用 `cctrans setup` / `cctrans key` 設定,或直接編輯該檔案。終端機環境變數永遠不會被讀取,本工具的 key 與終端機的 key 互不污染。
 
-其餘設定(後端、語言、標記、模型、Azure 端點)都在 `~/.cc-translate/state.json` 中——用 `tt` 指令修改或直接編輯檔案。
+其餘設定(後端、語言、標記、模型、Azure 端點)都在 `~/.cc-translate/state.json` 中——用 `cctrans` 指令修改或直接編輯檔案。
 
 ## 多語言
 
 目標語言支援 **CJK + 俄語 + 印地語**(非拉丁文字,可按 Unicode 區間零成本判斷「該行已是目標語言」並跳過):
 
 ```bash
-tt lang ja       # 日語
-tt lang ko       # 韓語
-tt lang ru       # 俄語
-tt lang hi       # 印地語
-tt lang zh-Hant  # 繁體中文
-tt lang zh-Hans  # 簡體中文(預設)
+cctrans lang ja       # 日語
+cctrans lang ko       # 韓語
+cctrans lang ru       # 俄語
+cctrans lang hi       # 印地語
+cctrans lang zh-Hant  # 繁體中文
+cctrans lang zh-Hans  # 簡體中文(預設)
 ```
 
 中文採用 BCP-47 **文字碼**(`zh-Hans`/`zh-Hant`)——繁體是文字系統而非地區;`zh-CN` / `zh-TW` 仍可作為別名使用,會自動正規化。切換語言立即生效(鉤子每次呼叫都讀取狀態),不同語言的快取相互獨立。
 
 ## 輸入翻譯
 
-`tt input on` 啟用 `UserPromptSubmit` 鉤子:當你的輸入大多是非英文時,英文譯文會作為上下文附給模型並被視為權威指令——你繼續用母語打字,模型按英文工作。(已在 CC 2.1.169 核實:鉤子無法改寫 prompt 本身,所以原文仍在歷史中,英文隨附。)英文輸入原樣通過;任何錯誤都安全回退為原樣送出。
+`cctrans input on` 啟用 `UserPromptSubmit` 鉤子:當你的輸入大多是非英文時,英文譯文會作為上下文附給模型並被視為權威指令——你繼續用母語打字,模型按英文工作。(已在 CC 2.1.169 核實:鉤子無法改寫 prompt 本身,所以原文仍在歷史中,英文隨附。)英文輸入原樣通過;任何錯誤都安全回退為原樣送出。
 
 ## 行為與限制(已核實)
 
@@ -112,5 +130,5 @@ tt lang zh-Hans  # 簡體中文(預設)
 ## 解除安裝
 
 ```bash
-node bin/tt.js uninstall    # 移除鉤子;重新啟動 Claude Code 生效
+node bin/cctrans.js uninstall    # 移除鉤子;重新啟動 Claude Code 生效
 ```

package/ROADMAP.md

@@ -3,13 +3,13 @@
 ## Shipped
 
 ### ✅ Input translation — write in your language, send in English
-`tt 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`.
+`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
-`tt install` registers both hooks and launches the wizard; `tt 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 → backend selection → key entry for the chosen backend → live translation verification. Non-interactive flags: `--lang`, `--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 `tt 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: `TT_HOME` / `TT_TRANSCRIPT` (tests) and `TT_DISABLE` / `TT_DEBUG_STDIN` (hook internals).
+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).
 
 ## Planned