cctrans 0.1.0 → 0.2.1

package/MOTIVATION.md

@@ -0,0 +1,78 @@
+# Why this project exists — the non-English "token tax" in Claude Code
+
+> Research notes gathered as the founding rationale for `cctranslate` / terminal-translate.
+> Scope: **only the models Claude Code runs on (Claude / Anthropic)**, and the target
+> languages this tool supports: **Japanese, Korean, Russian, Hindi** (plus Chinese).
+> Date gathered: 2026-06-09.
+
+## The one-sentence reason
+
+On Claude Code, expressing the same meaning in a non-English language costs **1.5×–3× more
+tokens** than English, while the model's *answer quality* in those languages stays high.
+So the pain is **cost / usage-limit burn, not model competence** — and the fix is to let the
+user keep working in English under the hood while reading their own language on screen.
+That is exactly what this tool does (English stays in the transcript + model context; the
+translated line is display-only).
+
+## 1. Token cost — Claude's "language tax" by script
+
+Background: among major providers, **Anthropic (Claude) has the *highest* average non-English
+token tax**. Gemini (256k SentencePiece vocab) and Qwen are the most efficient; Claude uses its
+own BPE tokenizer that compresses non-Latin scripts poorly. English packs ~4 chars/token; CJK
+often falls back to ~1 token/char.
+
+| Language | Script | Tokens vs English (Claude) | Notes |
+|----------|--------|----------------------------|-------|
+| **Japanese** 🇯🇵 | Kanji + kana (CJK) | **~2–3×** (per equivalent content) | single chars often ~1 token; per-char ~4× worse than English |
+| **Korean** 🇰🇷 | Hangul (CJK, agglutinative) | **~2–3×, sometimes higher** | 3 bytes/char + agglutinative morphology → frequent char/byte-level fallback; the worst-hit CJK case |
+| **Russian** 🇷🇺 | Cyrillic | **~1.5×**; narrow-domain text up to **3–4.4 tokens/word** | better than CJK but still penalized; Claude is among the less efficient closed models for Cyrillic |
+| **Hindi** 🇮🇳 | Devanagari | **~2–3× and up** (penalty described as "positively comic") | low-resource + conjunct ligatures → byte-level fallback; potentially the most expensive of the four |
+| Chinese (zh) | Han (CJK) | ~2–3× | included for completeness; default target of this tool |
+
+Worked example (Korean, generalizes to the rest): `"Fix the bug in this file"` ≈ **6 tokens** in
+English vs **~14–18 tokens** in Korean — same outcome.
+
+### Why it matters specifically for Claude Code
+Claude Code's **5-hour window and weekly caps are measured in tokens**, so non-English users:
+- hit the weekly cap **~1.5–3× faster** (Japanese/Korean/Hindi worst, Russian mildest);
+- fill the **200K / 1M context window** faster;
+- pay a higher effective price for the same plan ("invisible language tax").
+
+Anthropic's own tracking issue proposing language-adjusted limits
+([claude-code #26401](https://github.com/anthropics/claude-code/issues/26401)) was closed
+**"not planned" / stale** — i.e. there is no first-party remedy, which is the gap this tool fills.
+
+## 2. Quality — this is *not* the problem
+
+Opposite of cost: Claude is consistently strong on multilingual benchmarks, so switching the
+*display* language costs nothing in answer quality (and note: quality/cost effects are
+model-dependent — don't assume prompting in another language is better or cheaper).
+
+- **MGSM** (multilingual math reasoning): Claude >90% in 8+ languages, **including Russian and Japanese**.
+- **Multilingual MMLU** (knowledge): **Russian** and others slightly above 80%.
+- **Opus >90% accuracy** languages explicitly include **Hindi, Japanese, Korean**.
+- Roughly: Japanese ~92%, Korean/Hindi ~88–90%+, Russian >80–90%.
+
+## 3. Four-language summary
+
+| Dimension | Japanese | Korean | Russian | Hindi |
+|-----------|----------|--------|---------|-------|
+| Token cost (lower = better) | High (2–3×) | **Highest** (2–3×+) | Medium (~1.5×) | **Highest / uncertain** (2–3×+) |
+| Model quality | Very strong (~92%) | Strong (~88–90%) | Strong (>80–90%) | Strong (>90% Opus) |
+| Net experience | Cost-dragged | Most penalized | Best value | Most penalized |
+
+**Design implication for this tool:** the cheapest correct UX is to keep the *session* in
+English (instructions, code, transcript, model context) and translate only what the human reads
+and writes — which is the non-destructive display-overlay + input-context-attach architecture
+already chosen. Russian users gain the least (mild tax), Japanese/Korean/Hindi users gain the most.
+
+## Sources
+
+- [Claude Code Issue #26401 — CJK tokenization disadvantage, closed "not planned"](https://github.com/anthropics/claude-code/issues/26401)
+- [The Hidden Token Tax on Not Speaking English to AI](https://abvx.substack.com/p/the-hidden-token-tax-on-not-speaking) — Anthropic highest non-English tax; Russian ~1.5×; Hindi penalty extreme
+- [Tokenizer Quirks: Claude / GPT / Gemini don't count text the same way](https://dev.to/gabrielanhaia/tokenizer-quirks-claude-gpt-and-gemini-dont-count-the-same-text-the-same-way-1522) — CJK ≈ 1 token/char
+- [Tokenization efficiency for Ukrainian / Cyrillic (Frontiers, 2025)](https://www.frontiersin.org/journals/artificial-intelligence/articles/10.3389/frai.2025.1538165/full) — Claude 3–4.4 tokens/word for Cyrillic
+- [The Mystery of the Claude 3 Tokenizer — Sander Land](https://tokencontributions.substack.com/p/the-mystery-of-the-claude-3-tokenizer) — Claude tokenizer internals, CJK input/output count quirks
+- [Claude 3 multilingual benchmarks — 96% across 12 languages](https://medium.com/@venugopal.adep/96-accuracy-in-12-languages-the-secret-behind-claude-3s-multilingual-mastery-699b0b2f84df)
+- [Multilingual support — Claude API Docs](https://platform.claude.com/docs/en/build-with-claude/multilingual-support)
+- [Mythbuster: Chinese is not more efficient than English in vibe coding (arXiv)](https://arxiv.org/html/2604.14210v1) — non-Claude models, but busts the "non-English prompts save tokens" myth

package/README.hi.md

@@ -1,4 +1,4 @@
-# cctranslate
+# cctrans
 
 [English](README.md) | [简体中文](README.zh-Hans.md) | [繁體中文](README.zh-Hant.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Русский](README.ru.md) | **हिन्दी**
 
@@ -15,6 +15,24 @@ Claude Code के लिए एक **द्विभाषी ओवरले**
 - **हिस्ट्री प्रदूषित नहीं होती, मुख्य लूप के टोकन खर्च नहीं होते**: अनुवाद एक **अलग सस्ते बैकएंड** से होता है, जो आपके Claude Code सत्र से पूरी तरह बाहर है।
 - **एक कुंजी से टॉगल**: डिफ़ॉल्ट रूप से चालू; शुद्ध अंग्रेज़ी/कोड पढ़ना हो तो तुरंत बंद करें।
 
+## यह प्रोजेक्ट क्यों
+
+दो समस्याएँ, एक आर्किटेक्चर:
+
+**1. Claude Code बार-बार अंग्रेज़ी में जवाब देता है।** Skills और दस्तावेज़ अंग्रेज़ी में ही रहने चाहिए, और CLAUDE.md में "हिन्दी में जवाब दो" लिखने पर भी जवाब अंग्रेज़ी में लौट आते हैं। दोबारा अनुवाद माँगना एक पूरा मॉडल टर्न खर्च करता है और बातचीत का इतिहास भी दूषित करता है।
+
+**2. अपनी भाषा में काम करने पर छिपा हुआ टोकन-कर लगता है — ख़ासकर Claude पर।** वही अर्थ व्यक्त करने में अंग्रेज़ी से **~1.5–3× ज़्यादा टोकन** लगते हैं (Claude का टोकनाइज़र गैर-लैटिन लिपियों को खराब संपीड़ित करता है), और Claude Code की 5-घंटे की विंडो और साप्ताहिक सीमाएँ टोकन में मापी जाती हैं — यानी गैर-अंग्रेज़ी सत्र आपका प्लान 1.5–3× तेज़ी से जलाते हैं। अहम बात: **जवाब की गुणवत्ता समस्या नहीं है**: Claude बहुभाषी बेंचमार्क में >90% स्कोर करता है। दर्द विशुद्ध रूप से लागत का है।
+
+| | जापानी | कोरियाई | रूसी | हिन्दी | चीनी |
+|---|---|---|---|---|---|
+| अंग्रेज़ी की तुलना में टोकन लागत | ~2–3× | ~2–3×+ | ~1.5× | ~2–3×+ | ~2–3× |
+
+भाषा-समायोजित सीमाओं के लिए Anthropic का issue ([#26401](https://github.com/anthropics/claude-code/issues/26401)) *not planned* कहकर बंद कर दिया गया — कोई आधिकारिक उपाय नहीं है।
+
+**इसलिए सबसे सस्ता और सही डिज़ाइन ठीक वही है जो यह टूल करता है:** सत्र शुरू से अंत तक अंग्रेज़ी में रहता है (प्रॉम्प्ट, ट्रांसक्रिप्ट, मॉडल कॉन्टेक्स्ट — मुख्य लूप का शून्य अतिरिक्त टोकन), और आपकी भाषा केवल वहीं मौजूद है जहाँ इंसान को पढ़ना है: हर अंग्रेज़ी पंक्ति के नीचे केवल-प्रदर्शन अनुवाद पंक्ति, जिसे एक अलग सस्ता बैकएंड रेंडर करता है।
+
+स्रोतों सहित पूर्ण शोध नोट्स: [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 विज़ार्ड चलाता है
+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 इस्तेमाल करें:
-> `alias tt='node /path/to/cctranslate/bin/tt.js'`
+> `alias cctrans='node /path/to/cctrans/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` में API कुंजियाँ प्रबंधित करें |
-| `tt input on` / `tt input off` | गैर-अंग्रेज़ी इनपुट का अंग्रेज़ी अनुवाद (संदर्भ के रूप में भेजा जाता है) |
-| `tt last [N]` | नवीनतम (या N पीछे का) जवाब टर्मिनल में अनुवाद करें |
-| `tt test <टेक्स्ट>` | इंजन जाँचने के लिए कोई टेक्स्ट अनुवाद करें |
-| `tt install` / `tt uninstall` | हुक पंजीकृत / हटाएँ |
-
-**सबसे तेज़ टॉगल**: Claude Code के इनपुट बॉक्स में सीधे `!tt off` या `!tt on` टाइप करें (`!` CC का बिल्ट-इन bash मोड है — कोई मॉडल कॉल नहीं, कोई टोकन नहीं)।
+| `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` में API कुंजियाँ प्रबंधित करें |
+| `cctrans input on` / `cctrans input off` | गैर-अंग्रेज़ी इनपुट का अंग्रेज़ी अनुवाद (संदर्भ के रूप में भेजा जाता है) |
+| `cctrans last [N]` | नवीनतम (या N पीछे का) जवाब टर्मिनल में अनुवाद करें |
+| `cctrans test <टेक्स्ट>` | इंजन जाँचने के लिए कोई टेक्स्ट अनुवाद करें |
+| `cctrans install` / `cctrans uninstall` | हुक पंजीकृत / हटाएँ |
+
+**सबसे तेज़ टॉगल**: Claude Code के इनपुट बॉक्स में सीधे `!cctrans off` या `!cctrans on` टाइप करें (`!` CC का बिल्ट-इन bash मोड है — कोई मॉडल कॉल नहीं, कोई टोकन नहीं)।
 
 ## अनुवाद बैकएंड
 
 | बैकएंड | आवश्यक | गति | गुणवत्ता | टिप्पणी |
 |--------|--------|-----|----------|---------|
-| `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` (मुफ़्त: 5 लाख वर्ण/माह) | ~0.5s/खंड | उच्च | सर्वश्रेष्ठ पारंपरिक MT; array API से पंक्तियाँ स्वतः संरेखित |
-| `azure` | `tt key azure` (मुफ़्त: 20 लाख वर्ण/माह) | ~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` (मुफ़्त: 5 लाख वर्ण/माह) | ~0.5s/खंड | उच्च | सर्वश्रेष्ठ पारंपरिक MT; array API से पंक्तियाँ स्वतः संरेखित |
+| `azure` | `cctrans key azure` (मुफ़्त: 20 लाख वर्ण/माह) | ~0.5s/खंड | मध्यम-उच्च | वैकल्पिक `cctrans key azure-region` |
 | `google` | कुछ नहीं | ~0.3s/खंड | मध्यम | मुफ़्त अनौपचारिक endpoint; **बाक़ी सब विफल होने पर fallback** |
 | `claude-code` | `claude` CLI लॉग-इन | ~3-6s/खंड | उच्च | आपकी **Claude सदस्यता** पर चलता है (`claude -p` headless) — कोई अतिरिक्त लागत नहीं पर धीमा |
 
 प्राथमिक बैकएंड विफल/टाइमआउट होने पर शृंखला **स्वतः google पर fallback** करती है — सत्र कभी अवरुद्ध नहीं होता। हर अनुवादित पंक्ति बैकएंड + भाषा + सामग्री हैश से कैश होती है।
 
-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 पर सत्यापित: हुक प्रॉम्प्ट को फिर से लिख नहीं सकते, इसलिए मूल इतिहास में रहता है और अंग्रेज़ी साथ में।) अंग्रेज़ी इनपुट अपरिवर्तित गुज़रता है; किसी त्रुटि पर प्रॉम्प्ट सुरक्षित रूप से ज्यों का त्यों भेजा जाता है।
 
 ## व्यवहार और सीमाएँ (सत्यापित)
 
@@ -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.ja.md

@@ -1,4 +1,4 @@
-# cctranslate
+# cctrans
 
 [English](README.md) | [简体中文](README.zh-Hans.md) | [繁體中文](README.zh-Hant.md) | **日本語** | [한국어](README.ko.md) | [Русский](README.ru.md) | [हिन्दी](README.hi.md)
 
@@ -15,6 +15,24 @@ Claude Code に**バイリンガル表示**を追加:すべての返信で、元
 - **履歴を汚さない・メインループのトークンを消費しない**:翻訳は**独立した低コストのバックエンド**で実行され、Claude Code セッションとは完全に無関係です。
 - **ワンキーでオン/オフ**:デフォルトは常時オン;英語/コードだけ読みたいときはすぐオフにできます。
 
+## なぜ作ったか
+
+2 つの課題を 1 つのアーキテクチャで解決します:
+
+**1. Claude Code は英語で返答しがち。** Skills とドキュメントは英語のままにする必要があり、CLAUDE.md に「日本語で返答」と書いても返答は英語に戻りがちです。「日本語で」と打ち直して再回答させると、モデル呼び出しを丸ごと 1 回消費し、会話履歴も汚れます。
+
+**2. 母語で作業すると隠れた「トークン税」がかかる——特に Claude では。** 同じ意味を表現するのに英語より **約 1.5–3 倍のトークン**がかかります(Claude のトークナイザは非ラテン文字の圧縮が苦手)。Claude Code の 5 時間ウィンドウと週次上限はトークンで計測されるため、非英語セッションはプランを 1.5–3 倍速く消費します。重要なのは、**回答品質は問題ではない**こと:Claude は多言語ベンチマークで 90% 超。痛みは純粋にコストです。
+
+| | 日本語 | 韓国語 | ロシア語 | ヒンディー語 | 中国語 |
+|---|---|---|---|---|---|
+| 英語比のトークンコスト | ~2–3× | ~2–3×+ | ~1.5× | ~2–3×+ | ~2–3× |
+
+言語別の上限調整を求める Anthropic の issue([#26401](https://github.com/anthropics/claude-code/issues/26401))は *not planned* でクローズ——公式の救済はありません。
+
+**だから最も安価で正しい設計は、まさにこのツールの方式:** セッションは端から端まで英語のまま(プロンプト、トランスクリプト、モデルコンテキスト——メインループの追加トークンはゼロ)、あなたの言語は人間が読む場所にだけ存在します:各英語行の下の表示専用の訳文行を、独立した安価なバックエンドが描画します。
+
+出典付きの完全な調査ノート:[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 ウィザードを実行
+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 tt='node /path/to/cctranslate/bin/tt.js'`
+> `alias cctrans='node /path/to/cctrans/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` の API キーを管理 |
-| `tt input on` / `tt input off` | 非英語の入力を英語に翻訳(コンテキストとして送信) |
-| `tt last [N]` | 最新(または N 個前)の返信をターミナルに翻訳 |
-| `tt test <テキスト>` | テキストを翻訳してエンジンを検証 |
-| `tt install` / `tt uninstall` | フックの登録 / 削除 |
-
-**最速のトグル**:Claude Code の入力欄に `!tt off` / `!tt on` と直接入力(`!` は CC 内蔵の bash モード——モデル呼び出しなし、トークン消費なし)。
+| `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` の API キーを管理 |
+| `cctrans input on` / `cctrans input off` | 非英語の入力を英語に翻訳(コンテキストとして送信) |
+| `cctrans last [N]` | 最新(または N 個前)の返信をターミナルに翻訳 |
+| `cctrans test <テキスト>` | テキストを翻訳してエンジンを検証 |
+| `cctrans install` / `cctrans uninstall` | フックの登録 / 削除 |
+
+**最速のトグル**:Claude Code の入力欄に `!cctrans off` / `!cctrans on` と直接入力(`!` は CC 内蔵の bash モード——モデル呼び出しなし、トークン消費なし)。
 
 ## 翻訳バックエンド
 
 | バックエンド | 前提 | 速度 | 品質 | 備考 |
 |--------------|------|------|------|------|
-| `openai`(キーがあればデフォルト) | `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 の最高品質;配列 API で行が自然に揃う |
-| `azure` | `tt key azure`(無料 200 万字/月) | ~0.5s/断片 | 中高 | `tt key azure-region` も指定可 |
+| `openai`(キーがあればデフォルト) | `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 の最高品質;配列 API で行が自然に揃う |
+| `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 キーは `~/.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 で検証済み:フックは 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.ko.md

@@ -1,4 +1,4 @@
-# cctranslate
+# cctrans
 
 [English](README.md) | [简体中文](README.zh-Hans.md) | [繁體中文](README.zh-Hant.md) | [日本語](README.ja.md) | **한국어** | [Русский](README.ru.md) | [हिन्दी](README.hi.md)
 
@@ -15,6 +15,24 @@ Claude Code에 **이중 언어 오버레이**를 추가합니다: 모든 응답
 - **히스토리 오염 없음, 메인 루프 토큰 소비 없음**: 번역은 **독립적인 저비용 백엔드**에서 실행되며 Claude Code 세션과 완전히 무관합니다.
 - **원키 토글**: 기본은 항상 켜짐; 영어/코드만 읽고 싶을 때 즉시 끌 수 있습니다.
 
+## 왜 만들었나
+
+두 가지 문제, 하나의 아키텍처:
+
+**1. Claude Code는 자꾸 영어로 답합니다.** Skills와 문서는 영어로 유지해야 하고, CLAUDE.md에 "한국어로 답해"라고 적어도 답변은 영어로 돌아가곤 합니다. "한국어로"라고 다시 요청하면 모델 호출 한 턴을 통째로 쓰고 대화 히스토리도 오염됩니다.
+
+**2. 모국어로 작업하면 숨은 토큰세가 붙습니다 — 특히 Claude에서.** 같은 의미를 표현하는 데 영어보다 **약 1.5–3배 많은 토큰**이 듭니다(Claude의 토크나이저는 비라틴 문자 압축이 약함). Claude Code의 5시간 윈도우와 주간 한도는 토큰으로 측정되므로 비영어 세션은 플랜을 1.5–3배 빨리 소진합니다. 중요한 건, **답변 품질은 문제가 아니라는 것**: Claude는 다국어 벤치마크에서 90% 이상. 고통은 순전히 비용입니다.
+
+| | 일본어 | 한국어 | 러시아어 | 힌디어 | 중국어 |
+|---|---|---|---|---|---|
+| 영어 대비 토큰 비용 | ~2–3× | ~2–3×+ | ~1.5× | ~2–3×+ | ~2–3× |
+
+언어별 한도 조정을 요청한 Anthropic의 issue([#26401](https://github.com/anthropics/claude-code/issues/26401))는 *not planned*로 닫혔습니다 — 공식 해결책은 없습니다.
+
+**그래서 가장 저렴하고 올바른 설계가 바로 이 도구의 방식입니다:** 세션은 처음부터 끝까지 영어로 유지되고(프롬프트, 트랜스크립트, 모델 컨텍스트 — 메인 루프 추가 토큰 0), 당신의 언어는 사람이 읽는 곳에만 존재합니다: 각 영어 줄 아래 표시 전용 번역 줄을 독립적인 저비용 백엔드가 렌더링합니다.
+
+출처가 포함된 전체 조사 노트: [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 마법사 실행
+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 tt='node /path/to/cctranslate/bin/tt.js'`
+> `alias cctrans='node /path/to/cctrans/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`의 API 키 관리 |
-| `tt input on` / `tt input off` | 비영어 입력을 영어로 번역 (컨텍스트로 전송) |
-| `tt last [N]` | 최신(또는 N개 전) 응답을 터미널에 번역 |
-| `tt test <텍스트>` | 텍스트를 번역하여 엔진 검증 |
-| `tt install` / `tt uninstall` | 훅 등록 / 제거 |
-
-**가장 빠른 토글**: Claude Code 입력창에 `!tt off` / `!tt on`을 직접 입력 (`!`는 CC 내장 bash 모드 — 모델 호출 없음, 토큰 소비 없음).
+| `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`의 API 키 관리 |
+| `cctrans input on` / `cctrans input off` | 비영어 입력을 영어로 번역 (컨텍스트로 전송) |
+| `cctrans last [N]` | 최신(또는 N개 전) 응답을 터미널에 번역 |
+| `cctrans test <텍스트>` | 텍스트를 번역하여 엔진 검증 |
+| `cctrans install` / `cctrans uninstall` | 훅 등록 / 제거 |
+
+**가장 빠른 토글**: Claude Code 입력창에 `!cctrans off` / `!cctrans on`을 직접 입력 (`!`는 CC 내장 bash 모드 — 모델 호출 없음, 토큰 소비 없음).
 
 ## 번역 백엔드
 
 | 백엔드 | 요구사항 | 속도 | 품질 | 비고 |
 |--------|----------|------|------|------|
-| `openai` (키 있으면 기본) | `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 최고 품질; 배열 API로 줄이 자연히 정렬 |
-| `azure` | `tt key azure` (무료 200만 자/월) | ~0.5s/조각 | 중상 | `tt key azure-region` 추가 가능 |
+| `openai` (키 있으면 기본) | `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 최고 품질; 배열 API로 줄이 자연히 정렬 |
+| `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 키는 **오직** `~/.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 + 러시아어 + 힌디어**를 지원합니다 (비라틴 문자이므로 유니코드 범위로 "이 줄은 이미 대상 언어"를 무비용 판별하여 건너뜁니다):
 
 ```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 재시작으로 반영
 ```