From 215d87766e919b58149f2edc7631b6b556bf4033 Mon Sep 17 00:00:00 2001
From: Microck <contact@micr.dev>
Date: Wed, 18 Mar 2026 18:19:50 +0000
Subject: [PATCH 1/7] feat(translate): add text-mode Kagi Translate support

Add a new kagi translate command that bootstraps translate.kagi.com from the existing session token, then calls detect, translate, alternatives, alignments, suggestions, and word insights over direct HTTP.

Document the new command, update auth and coverage references, and note the current runtime dependency on python3 plus curl_cffi for bootstrap.
---
 Cargo.lock                         |  21 +
 Cargo.toml                         |   2 +-
 README.md                          |  23 +-
 docs/api-coverage.md               |  10 +-
 docs/commands/translate.mdx        | 259 +++++++++
 docs/docs.json                     |   1 +
 docs/index.mdx                     |  10 +-
 docs/reference/auth-matrix.mdx     |   5 +
 docs/reference/coverage.mdx        |  21 +-
 docs/reference/error-reference.mdx |  15 +
 docs/reference/output-contract.mdx |  34 ++
 src/api.rs                         | 867 ++++++++++++++++++++++++++++-
 src/auth.rs                        |  64 ++-
 src/cli.rs                         |  97 ++++
 src/main.rs                        |  90 ++-
 src/types.rs                       | 177 ++++++
 16 files changed, 1632 insertions(+), 64 deletions(-)
 create mode 100644 docs/commands/translate.mdx

diff --git a/Cargo.lock b/Cargo.lock
index 62edc34..4eceeb6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -241,6 +241,16 @@ version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
 
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.52.0",
+]
+
 [[package]]
 name = "fastrand"
 version = "2.3.0"
@@ -1187,6 +1197,16 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
 [[package]]
 name = "siphasher"
 version = "1.0.2"
@@ -1354,6 +1374,7 @@ dependencies = [
  "libc",
  "mio",
  "pin-project-lite",
+ "signal-hook-registry",
  "socket2",
  "tokio-macros",
  "windows-sys 0.61.2",
diff --git a/Cargo.toml b/Cargo.toml
index 677d5a9..26ef15f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -30,5 +30,5 @@ scraper = "0.25.0"
 serde = { version = "1.0.219", features = ["derive"] }
 serde_json = "1.0.140"
 thiserror = "2.0.12"
-tokio = { version = "1.44.2", features = ["macros", "rt-multi-thread"] }
+tokio = { version = "1.44.2", features = ["macros", "process", "rt-multi-thread"] }
 toml = "1.0.6"
diff --git a/README.md b/README.md
index 712e700..243e1ac 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@
 
 ---
 
-`kagi` is a terminal CLI for Kagi that gives you command-line access to search, lenses, assistant, summarization, feeds, and paid API commands. it is built for people who want one command surface for interactive use, shell workflows, and structured JSON output.
+`kagi` is a terminal CLI for Kagi that gives you command-line access to search, lenses, assistant, translate, summarization, feeds, and paid API commands. it is built for people who want one command surface for interactive use, shell workflows, and structured JSON output.
 
 the main setup path is your existing Kagi session-link URL. paste it into `kagi auth set --session-token` and the CLI extracts the token for you. if you also use Kagi's paid API, add `KAGI_API_TOKEN` and the public API commands are available too.
 
@@ -29,7 +29,7 @@ if you already use Kagi and want to access it from scripts, shell workflows, or
 
 - use your existing session-link URL for subscriber features
 - get structured JSON for scripts, agents, and other tooling
-- use one CLI for search, assistant, summarization, and feeds
+- use one CLI for search, assistant, translate, summarization, and feeds
 - add `KAGI_API_TOKEN` only when you want the paid public API commands
 
 ## quickstart
@@ -101,7 +101,7 @@ export KAGI_API_TOKEN='...'
 
 | credential | what it unlocks |
 | --- | --- |
-| `KAGI_SESSION_TOKEN` | base search, `search --lens`, `assistant`, `summarize --subscriber` |
+| `KAGI_SESSION_TOKEN` | base search, `search --lens`, `assistant`, `translate`, `summarize --subscriber` |
 | `KAGI_API_TOKEN` | public `summarize`, `fastgpt`, `enrich web`, `enrich news` |
 | none | `news`, `smallweb`, `auth status`, `--help` |
 
@@ -125,6 +125,7 @@ notes:
 - base `kagi search` defaults to the session-token path when both credentials are present
 - set `[auth] preferred_auth = "api"` if you want base search to prefer the API path instead
 - `search --lens` always requires `KAGI_SESSION_TOKEN`
+- `translate` currently also requires `python3` with the `curl_cffi` package installed
 - `auth check` validates the selected primary credential without using search fallback logic
 
 for the full command-to-token matrix, use the [`auth-matrix`](https://kagi.micr.dev/reference/auth-matrix) docs page.
@@ -139,6 +140,7 @@ for the full command-to-token matrix, use the [`auth-matrix`](https://kagi.micr.
 | `kagi summarize` | use the paid public summarizer API or the subscriber summarizer with `--subscriber` |
 | `kagi news` | read Kagi News from public JSON endpoints |
 | `kagi assistant` | prompt Kagi Assistant with a subscriber session token |
+| `kagi translate` | translate text through Kagi Translate with a subscriber session token |
 | `kagi fastgpt` | query FastGPT through the paid API |
 | `kagi enrich` | query Kagi's web and news enrichment indexes |
 | `kagi smallweb` | fetch the Kagi Small Web feed |
@@ -200,6 +202,18 @@ continue research with assistant:
 kagi assistant "plan a focused research session in the terminal"
 ```
 
+translate text and keep all text-mode extras:
+
+```bash
+kagi translate "Bonjour tout le monde"
+```
+
+translate only the core text result:
+
+```bash
+kagi translate "Bonjour tout le monde" --no-alternatives --no-word-insights --no-suggestions --no-alignments
+```
+
 use the subscriber summarizer:
 
 ```bash
@@ -258,6 +272,3 @@ for the fuller install matrix and platform-specific setup, use the [installation
 ## license
 
 [mit license](LICENSE)
-
-### todo
-- add https://translate.kagi.com/
diff --git a/docs/api-coverage.md b/docs/api-coverage.md
index 21287e0..f71bab8 100644
--- a/docs/api-coverage.md
+++ b/docs/api-coverage.md
@@ -12,6 +12,7 @@
 - **Subscriber web Summarizer** - implemented on the session-token web-product path via `kagi summarize --subscriber ...`
 - **Kagi News public product endpoints** - implemented via `kagi news ...`
 - **Subscriber web Assistant prompt flow** - implemented on Kagi Assistant's authenticated tagged stream via `kagi assistant ...`
+- **Kagi Translate text mode** - implemented via `kagi translate ...` with runtime bootstrap from `KAGI_SESSION_TOKEN`
 
 ## Source of truth
 
@@ -27,10 +28,6 @@ This CLI also implements non-public or product-only seams:
 - subscriber web Assistant prompt flow via Kagi session-token auth
 - Kagi News product endpoints
 
-## TODO / deferred
-
-- **Kagi Translate** - removed from the public CLI surface until there is a live-verified Session Link compatible implementation
-
 ## Notes
 
 - Lens support is not documented on the official Search API. In this CLI it works through Kagi's live HTML/session flow using the `l=<index>` query parameter.
@@ -39,7 +36,8 @@ This CLI also implements non-public or product-only seams:
 - Base-search fallback to session-token search happens on the user-facing `search` command only. `auth check` validates the selected primary credential without fallback.
 - The paid public Summarizer, FastGPT, and Enrichment APIs require `KAGI_API_TOKEN` and sufficient API credit.
 - The subscriber web Summarizer requires `KAGI_SESSION_TOKEN` and uses the authenticated `GET /mother/summary_labs?...` stream path instead of the public `/api/v0/summarize` endpoint.
-- Live verification on March 16, 2026 showed that `https://translate.kagi.com/api/auth` returns `null` even when the same `KAGI_SESSION_TOKEN` works on `kagi.com`.
-- Because the repo is marketed around Session Link auth, `translate` was removed from the CLI surface until that mismatch is solved.
+- Live verification on March 18, 2026 showed that direct raw-cookie HTTP bootstrap still fails, but a browserless `python3 + curl_cffi` bootstrap can mint `translate_session` from the same `KAGI_SESSION_TOKEN`.
+- After bootstrap, the CLI uses normal Rust HTTP requests for `/api/detect`, `/api/translate`, `/api/alternative-translations`, `/api/text-alignments`, `/api/translation-suggestions`, and `/api/word-insights`.
+- `translate` requires `python3` with the `curl_cffi` package installed at runtime.
 - Assistant requires `KAGI_SESSION_TOKEN` and currently targets `/assistant/prompt` with the same tagged stream protocol used by the web app.
 - News uses `https://news.kagi.com/api/...` JSON endpoints and does not require auth.
diff --git a/docs/commands/translate.mdx b/docs/commands/translate.mdx
new file mode 100644
index 0000000..85ec45d
--- /dev/null
+++ b/docs/commands/translate.mdx
@@ -0,0 +1,259 @@
+---
+title: "translate"
+description: "Complete reference for *kagi* translate command - translate text through Kagi Translate with session-token auth."
+---
+
+# `kagi translate`
+
+Translate text through Kagi Translate and return one JSON envelope with the core translation plus the auxiliary text-mode sections.
+
+## Synopsis
+
+```bash
+kagi translate [OPTIONS] <TEXT>
+```
+
+## Description
+
+`kagi translate` uses your existing `KAGI_SESSION_TOKEN`, bootstraps a `translate_session` at runtime, then calls the live `translate.kagi.com` endpoints over HTTP.
+
+By default the command fetches:
+
+- language detection
+- translated text
+- alternative translations
+- text alignments
+- translation suggestions
+- word insights
+
+If an auxiliary section fails, the core translation still succeeds and the failure is recorded in `warnings`.
+
+## Authentication
+
+**Required:** `KAGI_SESSION_TOKEN`
+
+The command follows the same Session Link auth story as other subscriber features. Save the full Session Link URL with:
+
+```bash
+kagi auth set --session-token 'https://kagi.com/search?token=...'
+```
+
+## Runtime Dependency
+
+Translate bootstrap currently requires:
+
+- `python3`
+- the Python package `curl_cffi`
+
+The CLI shells out once to mint `translate_session`, then uses normal Rust HTTP requests for the rest of the flow.
+
+## Arguments
+
+### `<TEXT>` (Required)
+
+The text to translate.
+
+```bash
+kagi translate "Bonjour tout le monde"
+```
+
+## Core Options
+
+### `--from <LANG>`
+
+Source language code. Default: `auto`.
+
+### `--to <LANG>`
+
+Target language code. Default: `en`.
+
+### `--quality <QUALITY>`
+
+Quality preference passed through to Kagi Translate.
+
+### `--model <MODEL>`
+
+Model override passed through to Kagi Translate.
+
+## Context and Style Options
+
+### `--prediction <TEXT>`
+
+Bias translation toward a predicted completion.
+
+### `--predicted-language <LANG>`
+
+Predicted source language code.
+
+### `--formality <LEVEL>`
+
+Formality hint.
+
+### `--speaker-gender <GENDER>`
+
+Speaker gender hint.
+
+### `--addressee-gender <GENDER>`
+
+Addressee gender hint.
+
+### `--language-complexity <LEVEL>`
+
+Language complexity hint.
+
+### `--translation-style <STYLE>`
+
+Translation style hint.
+
+### `--context <TEXT>`
+
+Extra translation context.
+
+### `--dictionary-language <LANG>`
+
+Dictionary language override.
+
+### `--time-format <FORMAT>`
+
+Time formatting style.
+
+### `--use-definition-context <true|false>`
+
+Toggle definition-aware translation behavior.
+
+### `--enable-language-features <true|false>`
+
+Toggle language-feature enrichment.
+
+### `--preserve-formatting <true|false>`
+
+Preserve formatting when possible.
+
+### `--context-memory-json <JSON>`
+
+Raw JSON array passed through as `context_memory`.
+
+```bash
+kagi translate "Bonjour" \
+  --context-memory-json '[{"kind":"glossary","value":"Use Hello, never Hi"}]'
+```
+
+## Auxiliary Section Controls
+
+### `--no-alternatives`
+
+Skip the alternative translations call.
+
+### `--no-word-insights`
+
+Skip the word insights call.
+
+### `--no-suggestions`
+
+Skip the translation suggestions call.
+
+### `--no-alignments`
+
+Skip the text alignments call.
+
+## Output Format
+
+```json
+{
+  "bootstrap": {
+    "method": "python3+curl_cffi(chrome136)",
+    "authenticated": true
+  },
+  "detected_language": {
+    "iso": "fr",
+    "label": "French"
+  },
+  "translation": {
+    "translation": "Hello everyone"
+  },
+  "alternatives": {
+    "elements": []
+  },
+  "text_alignments": {
+    "alignments": []
+  },
+  "translation_suggestions": {
+    "suggestions": []
+  },
+  "word_insights": {
+    "insights": []
+  },
+  "warnings": []
+}
+```
+
+## Examples
+
+### Basic Translation
+
+```bash
+kagi translate "Bonjour tout le monde"
+```
+
+### Translate to Japanese
+
+```bash
+kagi translate "Hello everyone" --to ja
+```
+
+### Provide Style and Context
+
+```bash
+kagi translate "Can you review this?" \
+  --to fr \
+  --formality more \
+  --translation-style natural \
+  --context "Professional email to a client"
+```
+
+### Fastest Core Output Only
+
+```bash
+kagi translate "Bonjour tout le monde" \
+  --no-alternatives \
+  --no-word-insights \
+  --no-suggestions \
+  --no-alignments
+```
+
+### Extract Just the Translated Text
+
+```bash
+kagi translate "Bonjour tout le monde" | jq -r '.translation.translation'
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error - see stderr |
+
+## Troubleshooting
+
+### Missing bootstrap dependency
+
+If you see an error mentioning `python3` or `curl_cffi`, install the missing dependency and retry.
+
+### Invalid session token
+
+Refresh your Session Link and save it again:
+
+```bash
+kagi auth set --session-token 'https://kagi.com/search?token=...'
+```
+
+### Auxiliary section warnings
+
+If `warnings` is non-empty, the translation succeeded but one or more optional follow-on calls were rejected or unavailable.
+
+## See Also
+
+- [Authentication Guide](/guides/authentication)
+- [Auth Matrix](/reference/auth-matrix)
+- [Coverage](/reference/coverage)
diff --git a/docs/docs.json b/docs/docs.json
index 8285979..f0add9c 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -85,6 +85,7 @@
             "group": "AI & Enrichment",
             "pages": [
               "commands/assistant",
+              "commands/translate",
               "commands/fastgpt",
               "commands/enrich"
             ]
diff --git a/docs/index.mdx b/docs/index.mdx
index 6fdb7c7..30fa254 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -51,6 +51,8 @@ Unlock the full potential of your Kagi subscription:
 
 - **Assistant Integration**: Prompt Kagi Assistant programmatically and continue conversations across sessions.
 
+- **Translate Integration**: Run Kagi Translate text mode from the terminal with one JSON response envelope.
+
 - **Subscriber Features**: Access subscriber-only capabilities like the web-based Summarizer with full control over output length and style.
 
 ## Feature Overview
@@ -69,13 +71,14 @@ The `kagi search` command provides multiple pathways depending on your authentic
 
 Two credential types serve different purposes:
 
-- **KAGI_SESSION_TOKEN**: Unlocks subscriber features including lens search, Assistant, and subscriber Summarizer. Obtained from your Kagi Session Link URL.
+- **KAGI_SESSION_TOKEN**: Unlocks subscriber features including lens search, Assistant, subscriber Summarizer, and Translate text mode. Obtained from your Kagi Session Link URL.
 
 - **KAGI_API_TOKEN**: Enables paid public API commands including FastGPT, public Summarizer, and enrichment APIs. Requires API credit.
 
 ### Content Processing
 
 - **Summarization**: Both paid public API and subscriber web paths with multiple engines, styles, and output lengths
+- **Translation**: Text-mode Kagi Translate with detection, alternatives, alignments, suggestions, and word insights
 - **FastGPT**: Quick answers powered by Kagi's FastGPT API
 - **Enrichment**: Query specialized web and news indexes
 - **Assistant**: Full conversation support with thread continuation
@@ -106,7 +109,8 @@ flowchart TB
         web1["search --lens"]
         web2["assistant"]
         web3["summarize --subscriber"]
-        web4["search (session)"]
+        web4["translate"]
+        web5["search (session)"]
     end
     
     subgraph PublicFeeds["Public Feeds (No Auth)"]
@@ -158,7 +162,6 @@ Choose your path based on your current needs:
 
 ### Runtime Requirements
 
-- No runtime dependencies (self-contained binary)
 - Network connectivity to kagi.com
 - Shell environment (Bash, Zsh, Fish, PowerShell, or CMD)
 
@@ -167,6 +170,7 @@ Choose your path based on your current needs:
 - **For scripting**: `jq` for JSON processing (recommended)
 - **For development**: Rust toolchain 1.70+
 - **For npm install**: Node.js 16+ and npm, pnpm, or bun
+- **For `kagi translate`**: `python3` with the `curl_cffi` package installed
 
 ## Design Principles in Practice
 
diff --git a/docs/reference/auth-matrix.mdx b/docs/reference/auth-matrix.mdx
index 611f22a..a37de66 100644
--- a/docs/reference/auth-matrix.mdx
+++ b/docs/reference/auth-matrix.mdx
@@ -20,6 +20,7 @@ This reference provides a complete mapping of which commands require which authe
 | `summarize --subscriber` | `KAGI_SESSION_TOKEN` | None | Subscriber web product |
 | `news` | None | None | Public endpoint |
 | `assistant` | `KAGI_SESSION_TOKEN` | None | Subscriber feature |
+| `translate` | `KAGI_SESSION_TOKEN` | None | Text mode only; runtime bootstrap needs `python3 + curl_cffi` |
 | `fastgpt` | `KAGI_API_TOKEN` | None | Paid public API |
 | `enrich web` | `KAGI_API_TOKEN` | None | Paid public API |
 | `enrich news` | `KAGI_API_TOKEN` | None | Paid public API |
@@ -103,6 +104,7 @@ flowchart TD
 | Command | Token | Purpose |
 |---------|-------|---------|
 | `assistant` | `KAGI_SESSION_TOKEN` | Conversational AI with threads |
+| `translate` | `KAGI_SESSION_TOKEN` | Kagi Translate text mode |
 | `fastgpt` | `KAGI_API_TOKEN` | Quick factual answers |
 
 ### Data Commands
@@ -131,6 +133,7 @@ Requires `KAGI_SESSION_TOKEN`:
 
 - ✅ Lens-aware search (`--lens`)
 - ✅ Kagi Assistant (`assistant`)
+- ✅ Kagi Translate (`translate`)
 - ✅ Subscriber Summarizer (`summarize --subscriber`)
 - ✅ Base search (fallback)
 
@@ -207,6 +210,7 @@ kagi auth set --session-token 'https://kagi.com/search?token=...'
 - ✅ `kagi search "query"` (uses session path)
 - ✅ `kagi search --lens 2 "query"`
 - ✅ `kagi assistant "prompt"`
+- ✅ `kagi translate "Bonjour tout le monde"`
 - ✅ `kagi summarize --subscriber --url ...`
 - ✅ `kagi news`
 - ✅ `kagi smallweb`
@@ -313,6 +317,7 @@ kagi assistant "prompt"
 | Use my lens | Session | `kagi search --lens` |
 | Quick answers | API | `kagi fastgpt` |
 | AI conversation | Session | `kagi assistant` |
+| Translate text | Session | `kagi translate` |
 | Summarize (free API) | API | `kagi summarize --url` |
 | Summarize (subscription) | Session | `kagi summarize --subscriber` |
 | Read news | None | `kagi news` |
diff --git a/docs/reference/coverage.mdx b/docs/reference/coverage.mdx
index 7222877..6993f5a 100644
--- a/docs/reference/coverage.mdx
+++ b/docs/reference/coverage.mdx
@@ -31,6 +31,7 @@ These features use the subscriber web product (Session Token):
 | Lens Search | `kagi search --lens` | ✅ Implemented |
 | Web Summarizer | `kagi summarize --subscriber` | ✅ Implemented |
 | Assistant | `kagi assistant` | ✅ Implemented |
+| Translate (text mode) | `kagi translate` | ✅ Implemented |
 
 ### Public Product Endpoints
 
@@ -56,6 +57,7 @@ These require no authentication:
 | `summarize --subscriber` | Web summarizer | Session | ✅ |
 | `news` | News feed | None | ✅ |
 | `assistant` | AI assistant | Session | ✅ |
+| `translate` | Kagi Translate text mode | Session | ✅ |
 | `fastgpt` | Fast answers | API | ✅ |
 | `enrich web` | Web enrichment | API | ✅ |
 | `enrich news` | News enrichment | API | ✅ |
@@ -81,6 +83,8 @@ These require no authentication:
 | `--web-search` | fastgpt | ✅ |
 | `--target-language` | summarize | ✅ |
 | `--thread-id` | assistant | ✅ |
+| `--from`, `--to` | translate | ✅ |
+| `--no-alternatives`, `--no-word-insights`, `--no-suggestions`, `--no-alignments` | translate | ✅ |
 
 ## Not Available
 
@@ -88,15 +92,7 @@ These require no authentication:
 
 These features were evaluated and left out of the public CLI surface:
 
-#### Translate
-
-**Status:** ❌ Not implemented
-
-**Reason:** The current Session Link implementation is not sufficient for `translate.kagi.com` as deployed. The endpoint requires additional authentication mechanisms that are incompatible with the Session Link token model.
-
-**Decision:** Rather than ship a fragile compatibility layer that might break, the feature is excluded until there is a viable authentication path.
-
-**Alternative:** Use the web interface at [translate.kagi.com](https://translate.kagi.com)
+There is no public CLI support today for document, website, image, proofread, dictionary, or voice modes from Kagi Translate. The implemented scope is text mode only.
 
 ## API Surface Philosophy
 
@@ -120,7 +116,7 @@ These features were evaluated and left out of the public CLI surface:
 
 | Type | Support | Commands |
 |------|---------|----------|
-| Session Token | ✅ | search, summarize --subscriber, assistant |
+| Session Token | ✅ | search, summarize --subscriber, assistant, translate |
 | API Token | ✅ | search, summarize, fastgpt, enrich |
 
 ### Authentication Patterns
@@ -146,6 +142,7 @@ All commands output JSON:
 | smallweb | Stable |
 | summarize | Stable |
 | assistant | Stable |
+| translate | Stable |
 | fastgpt | Stable |
 | enrich | Stable |
 
@@ -183,6 +180,8 @@ All commands output JSON:
 | GitHub Releases | ✅ |
 | Build from source | ✅ |
 
+**Translate runtime note:** `kagi translate` additionally requires `python3` with the `curl_cffi` package installed.
+
 ## Feature Comparison Matrix
 
 ### vs Kagi Web Product
@@ -193,7 +192,7 @@ All commands output JSON:
 | Lens Search | ✅ | ✅ |
 | Assistant | ✅ (basic) | ✅ (full) |
 | Summarizer | ✅ | ✅ |
-| Translate | ❌ | ✅ |
+| Translate | ✅ (text mode) | ✅ |
 | Settings | ❌ | ✅ |
 | Billing | ❌ | ✅ |
 
diff --git a/docs/reference/error-reference.mdx b/docs/reference/error-reference.mdx
index f12d42a..6df9792 100644
--- a/docs/reference/error-reference.mdx
+++ b/docs/reference/error-reference.mdx
@@ -155,6 +155,21 @@ rm ./.kagi.toml
 kagi auth set --session-token 'YOUR_TOKEN'
 ```
 
+### "kagi translate requires `python3` with the `curl_cffi` package installed"
+
+**Meaning:** The translate bootstrap helper is missing a local runtime dependency.
+
+**Solution:**
+```bash
+python3 -m pip install --user curl_cffi
+```
+
+Then retry:
+
+```bash
+kagi translate "Bonjour tout le monde"
+```
+
 ## Command Errors
 
 ### "--length requires --subscriber"
diff --git a/docs/reference/output-contract.mdx b/docs/reference/output-contract.mdx
index a2cef36..48dc496 100644
--- a/docs/reference/output-contract.mdx
+++ b/docs/reference/output-contract.mdx
@@ -137,6 +137,37 @@ Subscriber mode:
 }
 ```
 
+### `kagi translate`
+
+```json
+{
+  "bootstrap": {
+    "method": "python3+curl_cffi(chrome136)",
+    "authenticated": true
+  },
+  "detected_language": {
+    "iso": "fr",
+    "label": "French"
+  },
+  "translation": {
+    "translation": "Hello everyone"
+  },
+  "alternatives": {
+    "elements": []
+  },
+  "text_alignments": {
+    "alignments": []
+  },
+  "translation_suggestions": {
+    "suggestions": []
+  },
+  "word_insights": {
+    "insights": []
+  },
+  "warnings": []
+}
+```
+
 ### `kagi fastgpt`
 
 ```json
@@ -221,6 +252,9 @@ kagi fastgpt "What is Rust?" | jq -r '.data.output'
 # Assistant markdown reply
 kagi assistant "Hello" | jq -r '.message.markdown'
 
+# Translate text
+kagi translate "Bonjour tout le monde" | jq -r '.translation.translation'
+
 # Subscriber summary text
 kagi summarize --subscriber --url https://example.com | jq -r '.data.output'
 
diff --git a/src/api.rs b/src/api.rs
index b6d2bd5..15b047a 100644
--- a/src/api.rs
+++ b/src/api.rs
@@ -1,23 +1,29 @@
 use std::collections::HashMap;
+use std::future::Future;
+use std::process::Stdio;
 
 use reqwest::{Client, StatusCode, header};
 use serde::Deserialize;
 #[cfg(test)]
 use serde::Serialize;
 use serde::de::DeserializeOwned;
-use serde_json::Value;
 use serde_json::json;
+use serde_json::{Map, Value};
+use tokio::process::Command;
 
 use crate::error::KagiError;
 #[cfg(test)]
 use crate::types::ApiMeta;
 use crate::types::{
-    AssistantMessage, AssistantMeta, AssistantPromptRequest, AssistantPromptResponse,
-    AssistantThread, EnrichResponse, FastGptRequest, FastGptResponse, NewsBatchCategories,
-    NewsBatchCategory, NewsCategoriesResponse, NewsCategoryMetadata, NewsCategoryMetadataList,
-    NewsChaos, NewsChaosResponse, NewsLatestBatch, NewsResolvedCategory, NewsStoriesPayload,
-    NewsStoriesResponse, SmallWebFeed, SubscriberSummarization, SubscriberSummarizeMeta,
-    SubscriberSummarizeRequest, SubscriberSummarizeResponse, SummarizeRequest, SummarizeResponse,
+    AlternativeTranslationsResponse, AssistantMessage, AssistantMeta, AssistantPromptRequest,
+    AssistantPromptResponse, AssistantThread, EnrichResponse, FastGptRequest, FastGptResponse,
+    NewsBatchCategories, NewsBatchCategory, NewsCategoriesResponse, NewsCategoryMetadata,
+    NewsCategoryMetadataList, NewsChaos, NewsChaosResponse, NewsLatestBatch, NewsResolvedCategory,
+    NewsStoriesPayload, NewsStoriesResponse, SmallWebFeed, SubscriberSummarization,
+    SubscriberSummarizeMeta, SubscriberSummarizeRequest, SubscriberSummarizeResponse,
+    SummarizeRequest, SummarizeResponse, TextAlignmentsResponse, TranslateBootstrapMetadata,
+    TranslateCommandRequest, TranslateDetectedLanguage, TranslateOptionState, TranslateResponse,
+    TranslateTextResponse, TranslateWarning, TranslationSuggestionsResponse, WordInsightsResponse,
 };
 
 const USER_AGENT: &str = "kagi-cli/0.1.0 (+https://github.com/)";
@@ -31,6 +37,14 @@ const KAGI_FASTGPT_URL: &str = "https://kagi.com/api/v0/fastgpt";
 const KAGI_ENRICH_WEB_URL: &str = "https://kagi.com/api/v0/enrich/web";
 const KAGI_ENRICH_NEWS_URL: &str = "https://kagi.com/api/v0/enrich/news";
 const KAGI_SMALLWEB_FEED_URL: &str = "https://kagi.com/api/v1/smallweb/feed/";
+const KAGI_TRANSLATE_DETECT_URL: &str = "https://translate.kagi.com/api/detect";
+const KAGI_TRANSLATE_URL: &str = "https://translate.kagi.com/api/translate";
+const KAGI_TRANSLATE_ALTERNATIVES_URL: &str =
+    "https://translate.kagi.com/api/alternative-translations";
+const KAGI_TRANSLATE_ALIGNMENTS_URL: &str = "https://translate.kagi.com/api/text-alignments";
+const KAGI_TRANSLATE_SUGGESTIONS_URL: &str =
+    "https://translate.kagi.com/api/translation-suggestions";
+const KAGI_TRANSLATE_WORD_INSIGHTS_URL: &str = "https://translate.kagi.com/api/word-insights";
 const ASSISTANT_ZERO_BRANCH_UUID: &str = "00000000-0000-4000-0000-000000000000";
 
 pub async fn execute_summarize(
@@ -365,6 +379,137 @@ pub async fn execute_assistant_prompt(
     }
 }
 
+pub async fn execute_translate(
+    request: &TranslateCommandRequest,
+    session_token: &str,
+) -> Result<TranslateResponse, KagiError> {
+    if session_token.trim().is_empty() {
+        return Err(KagiError::Auth(
+            "missing Kagi session token (expected KAGI_SESSION_TOKEN)".to_string(),
+        ));
+    }
+
+    if request.text.trim().is_empty() {
+        return Err(KagiError::Config(
+            "translate text cannot be empty".to_string(),
+        ));
+    }
+
+    if request.from.trim().is_empty() {
+        return Err(KagiError::Config(
+            "translate --from cannot be empty".to_string(),
+        ));
+    }
+
+    if request.to.trim().is_empty() {
+        return Err(KagiError::Config(
+            "translate --to cannot be empty".to_string(),
+        ));
+    }
+
+    let bootstrap = bootstrap_translate_session(session_token).await?;
+    let client = build_client()?;
+    let cookie_header = build_translate_cookie_header(session_token, &bootstrap.translate_session);
+    let detected_language =
+        execute_translate_detect(&client, &cookie_header, request.text.trim()).await?;
+    let effective_source_language =
+        effective_translate_source_language(&request.from, &detected_language);
+    let translation = execute_translate_text(
+        &client,
+        &cookie_header,
+        request,
+        &bootstrap.translate_session,
+        &effective_source_language,
+    )
+    .await?;
+    let translation_options = build_translate_option_state(request);
+    let translated_text = translation.translation.clone();
+    let target_language = request.to.clone();
+    let translate_session = bootstrap.translate_session.clone();
+
+    let (alternatives_result, alignments_result, suggestions_result, insights_result) = tokio::join!(
+        capture_optional_translate_section(
+            "alternatives",
+            request.fetch_alternatives,
+            execute_translate_alternatives(
+                &client,
+                &cookie_header,
+                &translate_session,
+                request,
+                &effective_source_language,
+                &translated_text,
+                translation_options.as_ref(),
+            ),
+        ),
+        capture_optional_translate_section(
+            "text_alignments",
+            request.fetch_alignments,
+            execute_translate_text_alignments(
+                &client,
+                &cookie_header,
+                &translate_session,
+                request.text.trim(),
+                &translated_text,
+            ),
+        ),
+        capture_optional_translate_section(
+            "translation_suggestions",
+            request.fetch_suggestions,
+            execute_translate_suggestions(
+                &client,
+                &cookie_header,
+                &translate_session,
+                request.text.trim(),
+                &translated_text,
+                &effective_source_language,
+                &target_language,
+                translation_options.as_ref(),
+            ),
+        ),
+        capture_optional_translate_section(
+            "word_insights",
+            request.fetch_word_insights,
+            execute_translate_word_insights(
+                &client,
+                &cookie_header,
+                &translate_session,
+                request.text.trim(),
+                &translated_text,
+                translation_options.as_ref(),
+            ),
+        ),
+    );
+
+    let (alternatives, alternatives_warning) = alternatives_result;
+    let (text_alignments, alignments_warning) = alignments_result;
+    let (translation_suggestions, suggestions_warning) = suggestions_result;
+    let (word_insights, insights_warning) = insights_result;
+
+    let warnings = vec![
+        alternatives_warning,
+        alignments_warning,
+        suggestions_warning,
+        insights_warning,
+    ]
+    .into_iter()
+    .flatten()
+    .collect();
+
+    Ok(TranslateResponse {
+        bootstrap: TranslateBootstrapMetadata {
+            method: bootstrap.method,
+            authenticated: true,
+        },
+        detected_language,
+        translation,
+        alternatives,
+        text_alignments,
+        translation_suggestions,
+        word_insights,
+        warnings,
+    })
+}
+
 pub async fn execute_fastgpt(
     request: &FastGptRequest,
     token: &str,
@@ -445,6 +590,388 @@ async fn execute_enrich(
     decode_kagi_json(response, surface).await
 }
 
+async fn bootstrap_translate_session(
+    session_token: &str,
+) -> Result<TranslateBootstrapResult, KagiError> {
+    const BOOTSTRAP_SCRIPT: &str = r#"import json
+import os
+import sys
+
+def finish(ok, **kwargs):
+    payload = {"ok": ok}
+    payload.update(kwargs)
+    print(json.dumps(payload))
+    sys.exit(0 if ok else 1)
+
+token = os.environ.get("KAGI_SESSION_TOKEN_RAW", "").strip()
+if not token:
+    finish(False, kind="config", message="missing normalized KAGI session token")
+
+try:
+    from curl_cffi import requests
+except Exception as exc:
+    finish(
+        False,
+        kind="config",
+        message="kagi translate requires python3 with the curl_cffi package installed",
+        detail=str(exc),
+    )
+
+try:
+    session = requests.Session(impersonate="chrome136")
+    session.cookies.set("kagi_session", token, domain=".kagi.com", path="/", secure=True)
+    response = session.get("https://translate.kagi.com/", timeout=30, allow_redirects=True)
+except Exception as exc:
+    finish(False, kind="network", message="translate bootstrap request failed", detail=str(exc))
+
+if response.status_code >= 400:
+    finish(
+        False,
+        kind="network",
+        message=f"translate bootstrap returned HTTP {response.status_code}",
+    )
+
+translate_session = ""
+for cookie in session.cookies.jar:
+    if cookie.name == "translate_session" and cookie.value:
+        translate_session = cookie.value
+        break
+
+if not translate_session:
+    finish(
+        False,
+        kind="auth",
+        message="translate bootstrap did not mint a translate_session cookie",
+    )
+
+finish(
+    True,
+    translate_session=translate_session,
+    method="python3+curl_cffi(chrome136)",
+)
+"#;
+
+    let output = Command::new("python3")
+        .arg("-c")
+        .arg(BOOTSTRAP_SCRIPT)
+        .env("KAGI_SESSION_TOKEN_RAW", session_token)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .output()
+        .await
+        .map_err(|error| match error.kind() {
+            std::io::ErrorKind::NotFound => KagiError::Config(
+                "kagi translate requires `python3` with the `curl_cffi` package installed"
+                    .to_string(),
+            ),
+            _ => KagiError::Config(format!(
+                "failed to start translate bootstrap helper: {error}"
+            )),
+        })?;
+
+    let stdout = String::from_utf8(output.stdout).map_err(|error| {
+        KagiError::Parse(format!(
+            "translate bootstrap helper returned non-UTF-8 output: {error}"
+        ))
+    })?;
+    let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
+    let trimmed_stdout = stdout.trim();
+
+    if trimmed_stdout.is_empty() {
+        return Err(KagiError::Config(if stderr.is_empty() {
+            "translate bootstrap helper returned no output".to_string()
+        } else {
+            format!("translate bootstrap helper failed: {stderr}")
+        }));
+    }
+
+    let parsed: TranslateBootstrapScriptOutput =
+        serde_json::from_str(trimmed_stdout).map_err(|error| {
+            KagiError::Parse(format!(
+                "failed to parse translate bootstrap helper output: {error}"
+            ))
+        })?;
+
+    if parsed.ok {
+        let translate_session = parsed.translate_session.ok_or_else(|| {
+            KagiError::Parse(
+                "translate bootstrap helper did not return translate_session".to_string(),
+            )
+        })?;
+        let method = parsed
+            .method
+            .unwrap_or_else(|| "python3+curl_cffi".to_string());
+
+        return Ok(TranslateBootstrapResult {
+            translate_session,
+            method,
+        });
+    }
+
+    let mut message = parsed
+        .message
+        .unwrap_or_else(|| "translate bootstrap failed".to_string());
+    if !stderr.is_empty() {
+        message.push_str(&format!("; stderr: {stderr}"));
+    }
+
+    Err(map_bootstrap_kind_to_error(
+        parsed.kind.as_deref().unwrap_or("config"),
+        &message,
+    ))
+}
+
+async fn execute_translate_detect(
+    client: &Client,
+    cookie_header: &str,
+    text: &str,
+) -> Result<TranslateDetectedLanguage, KagiError> {
+    let response = client
+        .post(KAGI_TRANSLATE_DETECT_URL)
+        .header(header::COOKIE, cookie_header)
+        .header(header::CONTENT_TYPE, "application/json")
+        .json(&json!({
+            "text": text,
+            "include_alternatives": true,
+        }))
+        .send()
+        .await
+        .map_err(map_transport_error)?;
+
+    let value: Value = decode_translate_json(response, "language detection").await?;
+    parse_translate_detect_value(value)
+}
+
+async fn execute_translate_text(
+    client: &Client,
+    cookie_header: &str,
+    request: &TranslateCommandRequest,
+    translate_session: &str,
+    effective_source_language: &str,
+) -> Result<TranslateTextResponse, KagiError> {
+    let response = client
+        .post(KAGI_TRANSLATE_URL)
+        .header(header::COOKIE, cookie_header)
+        .header(header::CONTENT_TYPE, "application/json")
+        .json(&build_translate_payload(
+            request,
+            translate_session,
+            effective_source_language,
+        ))
+        .send()
+        .await
+        .map_err(map_transport_error)?;
+
+    decode_translate_json(response, "translation").await
+}
+
+async fn execute_translate_alternatives(
+    client: &Client,
+    cookie_header: &str,
+    translate_session: &str,
+    request: &TranslateCommandRequest,
+    effective_source_language: &str,
+    translated_text: &str,
+    translation_options: Option<&TranslateOptionState>,
+) -> Result<AlternativeTranslationsResponse, KagiError> {
+    let mut payload = Map::new();
+    payload.insert(
+        "original_text".to_string(),
+        Value::String(request.text.clone()),
+    );
+    payload.insert(
+        "existing_translation".to_string(),
+        Value::String(translated_text.to_string()),
+    );
+    payload.insert(
+        "source_lang".to_string(),
+        Value::String(effective_source_language.to_string()),
+    );
+    payload.insert("target_lang".to_string(), Value::String(request.to.clone()));
+    payload.insert(
+        "session_token".to_string(),
+        Value::String(translate_session.to_string()),
+    );
+
+    if let Some(quality) = normalize_aux_quality(request.quality.as_deref()) {
+        payload.insert("quality".to_string(), Value::String(quality));
+    }
+
+    if let Some(options) = translation_options {
+        payload.insert(
+            "translation_options".to_string(),
+            serde_json::to_value(options).map_err(|error| {
+                KagiError::Parse(format!(
+                    "failed to serialize translate alternatives options: {error}"
+                ))
+            })?,
+        );
+    }
+
+    let response = client
+        .post(KAGI_TRANSLATE_ALTERNATIVES_URL)
+        .header(header::COOKIE, cookie_header)
+        .header(header::CONTENT_TYPE, "application/json")
+        .json(&Value::Object(payload))
+        .send()
+        .await
+        .map_err(map_transport_error)?;
+
+    decode_translate_json(response, "alternative translations").await
+}
+
+async fn execute_translate_text_alignments(
+    client: &Client,
+    cookie_header: &str,
+    translate_session: &str,
+    source_text: &str,
+    target_text: &str,
+) -> Result<TextAlignmentsResponse, KagiError> {
+    let response = client
+        .post(KAGI_TRANSLATE_ALIGNMENTS_URL)
+        .header(header::COOKIE, cookie_header)
+        .header(header::CONTENT_TYPE, "application/json")
+        .json(&json!({
+            "source_text": source_text,
+            "target_text": target_text,
+            "session_token": translate_session,
+        }))
+        .send()
+        .await
+        .map_err(map_transport_error)?;
+
+    decode_translate_json(response, "text alignments").await
+}
+
+async fn execute_translate_suggestions(
+    client: &Client,
+    cookie_header: &str,
+    translate_session: &str,
+    source_text: &str,
+    target_text: &str,
+    source_language: &str,
+    target_language: &str,
+    translation_options: Option<&TranslateOptionState>,
+) -> Result<TranslationSuggestionsResponse, KagiError> {
+    let mut payload = Map::new();
+    payload.insert(
+        "originalText".to_string(),
+        Value::String(source_text.to_string()),
+    );
+    payload.insert(
+        "translatedText".to_string(),
+        Value::String(target_text.to_string()),
+    );
+    payload.insert(
+        "sourceLanguage".to_string(),
+        Value::String(source_language.to_string()),
+    );
+    payload.insert(
+        "targetLanguage".to_string(),
+        Value::String(target_language.to_string()),
+    );
+    payload.insert("language".to_string(), Value::String("en".to_string()));
+    payload.insert(
+        "session_token".to_string(),
+        Value::String(translate_session.to_string()),
+    );
+
+    if let Some(options) = translation_options {
+        payload.insert(
+            "translationOptions".to_string(),
+            serde_json::to_value(options).map_err(|error| {
+                KagiError::Parse(format!(
+                    "failed to serialize translate suggestion options: {error}"
+                ))
+            })?,
+        );
+    }
+
+    let response = client
+        .post(KAGI_TRANSLATE_SUGGESTIONS_URL)
+        .header(header::COOKIE, cookie_header)
+        .header(header::CONTENT_TYPE, "application/json")
+        .json(&Value::Object(payload))
+        .send()
+        .await
+        .map_err(map_transport_error)?;
+
+    decode_translate_json(response, "translation suggestions").await
+}
+
+async fn execute_translate_word_insights(
+    client: &Client,
+    cookie_header: &str,
+    translate_session: &str,
+    source_text: &str,
+    target_text: &str,
+    translation_options: Option<&TranslateOptionState>,
+) -> Result<WordInsightsResponse, KagiError> {
+    let mut payload = Map::new();
+    payload.insert(
+        "original_text".to_string(),
+        Value::String(source_text.to_string()),
+    );
+    payload.insert(
+        "translated_text".to_string(),
+        Value::String(target_text.to_string()),
+    );
+    payload.insert(
+        "target_explanation_language".to_string(),
+        Value::String("en".to_string()),
+    );
+    payload.insert(
+        "session_token".to_string(),
+        Value::String(translate_session.to_string()),
+    );
+
+    if let Some(options) = translation_options {
+        payload.insert(
+            "translation_options".to_string(),
+            serde_json::to_value(options).map_err(|error| {
+                KagiError::Parse(format!(
+                    "failed to serialize translate word-insight options: {error}"
+                ))
+            })?,
+        );
+    }
+
+    let response = client
+        .post(KAGI_TRANSLATE_WORD_INSIGHTS_URL)
+        .header(header::COOKIE, cookie_header)
+        .header(header::CONTENT_TYPE, "application/json")
+        .json(&Value::Object(payload))
+        .send()
+        .await
+        .map_err(map_transport_error)?;
+
+    decode_translate_json(response, "word insights").await
+}
+
+async fn capture_optional_translate_section<T, F>(
+    section: &'static str,
+    enabled: bool,
+    future: F,
+) -> (Option<T>, Option<TranslateWarning>)
+where
+    F: Future<Output = Result<T, KagiError>>,
+{
+    if !enabled {
+        return (None, None);
+    }
+
+    match future.await {
+        Ok(value) => (Some(value), None),
+        Err(error) => (
+            None,
+            Some(TranslateWarning {
+                section: section.to_string(),
+                message: error.to_string(),
+            }),
+        ),
+    }
+}
+
 fn normalize_subscriber_summary_input(
     request: &SubscriberSummarizeRequest,
 ) -> Result<(&'static str, String), KagiError> {
@@ -732,6 +1259,177 @@ fn format_client_error_suffix(body: &str) -> String {
     format!("; {trimmed}")
 }
 
+fn build_translate_cookie_header(session_token: &str, translate_session: &str) -> String {
+    format!("kagi_session={session_token}; translate_session={translate_session}")
+}
+
+fn effective_translate_source_language(
+    requested_from: &str,
+    detected_language: &TranslateDetectedLanguage,
+) -> String {
+    if requested_from.eq_ignore_ascii_case("auto") && !detected_language.iso.trim().is_empty() {
+        detected_language.iso.clone()
+    } else {
+        requested_from.to_string()
+    }
+}
+
+fn build_translate_option_state(request: &TranslateCommandRequest) -> Option<TranslateOptionState> {
+    let options = TranslateOptionState {
+        formality: request.formality.clone(),
+        speaker_gender: request.speaker_gender.clone(),
+        addressee_gender: request.addressee_gender.clone(),
+        language_complexity: request.language_complexity.clone(),
+        style: request.translation_style.clone(),
+        context: request.context.clone(),
+    };
+
+    if options.formality.is_none()
+        && options.speaker_gender.is_none()
+        && options.addressee_gender.is_none()
+        && options.language_complexity.is_none()
+        && options.style.is_none()
+        && options.context.is_none()
+    {
+        None
+    } else {
+        Some(options)
+    }
+}
+
+fn build_translate_payload(
+    request: &TranslateCommandRequest,
+    translate_session: &str,
+    effective_source_language: &str,
+) -> Value {
+    let mut payload = Map::new();
+    payload.insert("text".to_string(), Value::String(request.text.clone()));
+    payload.insert(
+        "from".to_string(),
+        Value::String(effective_source_language.to_string()),
+    );
+    payload.insert("to".to_string(), Value::String(request.to.clone()));
+    payload.insert("stream".to_string(), Value::Bool(false));
+    payload.insert(
+        "session_token".to_string(),
+        Value::String(translate_session.to_string()),
+    );
+
+    insert_optional_string(&mut payload, "quality", request.quality.as_deref());
+    insert_optional_string(&mut payload, "model", request.model.as_deref());
+    insert_optional_string(&mut payload, "prediction", request.prediction.as_deref());
+    insert_optional_string(
+        &mut payload,
+        "predicted_language",
+        request.predicted_language.as_deref(),
+    );
+    insert_optional_string(&mut payload, "formality", request.formality.as_deref());
+    insert_optional_string(
+        &mut payload,
+        "speaker_gender",
+        request.speaker_gender.as_deref(),
+    );
+    insert_optional_string(
+        &mut payload,
+        "addressee_gender",
+        request.addressee_gender.as_deref(),
+    );
+    insert_optional_string(
+        &mut payload,
+        "language_complexity",
+        request.language_complexity.as_deref(),
+    );
+    insert_optional_string(
+        &mut payload,
+        "translation_style",
+        request.translation_style.as_deref(),
+    );
+    insert_optional_string(&mut payload, "context", request.context.as_deref());
+    insert_optional_string(
+        &mut payload,
+        "dictionary_language",
+        request.dictionary_language.as_deref(),
+    );
+    insert_optional_string(&mut payload, "time_format", request.time_format.as_deref());
+    insert_optional_bool(
+        &mut payload,
+        "use_definition_context",
+        request.use_definition_context,
+    );
+    insert_optional_bool(
+        &mut payload,
+        "enable_language_features",
+        request.enable_language_features,
+    );
+    insert_optional_bool(
+        &mut payload,
+        "preserve_formatting",
+        request.preserve_formatting,
+    );
+
+    if let Some(context_memory) = &request.context_memory {
+        payload.insert(
+            "context_memory".to_string(),
+            Value::Array(context_memory.clone()),
+        );
+    }
+
+    Value::Object(payload)
+}
+
+fn insert_optional_string(payload: &mut Map<String, Value>, key: &str, value: Option<&str>) {
+    if let Some(value) = value {
+        payload.insert(key.to_string(), Value::String(value.to_string()));
+    }
+}
+
+fn insert_optional_bool(payload: &mut Map<String, Value>, key: &str, value: Option<bool>) {
+    if let Some(value) = value {
+        payload.insert(key.to_string(), Value::Bool(value));
+    }
+}
+
+fn normalize_aux_quality(raw: Option<&str>) -> Option<String> {
+    raw.map(|value| {
+        if value == "best" || value.starts_with("deep_") {
+            "best".to_string()
+        } else {
+            "standard".to_string()
+        }
+    })
+}
+
+fn parse_translate_detect_value(value: Value) -> Result<TranslateDetectedLanguage, KagiError> {
+    let candidate = match value {
+        Value::Array(mut values) => values.drain(..).next().ok_or_else(|| {
+            KagiError::Parse(
+                "failed to parse translate language detection response: empty array".to_string(),
+            )
+        })?,
+        Value::Object(_) => value,
+        other => {
+            return Err(KagiError::Parse(format!(
+                "failed to parse translate language detection response: unexpected payload {other}"
+            )));
+        }
+    };
+
+    serde_json::from_value(candidate).map_err(|error| {
+        KagiError::Parse(format!(
+            "failed to parse translate language detection response: {error}"
+        ))
+    })
+}
+
+fn map_bootstrap_kind_to_error(kind: &str, message: &str) -> KagiError {
+    match kind {
+        "auth" => KagiError::Auth(message.to_string()),
+        "network" => KagiError::Network(message.to_string()),
+        "parse" => KagiError::Parse(message.to_string()),
+        _ => KagiError::Config(message.to_string()),
+    }
+}
+
 #[derive(Debug, Deserialize)]
 struct ApiErrorBody {
     #[allow(dead_code)]
@@ -805,6 +1503,25 @@ struct AssistantMessagePayload {
     profile: Option<Value>,
 }
 
+#[derive(Debug, Deserialize)]
+struct TranslateBootstrapScriptOutput {
+    ok: bool,
+    #[serde(default)]
+    kind: Option<String>,
+    #[serde(default)]
+    message: Option<String>,
+    #[serde(default)]
+    translate_session: Option<String>,
+    #[serde(default)]
+    method: Option<String>,
+}
+
+#[derive(Debug)]
+struct TranslateBootstrapResult {
+    translate_session: String,
+    method: String,
+}
+
 async fn decode_kagi_json<T>(response: reqwest::Response, surface: &str) -> Result<T, KagiError>
 where
     T: DeserializeOwned,
@@ -871,6 +1588,50 @@ where
     }
 }
 
+async fn decode_translate_json<T>(
+    response: reqwest::Response,
+    surface: &str,
+) -> Result<T, KagiError>
+where
+    T: DeserializeOwned,
+{
+    match response.status() {
+        StatusCode::OK => {
+            let body = response.text().await.map_err(|error| {
+                KagiError::Network(format!(
+                    "failed to read Kagi Translate {surface} response body: {error}"
+                ))
+            })?;
+            if looks_like_html_document(&body) {
+                return Err(KagiError::Auth(
+                    "invalid or expired Kagi session token for Kagi Translate".to_string(),
+                ));
+            }
+            serde_json::from_str(&body).map_err(|error| {
+                KagiError::Parse(format!(
+                    "failed to parse Kagi Translate {surface} response: {error}"
+                ))
+            })
+        }
+        StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN => Err(KagiError::Auth(
+            "invalid or expired Kagi session token for Kagi Translate".to_string(),
+        )),
+        status if status.is_client_error() => {
+            let body = response.text().await.unwrap_or_else(|_| String::new());
+            Err(KagiError::Config(format!(
+                "Kagi Translate {surface} request rejected: HTTP {status}{}",
+                format_client_error_suffix(&body)
+            )))
+        }
+        status if status.is_server_error() => Err(KagiError::Network(format!(
+            "Kagi Translate {surface} server error: HTTP {status}"
+        ))),
+        status => Err(KagiError::Network(format!(
+            "unexpected Kagi Translate {surface} response status: HTTP {status}"
+        ))),
+    }
+}
+
 fn build_client() -> Result<Client, KagiError> {
     Client::builder()
         .user_agent(USER_AGENT)
@@ -901,14 +1662,17 @@ pub struct KagiEnvelope<T> {
 #[cfg(test)]
 mod tests {
     use super::{
-        ApiErrorBody, KagiEnvelope, normalize_subscriber_summary_input,
-        normalize_subscriber_summary_length, normalize_subscriber_summary_type,
-        parse_assistant_prompt_stream, parse_subscriber_summarize_stream, resolve_news_category,
+        ApiErrorBody, KagiEnvelope, build_translate_payload, normalize_aux_quality,
+        normalize_subscriber_summary_input, normalize_subscriber_summary_length,
+        normalize_subscriber_summary_type, parse_assistant_prompt_stream,
+        parse_subscriber_summarize_stream, parse_translate_detect_value, resolve_news_category,
     };
     use crate::types::SubscriberSummarizeRequest;
     use crate::types::{
         FastGptAnswer, NewsBatchCategory, NewsCategoryMetadata, Reference, Summarization,
+        TranslateCommandRequest,
     };
+    use serde_json::{Value, json};
 
     #[test]
     fn parses_summarize_envelope() {
@@ -1121,4 +1885,87 @@ mod tests {
         assert_eq!(parsed.thread.id, "thread-1");
         assert_eq!(parsed.message.markdown.as_deref(), Some("Hi"));
     }
+
+    #[test]
+    fn parses_translate_detect_from_object_or_array() {
+        let object = json!({
+            "iso": "fr",
+            "label": "French",
+            "isUncertain": false,
+            "isMixed": false
+        });
+        let array = json!([
+            {
+                "iso": "fr",
+                "label": "French",
+                "isUncertain": false,
+                "isMixed": false
+            }
+        ]);
+
+        let parsed_object = parse_translate_detect_value(object).expect("object should parse");
+        let parsed_array = parse_translate_detect_value(array).expect("array should parse");
+
+        assert_eq!(parsed_object.iso, "fr");
+        assert_eq!(parsed_array.label, "French");
+    }
+
+    #[test]
+    fn builds_translate_payload_with_optional_fields() {
+        let request = TranslateCommandRequest {
+            text: "Bonjour".to_string(),
+            from: "auto".to_string(),
+            to: "en".to_string(),
+            quality: Some("best".to_string()),
+            model: Some("kagi".to_string()),
+            prediction: Some("Hello".to_string()),
+            predicted_language: Some("fr".to_string()),
+            formality: Some("formal".to_string()),
+            speaker_gender: Some("female".to_string()),
+            addressee_gender: Some("male".to_string()),
+            language_complexity: Some("simple".to_string()),
+            translation_style: Some("natural".to_string()),
+            context: Some("Office email".to_string()),
+            dictionary_language: Some("en".to_string()),
+            time_format: Some("24h".to_string()),
+            use_definition_context: Some(true),
+            enable_language_features: Some(true),
+            preserve_formatting: Some(true),
+            context_memory: Some(vec![json!({"kind": "glossary"})]),
+            fetch_alternatives: true,
+            fetch_word_insights: true,
+            fetch_suggestions: true,
+            fetch_alignments: true,
+        };
+
+        let payload = build_translate_payload(&request, "translate-session", "fr");
+        let object = payload.as_object().expect("payload should be object");
+
+        assert_eq!(object.get("from"), Some(&Value::String("fr".to_string())));
+        assert_eq!(
+            object.get("translation_style"),
+            Some(&Value::String("natural".to_string()))
+        );
+        assert_eq!(
+            object.get("context_memory"),
+            Some(&Value::Array(vec![json!({"kind": "glossary"})]))
+        );
+        assert_eq!(
+            object.get("session_token"),
+            Some(&Value::String("translate-session".to_string()))
+        );
+    }
+
+    #[test]
+    fn normalizes_aux_quality_values() {
+        assert_eq!(normalize_aux_quality(Some("best")).as_deref(), Some("best"));
+        assert_eq!(
+            normalize_aux_quality(Some("deep_contextual")).as_deref(),
+            Some("best")
+        );
+        assert_eq!(
+            normalize_aux_quality(Some("standard")).as_deref(),
+            Some("standard")
+        );
+    }
 }
diff --git a/src/auth.rs b/src/auth.rs
index 6809cd6..b6089b7 100644
--- a/src/auth.rs
+++ b/src/auth.rs
@@ -183,11 +183,12 @@ pub fn load_credential_inventory() -> Result<CredentialInventory, KagiError> {
         source: CredentialSource::Env,
         value,
     });
-    let env_session = read_env_credential(SESSION_TOKEN_ENV).map(|value| Credential {
-        kind: CredentialKind::SessionToken,
-        source: CredentialSource::Env,
-        value,
-    });
+    let env_session = normalize_optional_session_token(read_env_credential(SESSION_TOKEN_ENV))?
+        .map(|value| Credential {
+            kind: CredentialKind::SessionToken,
+            source: CredentialSource::Env,
+            value,
+        });
 
     let config_api = config
         .auth
@@ -201,17 +202,19 @@ pub fn load_credential_inventory() -> Result<CredentialInventory, KagiError> {
             value,
         });
 
-    let config_session = config
-        .auth
-        .as_ref()
-        .and_then(|auth| auth.session_token.as_ref())
-        .map(|value| value.trim().to_string())
-        .filter(|value| !value.is_empty())
-        .map(|value| Credential {
-            kind: CredentialKind::SessionToken,
-            source: CredentialSource::Config,
-            value,
-        });
+    let config_session = normalize_optional_session_token(
+        config
+            .auth
+            .as_ref()
+            .and_then(|auth| auth.session_token.as_ref())
+            .map(|value| value.trim().to_string())
+            .filter(|value| !value.is_empty()),
+    )?
+    .map(|value| Credential {
+        kind: CredentialKind::SessionToken,
+        source: CredentialSource::Config,
+        value,
+    });
 
     Ok(CredentialInventory {
         api_token: env_api.or(config_api),
@@ -280,7 +283,7 @@ pub fn save_credentials(
     }
 
     if let Some(session_input) = session_input {
-        let normalized = normalize_session_token_input(session_input)?;
+        let normalized = normalize_session_token(session_input)?;
         auth.session_token = Some(normalized);
     }
 
@@ -300,7 +303,13 @@ pub fn save_credentials(
     load_credential_inventory()
 }
 
-fn normalize_session_token_input(input: &str) -> Result<String, KagiError> {
+fn normalize_optional_session_token(input: Option<String>) -> Result<Option<String>, KagiError> {
+    input
+        .map(|value| normalize_session_token(&value))
+        .transpose()
+}
+
+pub fn normalize_session_token(input: &str) -> Result<String, KagiError> {
     let trimmed = input.trim();
     if trimmed.is_empty() {
         return Err(KagiError::Config(
@@ -572,22 +581,31 @@ mod tests {
 
     #[test]
     fn extracts_token_from_session_link_url() {
-        let token =
-            normalize_session_token_input("https://kagi.com/search?token=abc123.def456&foo=bar")
-                .expect("session link parses");
+        let token = normalize_session_token("https://kagi.com/search?token=abc123.def456&foo=bar")
+            .expect("session link parses");
         assert_eq!(token, "abc123.def456");
     }
 
     #[test]
     fn keeps_raw_session_token_input() {
-        let token = normalize_session_token_input("abc123.def456").expect("raw token accepted");
+        let token = normalize_session_token("abc123.def456").expect("raw token accepted");
         assert_eq!(token, "abc123.def456");
     }
 
     #[test]
     fn rejects_session_link_without_token_param() {
-        let error = normalize_session_token_input("https://kagi.com/search?q=test")
+        let error = normalize_session_token("https://kagi.com/search?q=test")
             .expect_err("missing token param should fail");
         assert!(error.to_string().contains("token="));
     }
+
+    #[test]
+    fn normalizes_session_link_from_environment_style_input() {
+        let normalized = normalize_optional_session_token(Some(
+            "https://kagi.com/search?token=env-session-token".to_string(),
+        ))
+        .expect("session token should normalize");
+
+        assert_eq!(normalized.as_deref(), Some("env-session-token"));
+    }
 }
diff --git a/src/cli.rs b/src/cli.rs
index 5b86e4f..af01ad5 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -81,6 +81,8 @@ pub enum Commands {
     News(NewsArgs),
     /// Prompt Kagi Assistant with subscriber session-token auth
     Assistant(AssistantArgs),
+    /// Translate text through Kagi Translate using session-token auth
+    Translate(TranslateArgs),
     /// Answer a query with Kagi's FastGPT API
     Fastgpt(FastGptArgs),
     /// Query Kagi's enrichment indexes
@@ -274,6 +276,101 @@ pub struct AssistantArgs {
     pub thread_id: Option<String>,
 }
 
+#[derive(Debug, Args)]
+pub struct TranslateArgs {
+    /// Text to translate
+    #[arg(value_name = "TEXT")]
+    pub text: String,
+
+    /// Source language code (default: auto)
+    #[arg(long, value_name = "LANG", default_value = "auto")]
+    pub from: String,
+
+    /// Target language code (default: en)
+    #[arg(long, value_name = "LANG", default_value = "en")]
+    pub to: String,
+
+    /// Translation quality preference
+    #[arg(long, value_name = "QUALITY")]
+    pub quality: Option<String>,
+
+    /// Translation model override
+    #[arg(long, value_name = "MODEL")]
+    pub model: Option<String>,
+
+    /// Prediction text to bias the translation
+    #[arg(long, value_name = "TEXT")]
+    pub prediction: Option<String>,
+
+    /// Predicted source language code
+    #[arg(long, value_name = "LANG")]
+    pub predicted_language: Option<String>,
+
+    /// Formality setting
+    #[arg(long, value_name = "LEVEL")]
+    pub formality: Option<String>,
+
+    /// Speaker gender hint
+    #[arg(long, value_name = "GENDER")]
+    pub speaker_gender: Option<String>,
+
+    /// Addressee gender hint
+    #[arg(long, value_name = "GENDER")]
+    pub addressee_gender: Option<String>,
+
+    /// Language complexity setting
+    #[arg(long, value_name = "LEVEL")]
+    pub language_complexity: Option<String>,
+
+    /// Translation style setting
+    #[arg(long, value_name = "STYLE")]
+    pub translation_style: Option<String>,
+
+    /// Extra translation context
+    #[arg(long, value_name = "TEXT")]
+    pub context: Option<String>,
+
+    /// Dictionary language override
+    #[arg(long, value_name = "LANG")]
+    pub dictionary_language: Option<String>,
+
+    /// Time formatting style
+    #[arg(long, value_name = "FORMAT")]
+    pub time_format: Option<String>,
+
+    /// Toggle definition-aware translation behavior
+    #[arg(long)]
+    pub use_definition_context: Option<bool>,
+
+    /// Toggle language-feature enrichment
+    #[arg(long)]
+    pub enable_language_features: Option<bool>,
+
+    /// Preserve source formatting when possible
+    #[arg(long)]
+    pub preserve_formatting: Option<bool>,
+
+    /// Raw JSON array passed through as context_memory
+    #[arg(long, value_name = "JSON")]
+    pub context_memory_json: Option<String>,
+
+    /// Skip the alternative translations call
+    #[arg(long)]
+    pub no_alternatives: bool,
+
+    /// Skip the word insights call
+    #[arg(long)]
+    pub no_word_insights: bool,
+
+    /// Skip the translation suggestions call
+    #[arg(long)]
+    pub no_suggestions: bool,
+
+    /// Skip the text alignments call
+    #[arg(long)]
+    pub no_alignments: bool,
+}
+
 #[derive(Debug, Args)]
 pub struct EnrichCommand {
     #[command(subcommand)]
diff --git a/src/main.rs b/src/main.rs
index ce19788..9dd7552 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -12,18 +12,21 @@ use clap_complete::{generate, shells};
 use crate::api::{
     execute_assistant_prompt, execute_enrich_news, execute_enrich_web, execute_fastgpt,
     execute_news, execute_news_categories, execute_news_chaos, execute_smallweb,
-    execute_subscriber_summarize, execute_summarize,
+    execute_subscriber_summarize, execute_summarize, execute_translate,
 };
 use crate::auth::{
     Credential, CredentialKind, SearchCredentials, format_status, load_credential_inventory,
     save_credentials,
 };
-use crate::cli::{AuthSetArgs, AuthSubcommand, Cli, Commands, CompletionShell, EnrichSubcommand};
+use crate::cli::{
+    AuthSetArgs, AuthSubcommand, Cli, Commands, CompletionShell, EnrichSubcommand, TranslateArgs,
+};
 use crate::error::KagiError;
 use crate::types::{
     AssistantPromptRequest, FastGptRequest, SearchResponse, SubscriberSummarizeRequest,
-    SummarizeRequest,
+    SummarizeRequest, TranslateCommandRequest,
 };
+use serde_json::Value;
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 use tokio::sync::Semaphore;
@@ -139,6 +142,12 @@ async fn run() -> Result<(), KagiError> {
             let response = execute_assistant_prompt(&request, &token).await?;
             print_json(&response)
         }
+        Commands::Translate(args) => {
+            let token = resolve_session_token()?;
+            let request = build_translate_request(args)?;
+            let response = execute_translate(&request, &token).await?;
+            print_json(&response)
+        }
         Commands::Fastgpt(args) => {
             let request = FastGptRequest {
                 query: args.query,
@@ -285,6 +294,59 @@ fn resolve_session_token() -> Result<String, KagiError> {
         })
 }
 
+fn build_translate_request(args: TranslateArgs) -> Result<TranslateCommandRequest, KagiError> {
+    Ok(TranslateCommandRequest {
+        text: args.text.trim().to_string(),
+        from: args.from.trim().to_string(),
+        to: args.to.trim().to_string(),
+        quality: normalize_optional_string(args.quality),
+        model: normalize_optional_string(args.model),
+        prediction: normalize_optional_string(args.prediction),
+        predicted_language: normalize_optional_string(args.predicted_language),
+        formality: normalize_optional_string(args.formality),
+        speaker_gender: normalize_optional_string(args.speaker_gender),
+        addressee_gender: normalize_optional_string(args.addressee_gender),
+        language_complexity: normalize_optional_string(args.language_complexity),
+        translation_style: normalize_optional_string(args.translation_style),
+        context: normalize_optional_string(args.context),
+        dictionary_language: normalize_optional_string(args.dictionary_language),
+        time_format: normalize_optional_string(args.time_format),
+        use_definition_context: args.use_definition_context,
+        enable_language_features: args.enable_language_features,
+        preserve_formatting: args.preserve_formatting,
+        context_memory: parse_context_memory_json(args.context_memory_json.as_deref())?,
+        fetch_alternatives: !args.no_alternatives,
+        fetch_word_insights: !args.no_word_insights,
+        fetch_suggestions: !args.no_suggestions,
+        fetch_alignments: !args.no_alignments,
+    })
+}
+
+fn normalize_optional_string(value: Option<String>) -> Option<String> {
+    value
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
+
+fn parse_context_memory_json(raw: Option<&str>) -> Result<Option<Vec<Value>>, KagiError> {
+    let Some(raw) = raw.map(str::trim).filter(|value| !value.is_empty()) else {
+        return Ok(None);
+    };
+
+    let parsed: Value = serde_json::from_str(raw).map_err(|error| {
+        KagiError::Config(format!(
+            "--context-memory-json must be valid JSON; parse failed: {error}"
+        ))
+    })?;
+
+    match parsed {
+        Value::Array(values) => Ok(Some(values)),
+        _ => Err(KagiError::Config(
+            "--context-memory-json must be a JSON array".to_string(),
+        )),
+    }
+}
+
 fn print_json<T: serde::Serialize>(value: &T) -> Result<(), KagiError> {
     let output = serde_json::to_string_pretty(value)
         .map_err(|error| KagiError::Parse(format!("failed to serialize JSON output: {error}")))?;
@@ -579,10 +641,11 @@ async fn run_batch_search(
 mod tests {
     use super::{
         RateLimiter, format_csv_response, format_markdown_response, format_pretty_response,
-        should_fallback_to_session,
+        parse_context_memory_json, should_fallback_to_session,
     };
     use crate::error::KagiError;
     use crate::types::{SearchResponse, SearchResult};
+    use serde_json::json;
     use std::sync::Arc;
     use std::time::{Duration, Instant};
 
@@ -801,4 +864,23 @@ mod tests {
             "request to Kagi timed out".to_string(),
         )));
     }
+
+    #[test]
+    fn parses_context_memory_array_json() {
+        let parsed = parse_context_memory_json(Some(r#"[{"kind":"glossary","value":"hello"}]"#))
+            .expect("context memory should parse");
+
+        assert_eq!(
+            parsed,
+            Some(vec![json!({"kind": "glossary", "value": "hello"})])
+        );
+    }
+
+    #[test]
+    fn rejects_non_array_context_memory_json() {
+        let error = parse_context_memory_json(Some(r#"{"kind":"glossary"}"#))
+            .expect_err("object context memory should fail");
+
+        assert!(error.to_string().contains("JSON array"));
+    }
 }
diff --git a/src/types.rs b/src/types.rs
index c9b39e0..5924ba3 100644
--- a/src/types.rs
+++ b/src/types.rs
@@ -320,3 +320,180 @@ pub struct EnrichResponse {
 pub struct SmallWebFeed {
     pub xml: String,
 }
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct TranslateCommandRequest {
+    pub text: String,
+    pub from: String,
+    pub to: String,
+    pub quality: Option<String>,
+    pub model: Option<String>,
+    pub prediction: Option<String>,
+    pub predicted_language: Option<String>,
+    pub formality: Option<String>,
+    pub speaker_gender: Option<String>,
+    pub addressee_gender: Option<String>,
+    pub language_complexity: Option<String>,
+    pub translation_style: Option<String>,
+    pub context: Option<String>,
+    pub dictionary_language: Option<String>,
+    pub time_format: Option<String>,
+    pub use_definition_context: Option<bool>,
+    pub enable_language_features: Option<bool>,
+    pub preserve_formatting: Option<bool>,
+    pub context_memory: Option<Vec<Value>>,
+    pub fetch_alternatives: bool,
+    pub fetch_word_insights: bool,
+    pub fetch_suggestions: bool,
+    pub fetch_alignments: bool,
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
+pub struct TranslateOptionState {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub formality: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub speaker_gender: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub addressee_gender: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub language_complexity: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub style: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub context: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct TranslateBootstrapMetadata {
+    pub method: String,
+    pub authenticated: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct TranslateWarning {
+    pub section: String,
+    pub message: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct TranslateDetectedLanguageAlternative {
+    pub iso: String,
+    pub label: String,
+    #[serde(default, rename = "isUncertain")]
+    pub is_uncertain: bool,
+    #[serde(default, rename = "isMixed")]
+    pub is_mixed: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct TranslateDetectedLanguage {
+    pub iso: String,
+    pub label: String,
+    #[serde(default, rename = "isUncertain")]
+    pub is_uncertain: bool,
+    #[serde(default, rename = "isMixed")]
+    pub is_mixed: bool,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub alternatives: Vec<TranslateDetectedLanguageAlternative>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TranslateTextResponse {
+    pub translation: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub detected_language: Option<TranslateDetectedLanguage>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub definition: Option<Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct AlternativeTranslationElement {
+    pub translation: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub explanation: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct AlternativeTranslationsResponse {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub original_description: Option<String>,
+    #[serde(default)]
+    pub elements: Vec<AlternativeTranslationElement>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TextAlignmentsResponse {
+    #[serde(default)]
+    pub source_blocks: Vec<Value>,
+    #[serde(default)]
+    pub target_blocks: Vec<Value>,
+    #[serde(default)]
+    pub source_roles: Vec<Value>,
+    #[serde(default)]
+    pub target_roles: Vec<Value>,
+    #[serde(default)]
+    pub alignments: Vec<Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TranslationSuggestion {
+    pub id: String,
+    pub label: String,
+    pub description: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub category: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub icon: Option<String>,
+    #[serde(default)]
+    pub steps: Vec<Value>,
+    #[serde(default, rename = "exclusiveWith")]
+    pub exclusive_with: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TranslationSuggestionsResponse {
+    #[serde(default)]
+    pub suggestions: Vec<TranslationSuggestion>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct WordInsightVariation {
+    pub text: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub explanation: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct WordInsight {
+    pub id: String,
+    pub original_text: String,
+    pub r#type: String,
+    #[serde(default)]
+    pub variations: Vec<WordInsightVariation>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct WordInsightsResponse {
+    #[serde(default)]
+    pub insights: Vec<WordInsight>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub marked_translation: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct TranslateResponse {
+    pub bootstrap: TranslateBootstrapMetadata,
+    pub detected_language: TranslateDetectedLanguage,
+    pub translation: TranslateTextResponse,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub alternatives: Option<AlternativeTranslationsResponse>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub text_alignments: Option<TextAlignmentsResponse>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub translation_suggestions: Option<TranslationSuggestionsResponse>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub word_insights: Option<WordInsightsResponse>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub warnings: Vec<TranslateWarning>,
+}

From 981751cd6f06dae277443c22782375dea2658a61 Mon Sep 17 00:00:00 2001
From: Microck <contact@micr.dev>
Date: Wed, 18 Mar 2026 18:38:51 +0000
Subject: [PATCH 2/7] docs(translate): add demo assets and usage guidance

---
 README.md                      |  12 +++++++++++-
 docs/commands/translate.mdx    |   6 +++++-
 docs/demo-assets/translate.gif | Bin 0 -> 9556 bytes
 docs/demos.md                  |   6 +++++-
 docs/guides/quickstart.mdx     |   7 +++++++
 docs/project/demos.mdx         |   5 +++++
 images/demos/translate.gif     | Bin 0 -> 9556 bytes
 project/demos.mdx              |   5 +++++
 scripts/demo-assistant.sh      |   2 ++
 scripts/demo-news.sh           |   2 ++
 scripts/demo-search.sh         |   2 ++
 scripts/demo-summarize.sh      |   2 ++
 scripts/demo-translate.sh      |  27 +++++++++++++++++++++++++++
 13 files changed, 73 insertions(+), 3 deletions(-)
 create mode 100644 docs/demo-assets/translate.gif
 create mode 100644 images/demos/translate.gif
 create mode 100755 scripts/demo-translate.sh

diff --git a/README.md b/README.md
index 243e1ac..34ed3ab 100644
--- a/README.md
+++ b/README.md
@@ -208,6 +208,14 @@ translate text and keep all text-mode extras:
 kagi translate "Bonjour tout le monde"
 ```
 
+plain `kagi translate "..."` means `--from auto --to en`.
+
+translate to a specific target language:
+
+```bash
+kagi translate "Bonjour tout le monde" --to ja
+```
+
 translate only the core text result:
 
 ```bash
@@ -241,7 +249,9 @@ kagi enrich news "browser privacy"
 
 ## what it looks like
 
-if you want a quick feel for the cli before installing it, this is the kind of output you get from the subscriber summarizer, assistant, and public news feed:
+if you want a quick feel for the cli before installing it, this is the kind of output you get from search, translate, the subscriber summarizer, assistant, and public news feed:
+
+![translate demo](images/demos/translate.gif)
 
 ![summarize demo](images/demos/summarize.gif)
 
diff --git a/docs/commands/translate.mdx b/docs/commands/translate.mdx
index 85ec45d..fb50210 100644
--- a/docs/commands/translate.mdx
+++ b/docs/commands/translate.mdx
@@ -7,6 +7,8 @@ description: "Complete reference for *kagi* translate command - translate text t
 
 Translate text through Kagi Translate and return one JSON envelope with the core translation plus the auxiliary text-mode sections.
 
+![Translate demo](/images/demos/translate.gif)
+
 ## Synopsis
 
 ```bash
@@ -28,6 +30,8 @@ By default the command fetches:
 
 If an auxiliary section fails, the core translation still succeeds and the failure is recorded in `warnings`.
 
+Plain `kagi translate "..."` means `--from auto --to en`. The CLI detects the source language first, then translates to English unless you pass `--to`.
+
 ## Authentication
 
 **Required:** `KAGI_SESSION_TOKEN`
@@ -189,7 +193,7 @@ Skip the text alignments call.
 
 ## Examples
 
-### Basic Translation
+### Basic Translation to English
 
 ```bash
 kagi translate "Bonjour tout le monde"
diff --git a/docs/demo-assets/translate.gif b/docs/demo-assets/translate.gif
new file mode 100644
index 0000000000000000000000000000000000000000..6495486e7751e3c8777fc722587e347899ff04ed
GIT binary patch
literal 9556
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

literal 0
HcmV?d00001

diff --git a/docs/demos.md b/docs/demos.md
index d02963e..3e29bdd 100644
--- a/docs/demos.md
+++ b/docs/demos.md
@@ -10,6 +10,7 @@ The demo scripts build the local debug binary, expose it as `kagi` through `/tmp
 - `docs/demo-assets/summarize.gif`
 - `docs/demo-assets/news.gif`
 - `docs/demo-assets/assistant.gif`
+- `docs/demo-assets/translate.gif`
 
 ## Regenerate
 
@@ -21,9 +22,10 @@ The current demo commands are:
 - `kagi summarize --subscriber --url https://mullvad.net/en/browser | jq -M ...`
 - `kagi news --category tech --limit 1 | jq -M ...`
 - `kagi assistant "plan a private obsidian workflow for cafe work. give me 3 setup tips and a short checklist." | jq -M ...`
+- `kagi translate "Bonjour tout le monde" --to ja | jq -M ...`
 
 ```bash
-chmod +x scripts/demo-search.sh scripts/demo-summarize.sh scripts/demo-news.sh scripts/demo-assistant.sh
+chmod +x scripts/demo-search.sh scripts/demo-summarize.sh scripts/demo-news.sh scripts/demo-assistant.sh scripts/demo-translate.sh
 
 mkdir -p docs/demo-assets /tmp/kagi-demos
 
@@ -34,11 +36,13 @@ KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-search.sh -q -i 0.2 --c
 KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-summarize.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/summarize.cast
 asciinema rec -c ./scripts/demo-news.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/news.cast
 KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-assistant.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/assistant.cast
+KAGI_SESSION_TOKEN='...' asciinema rec -c ./scripts/demo-translate.sh -q -i 0.2 --cols 92 --rows 22 /tmp/kagi-demos/translate.cast
 
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/search.cast docs/demo-assets/search.gif
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/summarize.cast docs/demo-assets/summarize.gif
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/news.cast docs/demo-assets/news.gif
 agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/assistant.cast docs/demo-assets/assistant.gif
+agg --theme asciinema --font-size 14 --idle-time-limit 2 --last-frame-duration 4 /tmp/kagi-demos/translate.cast docs/demo-assets/translate.gif
 ```
 
 If `agg --version` does not print `asciinema gif generator`, your `PATH` is resolving a different package. Use the official binary explicitly, for example `~/.cargo/bin/agg`.
diff --git a/docs/guides/quickstart.mdx b/docs/guides/quickstart.mdx
index 18b8719..9a59bc0 100644
--- a/docs/guides/quickstart.mdx
+++ b/docs/guides/quickstart.mdx
@@ -174,6 +174,9 @@ kagi search --lens 2 "developer documentation"
 # Test Assistant
 kagi assistant "What are the key features of Rust?"
 
+# Test Translate
+kagi translate "Bonjour tout le monde" --to ja
+
 # Test subscriber Summarizer
 kagi summarize --subscriber --url https://www.rust-lang.org --summary-type keypoints --length digest
 ```
@@ -182,6 +185,10 @@ kagi summarize --subscriber --url https://www.rust-lang.org --summary-type keypo
 
 ![Assistant command demo](/images/demos/assistant.gif)
 
+**Translate Demo:**
+
+![Translate command demo](/images/demos/translate.gif)
+
 **Subscriber Summarize Demo:**
 
 ![Summarize command demo](/images/demos/summarize.gif)
diff --git a/docs/project/demos.mdx b/docs/project/demos.mdx
index 2812cff..eb91cde 100644
--- a/docs/project/demos.mdx
+++ b/docs/project/demos.mdx
@@ -11,6 +11,7 @@ The docs site ships with recorded terminal GIFs from the repo:
 - subscriber summarize
 - news
 - assistant
+- translate
 
 ## Preview
 
@@ -30,6 +31,10 @@ The docs site ships with recorded terminal GIFs from the repo:
 
 ![Assistant demo](/images/demos/assistant.gif)
 
+### Translate
+
+![Translate demo](/images/demos/translate.gif)
+
 ## Regenerate
 
 Subscriber demos require `KAGI_SESSION_TOKEN`.
diff --git a/images/demos/translate.gif b/images/demos/translate.gif
new file mode 100644
index 0000000000000000000000000000000000000000..6495486e7751e3c8777fc722587e347899ff04ed
GIT binary patch
literal 9556
zcmc(ic|27A|LD&w7`srGEQ85TV@X6BBax*hJIPY^Y@ra<*q6xIcgB)^8T+n5mQZBN
znhDuSc8a+^-{1W$_uk)M_x^FuKkxH?KhEpFbDq!hRKI&iUcu@jqyvNn{^!L<roE@8
zucxYlQInQLLO|!od}ma44z`jWPaOchV<<(``H}cPPyaI)sE*NQW?>x|7`VX9LQl`Y
zbb*<ghK7#r{FZ^1mX49>!ugow`S`ytP%;ys8_+7h{<)cKDg4gbA=AFN+-bedO?=SP
zdCt51m!XvgB-2epoHM#N&;66rjVufs=t7xk#YE|g{>_&k`r+Q%l4*l0H7`HAG|z1}
z_}#0R{&m#ydhpjDGS)vJFeo@AG%P&gZDiEDXk1KeTzo=eQgTYF0XQQwGc7wOH}Abb
zR$+c|NoiS3VODunbxo}|0bkeD+|p{+kkQuB`LRoh2=4CdANX8A{PJ~pq^o!I+r(t)
z_|)w8xwsk9!s5?>`K8sh^=B&^zqWsyZ|&?K9BS?z{rP(;dvXS*;X0yYYY&96I0A))
z?9P{Tyqf98lKfq7*<~DOdMk5#qTyuK2(G(Td7t8h^@`0tRlV;|LO$tBzgwOEIZfVU
zZRS&T!C)3DkcL~crtoX7Mx5xQzM7(u0!*%EhGuQ?Sc!49<7{7T$+rs2&IoR;y3)yN
z`;p>D{dHy2^==D&8Cvz_v(4VSYqS0J6>}f35LzDX2EvcdFcvZMfriS39-M$yrgmf1
z&;DeYr{4z}tCt7ys&9F8nrc=@3iV3NKR4B`e<M8U&(vwI+njFjSpWXHx&GH2F_4z`
zUQ5I8h2A(Zi!UvWyURnlT3Pp6oA%cys-Mn%X>C6IMe2OZd%vyacz0!_#A2|m_0Qq<
zLVwo%4{fJ^j&|4Q20wftlL1O$5*Z7<WKZ&k2^Nw9=;T&NflPOVe+01_+W!b<w=Mh;
z!u4Y1M<_f*cs>k~Xg?n=oL@K}AzrsK{}$OTybvinZod#Ezf`#JPU&D}AsR&~vWUBV
z$zd@@L$GKuR$Fd$F%EM_<Y&CTp~KGvW80#iiDoZWe<oRmh%6;rCps*p*yk55r8?EE
zE~UA3i!7&mjyo)8crO(#XZjtiE@xpWMOW}ammF8J!vu?0aw6r{R&sH7L|60T4INkC
zC)*aU=BK|{TP?tch^`gpB|5GZoxe+K#iey?YbAtk(e=`ramV$thNa^5@|J_O^$H@T
z*aqR_rKcN}y@DkhRRePC8|3PtJ7SwPqlQm6YbR_=HtS|ytZ&wnLd3Qj789RtHLm2B
zY&C7vt#37NcZ>aM*&BcQtMzE9<X79@gY{n@04niqB9zT(yB#J}y4^u{ePg?mNnQN+
zM^+=J-(Bo>rN6tmyf%LKz(d7%dJ#!ZJD-FLN_YCi>o<1#kv-zO1G3+oc0bE6m+pR1
zI^5VDL{UlX4c%sQ-utQ{RJJ#)eSLFp1fwpoKdNu!ygz1aSGGTH=C!&1%`#NtV8S}d
z`C!t%pzL7Esebcd+O0?8aK`hS^Wm)ba@pZ`zr)SLIV_dr5h;kx<>*J4Q2Eh(<n^ti
z1)Tc3D0XvRKn|es&Om{n|DuThKNNuhG{8Pc2nhZUim0H`nVFfcZf@7)t`mtwV-u5*
zkkE{b%-Y&oQ86)JU%%M6I38YjQBe^}1#N9@Q(RoEqjT?xwY9d6j;pKNOJ83jW0U`i
zqH_rS8;$-?6#cJY`hVI{kS*cw1T6n|mihf66Y<;Xq747evZ2B~1BA}MvrLS+1M`@J
zRXG@>%><+Q0s><#li8E}7Ay4veO<tiN3SJefoyLCgXJMm*~pu07lmMKFH{iJ7j48K
zU}fl2DX81M_c8%DD59Z(Ko%6rLgk^5qm!jnEZy?3O}r4VQhKvN;hk)cvP&`*QJJ5a
zik5`{l4!yd7UW9}UF#|roC4@+BSe2HkR&$sehGD;yG%bBff<+qR)*gSpmC%ylGF}y
z60f=GW+~QQ4WT{)ym2U^Kc&64W#mV+KiH8+9fUy=EhJtu&5%*-&nerhp+dq<CMXa^
zJqv@x9kV<X0F4%+Oa2I`&Xl-Qgn)?KrI>y@hJcrm`d0pfMgr=5_Lw4nEf9xM`rXx-
zlJH`q`>a!aBSIMVA>lkT%l^oK_z{LkPGnN-9qOBGVb-Dm<Z8s#E8yfqh<^YDRbM82
z;6YakPKZ5^6(!T%%9bR+M~G-Ip$Ea>fCiSt`wj@?VcN)JhzG%tI;>3cd|m<6bnMy~
z$BtShS0Q;8E=(L+$AhYuT7yW6E2AWW*ojT-3fNg7Xj$^hX?qtH<t1;U>jm%jU>C&2
zkq=3zcIb+wPQ|+$!B^J-4LBg!GP*kpE~g`ylWEphLWvMC^HGF9z@EhA1u$4z$bprH
zP@(k1k63_N2?e?eov6p?dlnjh6>FeSCwhnasSgSWk9t|WcC)e}27+kdx^nUd0b@d}
zNYYTiRTy{%#As}+3NUJKvk39K*%R-IjgIi%`e@LbL3{nm^-P)v3_H|<GxBcvI@+&|
z@{$!ypP(J({Fq_TWO2ga?c!1gbc$yxX^DC*rr=@BU6BKHU}!4NKATn3q%hkyr87qe
zkJ;9cqS#Ib-a?a~&*N>Q<a@)JIhd9%u!4~esdJIxD_N3$hU?TZcQ^_ZA;6`C_cCEX
z_O$@MkE=2>QI~oJiZz$B%GyiSACqb9pv;B3GZ;4j%5IDUXMbsu5<-gHOVG{KyaxPy
zPepvdkli*To15dF$@H|`YAWra|FUjB7)dLRycodMv9l^bkBktwKE;JC5#84riz8k&
zc2{}y<L9%x?>x+JIK&x$V(qP14AS0tCiL-7VGr9od8$fj9BN3RZ#)F`stioG^1w>-
z?#lbvt=r2j-<7b~TfGUZYeAstMIxZD_t{0e_-I~wc%({c<pXBD#J$6<4|0$rY^>=9
zF<?X@0`Ukv?as%Hj+!68W0X{;DP{>CATCCI6et;=A!jIg*!%QFRZc0Ae*a~hw_M<I
znINxhk7f0kLg!8UJCuT00di8=bDfCVCp+#rsWav3*YDYd@YJ>yuVU`i?53c^zJ=~K
zt>(3anb*_d&RjINtAF*ar&0HxhCy>;Umhagf6tDne<yw6>DDbVMj|x-h$gT+;&N)*
z(KTR!6XILQ)IL3>20R2`assPBGIH_skcYH8C<-v~!7Fh~f4dowGPscV#}Ws?i0V>9
z*j|YE5aqa!4tRceAjRyl|G}#qIFLR9W(Ig?RXzfYz1RguNEQvs66D8@kKO5Prp+L+
zT(krLDJc*YI~+pgHbIx;=})mH6si~>&*(3VX1;@Er9tvD1jd2h`F!zVQ2;1C!*W(<
zSAk2G*jwgbJIO-h(bVOA*b6pcyaK-??$@Vq#lXD~AY(vEOqRRN6vz6I8fD{*kA-q!
z=%Lo1=+t)f=`8sDwJXuQohYohU`o*?%<W73CLz>xNUnBL2cRbX+21qvrXg3Z@`wY1
zCW!y-fINwVh47dTrEs@nl~$U82o=5$*Su`_Sbkw5&tNY`q;7zyH`dI8d?l-GK-mQ<
z3-V`=D?)l$IVDk&BBWGAu*N&XmzqcEtr2c?5yrv3T5zFjstM5@Wg84<c&)3;$uwK2
z`v84^u1-kar;8fQuSXZJfaKIK^QMb(!)E<Us*;96Zs=3d*3M203}ritpy{mT5sY-0
z+q9@dR2HMNy&s-qI5t(EQXpf6uD2&3zRuF#tPri@fk&A1?&Jw2s6p5xMlw_N3zXi2
zw2Xk!O9Lac(qo19lln&UZ|oP*>o}g_HOGog_lu2fLhEW0#>!vrmspmq88&i`SEcTk
z+HZCkLt@73n)b`wPTNgqnZ7km?U#E?d@<YY`_^_+TjKF*%z{d5qC-xW5TaB1n601U
zqx3-~E=ru4OKh^w^q>kiEoOVYfAWi=Ms+5AnLV4<<k!@L8b1jMN2C6!y5hQ8LX?E1
zirDnj)TQEz)-o5b%fmA}2ld3$0M|gRnR!jChHjm5cOk9mpEnL0RbZfhTuzNUuY~_7
zg8#<l=jJ}w`MJx_jeaigbC;hR{oL#Srt@=cpS%3r;{T@ebG4sa{9NbfB0u-~{|}eL
z;r~sS{LAJ4wM&KyJvINcOGt$Ot1d}P&&bTe|Eo*#3kr+=>5}paLghbQQdi&5_)nL#
zeIT~~(<R+Ky`TQ+k}rcp=Up;7Hh$hEQ`0l&T|)XXf8Hfa%PZ$yvaz{!-X%M`d;0;P
zqvPX)zo!K!z$rD?3N>Ci0LEenwuc7<05k%c)_JaA089nHH`DvuybTIFc+PcKdaxbD
zuSG64J6^KZOhi6Od=`HHyh|*$)$DO3E1h&ypkcc@+&?%F9VcoNI|yJSZzXAFhz8}~
zDK@TNA{5t_7;%_=h~R#Uo`X;_RKz|~G|ch`GfG!wh>er9n!F39qEhQChFcv^Y5ucI
zN(YGk1vK~IZn!QG_#y*4vf;0qN>IT)2fr6eIaWa<7tmCdejPIQ-NCd>4f3QQr%R>I
z+KDQ7Yy<=%d~_y_B6j_diJZIi0EP8f?)BeOe(+b`siU5HRIbvj%k%QAh2J4hhSvUX
z>G(lgm%p%+3(Nf$J!!8L0SbC{V>bd15nD|klxPB`weRKtnC)#<$kqaucoRr8ACU;A
zw!f1CBTF%nU{vW8?Y=@SN&dEUmdF4bCi{bA7`HT_;?l@X#KI_z@g`;hq=Gpp+X)rk
z@ppn7F+#lXI@&`RiA23-3`)emrn`5L2Ssq<cp>^cN&Jx8lnPlE5VH`hBdrn=3!yF*
zQUSAwH=?YG4~B>UB*+j2W~M_CBl+>+M1aEBni$JE)Ht8&EVnHPP$EdgH`Kj$9lp@N
z;ix=*CIT@xbvT)r&S>eF@n(~IdnJWB$WRdP5P@BZz4>)zI_nD4&>T%$u#dH`AdFB1
zWl(xym+32=giWD`5iOs2fYVm<UrJ)8N)KL{u#>@k5vcZ;wD5YYTFM<eEMOuECqAKq
zVK!sx!9$y{IWPvG;1`CA`iO|D1FiRM9%5?_!%rSP7sNt=Iyx7zj%M1xw<gijvWMwS
z0x+hG)}NVTu5|#04jU4;lO`EBE<Miuh95QrK*eR0L_@%Y0qIPtT~o9-cg0MVD^wN<
z4vR}n`Vq9gZ}!ajPH2g25q)gf>ZkQ0@#=n*th!JJ!k4akfN5wZ10cmJIz*c$l^T21
zM@^$ZPHdLEFS}|#zi?(jVA0-={ZX>+sBfY!d7g3@S$9^Jp#?8U{W1~k!>}zmRsD1J
zph+3-gPwf0F5&v-Qi1ldw@q5q1Q`lgus%-|R04kY3bLw8Q_H`71n#5NG7VTmXcMmj
zHG$@7kc&jc8LtUR=dIEgb}w%*CmxzgtY7y~p2=6?l{k64WS+S7l0u(pilX@R&q*d-
zYN0bEh68(&TKs9f6-J8Vv|1L!l~29D$33*x&svZM0+{e~CR?ih2TUXozeb|#h7Cyf
z*{@eX*c^?MLEusX+;fq||F}&qy{XJzvF!;6<n-cZm8BS{$21zu1;;{<A~a~&`A%84
zvCA7@00GY*{s2xKREP_fG$Te}H9$WIz^yMJD_S;q!~5q>ib>4Cn~>ZOm+s;9h4m-B
z7zhCGuuHInUp8!-0z#&Zg?q~SF%ab&#FmdD-^9zPP-q&V>puRzCdp1*C+!A6YNFMy
z!*%FH37zsMQWW%9cAg4+kMh|C%E^*k#8(`sz#48Sjl=3u;;@QfG}tpePuQ2lF`Dci
zeGO-oZI2ZMVTe|_kv1Z%ZndUzx`_<~?<KuH^_!pUBoXQIk)d}79zRAKJ>mC<hr3~4
z#cW@Xo=JCcg!ps9Wm3Be^UEU}BTtC$BGGVTT5O#Tr}lEn)$Jwe$d5WUg>ed`yckva
zcup2?+h}?|=7D=|scVhIYX^VnsK1!BPuhoaY&Z!?kBU?-@2Sh(tVuf?MgWw^6|Bka
z3<^JQapo|x9&{oH2$mP<T&7chys2r(R+3U>osGE$EgQBq-Tq>Y(9iCMe+HR{%J{sZ
zQH`8>2cCZ(qjnSSo%a~?M>(QLESApxM<Z*Kk{|#zUyQ0SF`6;O>*;gm%JqLNl6m>E
zU_3n^+<BRyJ%U9&ziLI+G;pmfmJ$$9zK|*I{Z^=}@0%d5_7ROGDm6m7;nl$>Bl!SE
zYL&*a3vD{OKR5<KH$%U*nO>rM(>j@>U0)L|iUO<gap+CzS2Unsl>0T~dS1Sq95=TD
zYn(1^N?KQRNS8sEs-oAwz|_jF0VP%3DzERLrkXW9C@8T+^JXakW;s&Z#GXU}cY~)t
zqJfavm`a_$O<`$olR(+xEYE9$6X{rol#?D$zA%>KOH@#EW`kV}G`xI2dboniFt8j6
z7+@g@9#9rS0+fl!VJhV)Pf5BzcvcA1J?jPnXfdFvP;8@=x(kbK42cU>Mfb-pRCs7z
zfmkxfT#W|ca+MKkzY{MuA9W$$RYuxrFK|vDb<2OLeCIX8n4&h)=+ht+ZD6K1z4*=N
zKJF{63r(Qpjh-CUao3m!OgHF!E>gSbfZ{B$*u4kD;s-99idO-DD&fO`bu`vj3kRar
zk9}`-;~X^vey9fVGZg_?i(OwDMxj6+Uv%B$x~d@bCj%E1CB0+Wmio5@jkn#&D9}*Q
zjfHpk4ja{xJh7q7H~WG$YR>mup|}tCKT#HSUARX-_Yj~ss5kF<eA&&eI?X>vhQgo1
zBiBM(v5!CHPL<XrU;em<>)Lh+@P`vN6U7pX$ZP%I8*8Z%2rQME&$lE4R9blVbpL9i
zQR1H|n|#%+DHt45sIu;C(LMU?CJFqlydD2H$eCq&9TeVVkRTy(kJ{7pW%tq~Fg#}b
zP$JD};h9(|bco1nR{Z_S_-wdKEtYjR?a2>H`9=yChpw}M$zhjw%3hfC7}b`Fyukf3
z9{khw_I^9nQ?D-XJ04TpOns3Nk@7up<p&~Im78qYHCnlxnZ2WnLRa&_<lCAx4_7Nt
z@Ucihl!&FhIr~8RzRBnQSG+oRPo)&2@6neq$b9~*zalPt&mUv#;3RQ<m6-Qlurnfi
zldd@Nq*M><F#7)QF}L*gF-xHRCq7C>tOgYh3&p(#liaRp*R#3^|1f_7VM^QZDwO}}
z;itCQJx%XA*Yeik*yn57*<RuO)-|KSlkw)WeL~N{HKXnHA(`xPC5^3ir#Wxht}`vY
zgSuN$fb2}%jQp#opobjfKb=tWH%M)UXWlQ!)z84xXY~O^pJDXg^FOx(B!;wqJpr*v
zqpnHM=TzJ#q)5)2fzvZjm^xkYg-^_(woS6ms_&&^ooj;OhthDHXXH^S&q*Wp>K?9W
zE5Lo{)mI}hJqn~)D<7c-dfUTMzNkJL2sa53WbEax-+8zVmb}OWm*2YsBLK%w>_>IQ
z_6@)jUf6MF9)l2`1vG-E)5$LW%1r~Od#q;V%wj6buBdMgl|RAIM0HBxz=)UthM!no
zI}1byAZ%+qSI;FaEfsBZdGj%{#zRO?Ln^A{Haq5}6jPvfGW%*3x9pL^*LK5NR!$c+
z3)+QOiGoJefv8lWtHHWjfkGgqcA=i6kSinHI<nvjYcRhtC+EnG!P}wTKV1(h!@de2
z);gq~GP`zlf>m>Zg6t)n-a9Mb2Ge6er%+2;(xdFJz(qF@8DIj@*Skp8b7kcKY$W5t
z!U%ph&QfnqL^WW823s6(ux;OA#)KSIDt`YRaIhaPvx2543Lpq*)_8%c2O{daDD97Y
z)<GBGHqWOfw2_`s2ph2_4Ft$g;^?ays~aCP1~u00hadqF@nHLv$RqDpU?$K`a`f2>
z__MV<Ssn*9!BP6)U@177MjYKFj^P-`)aX;n7gk8TqIoF>eL=4XFL@Xib0s^bkQk%2
z5`zH67QkZ>DY2rBvEq}llE<;gaJ^NwxGdpt*}Gx(k3+6EzFez|)9&?E=7>it#NRfF
zzvC0HkrJ=j7%%fe102l60K#Z1&<Kh!2`eO!^;a(oh%g$3CuCz1&V~}qkEv_WulA8v
z5^{--jfqZ^i7v;9ZX8Ma_(1nbd!y0l=MGO8iIF}IPpE<TR~*R!3dunx$ss<;VJXQG
zjmeRXtTi3F8{5fIDb$ue3<(M;IJcCa_>|;HSh@m3)?`YAn+A50K2IdIFeSCPF|~9u
zwfs1hz>!v^kXB=oR_Bw}kdoHanAS3x*5>f!bFlq~Ni8h;TIVONPhRPj@#%dcngf&R
zv3u!5Cg@>>j2yj;aTDo@lne_n|6xytErfrJGV|Lm&r^-eU>J8oSZ0o=#>R2xHb>Tu
zLe`#1)`3sfQ6rdog~DtYQu__Oko1B)_ygQzXDI_0m`lkD*!H_maQ(gl`7<tNOC9*o
z;gvMOkH!>6w+6jH1Lb~shh-|VFVv4O0?eI~?X!K)MEK1sclfCf@=?47V>i&o&nE!9
zxz@)g+n2+unyW7qmhwAie^_<=Ac{<-WojrviBXk+ri?AUz8#S3YacAI{pRp-HkB&&
zU06;qAxoT%BX#liDMaqF3>V!HB7KyntJ3LB_!~9Oe92JTJPi;f5$oqJ#PvdL@M6Jz
zDNvd<l6yC49VX*+;(P@ca9nLCA&>F9``#=9)=jP6Qmy!l*|TMYr(s0Mm9?l%u;6{d
zmD?+NewsF!d)&HEr|6iXmOult_Sj7+T#&#?;afMgi<Y2=8YbW(+4-7qq6R-Lfv3i?
zB=bgT^K)L-&O0^rl8<(|44+#(9w|w!1Wv!YK!*XF35bwr$tz0$B&ay|z{&F(_q?YX
zt%qocF6XSN!=L<XT^BgJLP|w3atFCerbbfwU<sp<D}#F`{$XVgi^|>%y`#1^7+5L>
zEnHrx;_jdX7y&aOI3ahcXbD_=26kgXytv6<CJ|grw@%;*1*bKDGuTT2Ul{#1M><q8
z$sP0=5pt)JCC6R=0v7ZLDwALhuoF3i)_J=OLJRCUm%F2>^+Bq-0SRMLEK_g6YByfT
zi$911NFHHb&#D#D1jtu?g>7I~eaYZ4Vf>Y+RgV^>H4wKMr}(nuxJHiv#!x<KPmB_4
z-A}8!b$?*VUaY2zrS>T5R_=R+981+H^qx0gh#pF<ukOo_I`OKcEm(ATEqHGw+@gd!
z5)x31;X+?-j2n8SSZM;oy08I-g-p2pu*N97<>dfA-(w(wlA`_7HF4D@!sX^F#para
z&2<l}bg3z}?rQGJf?Iu?Q;{(U99&`)A#REHH^S;|r?X(MAW=!&LQu`b%fxj`&J;-(
zh_E*`f2o?c?smGzVx=h18gm_LY})FGk7*5gD5Hh2dtS9W%B0!M|9&t2P$iOmNSO);
zdTITkOvRS`t&gA565t?3AecZ2AJZ3fuTz!k-wvo|#|Ki8-fp}FF}CQjGZEX;K%9Rg
zIB;Hwh_>;P1R-gk`!T>YxUdcluVdy*l{Pk9*491h$o7}`gU+p~mte&KV(uuBNCS^N
zk@Qr>J$}XR;9%iW5uQ$7o7`I>101`L#b}ux`d=v<vj<fCUT9Zm@M}}vw*yg{DYD0k
zK4{2fb+jNcUp)Xz3Iv&T*cjlKT;W%O4uiqqqGFtPeyD+jO(!yak(IwkSgXZ^t}2OO
znEEK4lG+e;J5B%N^AePBj-hZldwmcronP&VLDx87X=@~maS~a6+8+~W(^<|10i17K
zC1331xcRigCcW49ylnNkp1+N{<y{lo;u8P2GD}H4)-Z|>VKN#jQ4j-)(g>xdmGS%Q
zT<gct%Xwo#*R77O-xuFE(bG!WdtkNPdpQ>@(hEO9%h$HMSNMS=9>43N2+wO7XrT+*
z(+lp@{Op6jAJWpTu;Y)w1@!gzk5~=z%6JkeuGT#_%2tvbrD`fomQHU6X59JI1uJjT
zez~M*Rtq+}Au?$1CM2esJ6$O#_QX@&T^zL}auI1x1px)Uu$?xOQ6K9T84|WN1knf-
zX)W^;g<qZJb1HmRrN;5gY`R{;yk=!d*X`usi5mVCSV{>*de|DAEbw0<0AZ0|$&a^9
zoJW*h+vNnjfQw5WSY1nYO2b|&Jk`*7Jl6{1#yoW`4}MtDAVDsHEl6)E9?EY|>3RL#
z0gi49=gt7rD84ZpUK)%Q&kJ6+M?i_zST0IBzHmbR>&?=_fOp)iHKT%THz$)bCR1A{
z(`P3$oh6u=@mXcef%BhoTba%LrXVp>#hZ+!vr~V!rwET2t8Py3Vy5f385=UDf59`O
z`lh$xne((WyF*Mji;R6WXMUmTM@ozOPG^R=XNPajjy{?le>FSNO8IBCVnILWc)0Mw
zNwXNP`8LU{DM|B7%&Zb2TW%=E{Z+Q#<;slWEOIL3@u$n*%f8FnV6xS{$O^jm+Z2WO
zox#A_+}WRDfda`z?$!hEr}M9f$QrD&SA=?88DH$&NtD=MiMKF*3ICsBvJjc)3tTH`
zxabqCG%I(A9!N5X%Lt(x8KOI)k!yoCkW}mDmXT65;$j)$1?i(IC#3Gd<cbdRs&?mD
zJ05CZ;q&(C=a6(=K|4iF2*L7%V;)@Z=f4BlkVG0)^XJVg(E)Vn(gC*JJ5|C)HQWn6
z1{nD^1j67@>V2E;Wg391F95+XRBFS(OG9dHe(c+Px+shSC4B`JY%k!&6rY}dI7+cA
z&$@ad^EP(;m0{t#n@hFB0&WkanDn?`x|>;_fU&VNKgCxRNdOr%{D3p}+UrP#7XBWK
zcY{10YCTm=vcg|-N?q%&o8I`M5Nyqr)y7p*-lWX5l5Y;)HnKv;E19yaE%u8oa;{gH
z$uVP8Pgr>*RSld9*Ku#dVwLAIl`sEzu&GxL>3+Qt3FGtmKE$OZs<|db>swiMPoa#9
zC%tr_@%s`zgTF*i!H;tLkNcZQ`QhPrTZ%v=41Md262yi9jd0#5)v%S!1An3bQS3Cu
zp763WfgZ7NZqx!#^KaRXt2wr9LJWp+;ZONbEwkJ~T`S1)E#7(M%bbJ1<;%g062B-v
zKnSK2W8W_$b}vOkAH3B0%`V49nQBFED|YN<<<7#H&n!+Zxe}_lH}2GFz%X9_;<B=F
z6rukGht?ZZ_VqPMw=G37<pO%mlOQDW=D;7jbNPrWX!F3BDNipMuZ)`bO<(2p%h!{9
zh~+&BxOEg{aTHQPo!v<B@WoN)-3~j#QRD|$cm)NH_c)x$`Js%WMy@Gw?l_ZtjORUx
z>R!xwLoc3p@IH&~PTI++rDWmYNjGMhaO+Qv#h<!2e;Ts>lu4v`Veoooe@u|a4sLBk
zSIUlP%8wR*t=<0G;r{krrL+mBk~sK2XmL9J=5!+Kbn3(D%-rdB@+pb;Z2s2SqQ#lI
z180Tn*?Uy|Va{2V<-t}o^)@d#5lP;=Pkr!)9E&59PqI?jzmwrWn1D&DP-?N*bW_D$
zR^+4U>zV6{bAN6jg}IpDb_+-snMtQ1Qe;FkbW6s?<Vt4Uo6Qk>VmxvEOENdg%&WbA
z$SFx?jjSIiDu-JlY>#hQ;z@9;>>ttXL~OfN?t*}I-Xg;0{m(15`AdR!1<OMAg)71i
zMXMr?#cQHZOV-7lN;kxv%Qhuk%C}r>Ay5HV!Zz|*?nhO0<&LyRb*eu=*p+==yB|v=
z?#p@AU)MRPKaxLw0Y>{Yo!q#J26uv*|0=bLLV|<Pr^;_W*fxB?f~h#c8r$%WAU8Tu
zr<LvOL<o3KrPTiSV`gP2(tTs)Sr68mSDhRy?y!UCix)Mja$4QFqWu(XJDkU{EBM9v
zn%C0Cs>kG))LWs<V;4tlzvgLLac4B{iRkO=P~0wa+#eY&F|9Z4>)RKbP&Mz2m3V7c
zI$7g5iGQ?yP?lWhwme+RUoZK+MRRLybDa$~_aT648m4`OoM#PTk+E%QkXmey7SJnq
zI+k7<NWJc{wQ(%7GL)kpC+U15yEa;ERPC~Pa&2Rx%5J3G`H$SzOq18{*5;q<+oX<A
zma8s*<#!hQl4M-B{wnOP3>WBCxSZZN*qEyK__cMac(gs=6L;11OzC8A?OV0$ud|zf
zk9L+vDqP9RXMax)cYpmN-@<}u<l+7lik#l?0BX?&cp&|aBY4mSO?kfHi>Bv4H5`r&
ne4*SgkNCp)BINnQucUhOM~D<R@V}L4I^vI%>O0ba0gC?vxbu!L

literal 0
HcmV?d00001

diff --git a/project/demos.mdx b/project/demos.mdx
index 92069a8..f5fe332 100644
--- a/project/demos.mdx
+++ b/project/demos.mdx
@@ -11,6 +11,7 @@ The docs site ships with recorded terminal GIFs from the repo:
 - subscriber summarize
 - news
 - assistant
+- translate
 
 ## Preview
 
@@ -30,6 +31,10 @@ The docs site ships with recorded terminal GIFs from the repo:
 
 ![Assistant demo](/images/demos/assistant.gif)
 
+### Translate
+
+![Translate demo](/images/demos/translate.gif)
+
 ## Regenerate
 
 Subscriber demos require `KAGI_SESSION_TOKEN`.
diff --git a/scripts/demo-assistant.sh b/scripts/demo-assistant.sh
index 028bcef..72377a3 100755
--- a/scripts/demo-assistant.sh
+++ b/scripts/demo-assistant.sh
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+#!/usr/bin/env bash
+
 set -euo pipefail
 
 cd "$(dirname "$0")/.."
diff --git a/scripts/demo-news.sh b/scripts/demo-news.sh
index 17c3ea5..c1194e6 100755
--- a/scripts/demo-news.sh
+++ b/scripts/demo-news.sh
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+#!/usr/bin/env bash
+
 set -euo pipefail
 
 cd "$(dirname "$0")/.."
diff --git a/scripts/demo-search.sh b/scripts/demo-search.sh
index 1a56205..3e56562 100755
--- a/scripts/demo-search.sh
+++ b/scripts/demo-search.sh
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+#!/usr/bin/env bash
+
 set -euo pipefail
 
 cd "$(dirname "$0")/.."
diff --git a/scripts/demo-summarize.sh b/scripts/demo-summarize.sh
index d3fe026..d422589 100755
--- a/scripts/demo-summarize.sh
+++ b/scripts/demo-summarize.sh
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+#!/usr/bin/env bash
+
 set -euo pipefail
 
 cd "$(dirname "$0")/.."
diff --git a/scripts/demo-translate.sh b/scripts/demo-translate.sh
new file mode 100755
index 0000000..0c9b578
--- /dev/null
+++ b/scripts/demo-translate.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+: "${KAGI_SESSION_TOKEN:?set KAGI_SESSION_TOKEN before running this demo}"
+
+cargo build --quiet
+mkdir -p /tmp/kagi-demo-bin
+ln -sf "$PWD/target/debug/kagi" /tmp/kagi-demo-bin/kagi
+export PATH="/tmp/kagi-demo-bin:$PATH"
+
+printf '\033c'
+sleep 1.2
+printf '$ kagi translate "Bonjour tout le monde" --to ja | jq -M ...\n'
+sleep 0.4
+kagi translate "Bonjour tout le monde" --to ja \
+  | jq -M '{
+      detected_language: .detected_language.label,
+      translation: .translation.translation,
+      alignments: (.text_alignments.alignments | length),
+      alternatives: (.alternatives.elements | map(.translation)[0:3]),
+      suggestion_labels: (.translation_suggestions.suggestions | map(.label)[0:3]),
+      word_insight_terms: (.word_insights.insights | map(.original_text)[0:3])
+    }'
+sleep 2

From 7087d8eb786bf81593c33acffed5fbc444455226 Mon Sep 17 00:00:00 2001
From: Microck <contact@micr.dev>
Date: Wed, 18 Mar 2026 19:13:35 +0000
Subject: [PATCH 3/7] fix(translate): harden edge cases and output metadata

---
 docs/commands/translate.mdx        |   2 +-
 docs/reference/error-reference.mdx |  15 ++
 docs/reference/output-contract.mdx |   4 +-
 src/api.rs                         | 307 +++++++++++++++++++++++++++--
 src/types.rs                       |   4 +
 5 files changed, 310 insertions(+), 22 deletions(-)

diff --git a/docs/commands/translate.mdx b/docs/commands/translate.mdx
index fb50210..a1800f0 100644
--- a/docs/commands/translate.mdx
+++ b/docs/commands/translate.mdx
@@ -69,7 +69,7 @@ Source language code. Default: `auto`.
 
 ### `--to <LANG>`
 
-Target language code. Default: `en`.
+Target language code. Default: `en`. `auto` is not accepted for the target language.
 
 ### `--quality <QUALITY>`
 
diff --git a/docs/reference/error-reference.mdx b/docs/reference/error-reference.mdx
index 6df9792..fd07110 100644
--- a/docs/reference/error-reference.mdx
+++ b/docs/reference/error-reference.mdx
@@ -217,6 +217,21 @@ Error: Config: --cache is only supported for the paid public summarizer API
 kagi summarize --url https://example.com --cache false
 ```
 
+### "translate --to cannot be 'auto'; pass an explicit target language code"
+
+**Message:**
+```text
+configuration error: translate --to cannot be 'auto'; pass an explicit target language code
+```
+
+**Meaning:** Translate can auto-detect the source language, but the target language must always be explicit.
+
+**Solution:**
+```bash
+kagi translate "Bonjour tout le monde" --to en
+kagi translate "Bonjour tout le monde" --to ja
+```
+
 ### "--url or --text required"
 
 **Meaning:** Summarize command needs content to summarize.
diff --git a/docs/reference/output-contract.mdx b/docs/reference/output-contract.mdx
index 48dc496..745f298 100644
--- a/docs/reference/output-contract.mdx
+++ b/docs/reference/output-contract.mdx
@@ -150,7 +150,9 @@ Subscriber mode:
     "label": "French"
   },
   "translation": {
-    "translation": "Hello everyone"
+    "translation": "Hello everyone",
+    "source_language": "fr",
+    "target_language": "en"
   },
   "alternatives": {
     "elements": []
diff --git a/src/api.rs b/src/api.rs
index 15b047a..f90ef3a 100644
--- a/src/api.rs
+++ b/src/api.rs
@@ -389,23 +389,7 @@ pub async fn execute_translate(
         ));
     }
 
-    if request.text.trim().is_empty() {
-        return Err(KagiError::Config(
-            "translate text cannot be empty".to_string(),
-        ));
-    }
-
-    if request.from.trim().is_empty() {
-        return Err(KagiError::Config(
-            "translate --from cannot be empty".to_string(),
-        ));
-    }
-
-    if request.to.trim().is_empty() {
-        return Err(KagiError::Config(
-            "translate --to cannot be empty".to_string(),
-        ));
-    }
+    validate_translate_request(request)?;
 
     let bootstrap = bootstrap_translate_session(session_token).await?;
     let client = build_client()?;
@@ -422,9 +406,15 @@ pub async fn execute_translate(
         &effective_source_language,
     )
     .await?;
+    let target_language = request.to.clone();
+    let translation = finalize_translate_text_response(
+        translation,
+        &detected_language,
+        &effective_source_language,
+        &target_language,
+    );
     let translation_options = build_translate_option_state(request);
     let translated_text = translation.translation.clone();
-    let target_language = request.to.clone();
     let translate_session = bootstrap.translate_session.clone();
 
     let (alternatives_result, alignments_result, suggestions_result, insights_result) = tokio::join!(
@@ -1263,6 +1253,34 @@ fn build_translate_cookie_header(session_token: &str, translate_session: &str) -
     format!("kagi_session={session_token}; translate_session={translate_session}")
 }
 
+fn validate_translate_request(request: &TranslateCommandRequest) -> Result<(), KagiError> {
+    if request.text.trim().is_empty() {
+        return Err(KagiError::Config(
+            "translate text cannot be empty".to_string(),
+        ));
+    }
+
+    if request.from.trim().is_empty() {
+        return Err(KagiError::Config(
+            "translate --from cannot be empty".to_string(),
+        ));
+    }
+
+    if request.to.trim().is_empty() {
+        return Err(KagiError::Config(
+            "translate --to cannot be empty".to_string(),
+        ));
+    }
+
+    if request.to.eq_ignore_ascii_case("auto") {
+        return Err(KagiError::Config(
+            "translate --to cannot be 'auto'; pass an explicit target language code".to_string(),
+        ));
+    }
+
+    Ok(())
+}
+
 fn effective_translate_source_language(
     requested_from: &str,
     detected_language: &TranslateDetectedLanguage,
@@ -1274,6 +1292,20 @@ fn effective_translate_source_language(
     }
 }
 
+fn finalize_translate_text_response(
+    mut translation: TranslateTextResponse,
+    detected_language: &TranslateDetectedLanguage,
+    effective_source_language: &str,
+    target_language: &str,
+) -> TranslateTextResponse {
+    if translation.detected_language.is_none() {
+        translation.detected_language = Some(detected_language.clone());
+    }
+    translation.source_language = Some(effective_source_language.to_string());
+    translation.target_language = Some(target_language.to_string());
+    translation
+}
+
 fn build_translate_option_state(request: &TranslateCommandRequest) -> Option<TranslateOptionState> {
     let options = TranslateOptionState {
         formality: request.formality.clone(),
@@ -1662,17 +1694,69 @@ pub struct KagiEnvelope<T> {
 #[cfg(test)]
 mod tests {
     use super::{
-        ApiErrorBody, KagiEnvelope, build_translate_payload, normalize_aux_quality,
+        ApiErrorBody, KagiEnvelope, build_translate_option_state, build_translate_payload,
+        capture_optional_translate_section, effective_translate_source_language,
+        finalize_translate_text_response, normalize_aux_quality,
         normalize_subscriber_summary_input, normalize_subscriber_summary_length,
         normalize_subscriber_summary_type, parse_assistant_prompt_stream,
         parse_subscriber_summarize_stream, parse_translate_detect_value, resolve_news_category,
+        validate_translate_request,
     };
+    use crate::auth::normalize_session_token;
     use crate::types::SubscriberSummarizeRequest;
     use crate::types::{
         FastGptAnswer, NewsBatchCategory, NewsCategoryMetadata, Reference, Summarization,
-        TranslateCommandRequest,
+        TranslateCommandRequest, TranslateDetectedLanguage, TranslateTextResponse,
     };
     use serde_json::{Value, json};
+    use std::sync::{
+        Arc,
+        atomic::{AtomicBool, Ordering},
+    };
+
+    fn sample_translate_request() -> TranslateCommandRequest {
+        TranslateCommandRequest {
+            text: "Bonjour".to_string(),
+            from: "auto".to_string(),
+            to: "en".to_string(),
+            quality: None,
+            model: None,
+            prediction: None,
+            predicted_language: None,
+            formality: None,
+            speaker_gender: None,
+            addressee_gender: None,
+            language_complexity: None,
+            translation_style: None,
+            context: None,
+            dictionary_language: None,
+            time_format: None,
+            use_definition_context: None,
+            enable_language_features: None,
+            preserve_formatting: None,
+            context_memory: None,
+            fetch_alternatives: true,
+            fetch_word_insights: true,
+            fetch_suggestions: true,
+            fetch_alignments: true,
+        }
+    }
+
+    fn sample_detected_language() -> TranslateDetectedLanguage {
+        TranslateDetectedLanguage {
+            iso: "fr".to_string(),
+            label: "French".to_string(),
+            is_uncertain: false,
+            is_mixed: false,
+            alternatives: vec![],
+        }
+    }
+
+    fn live_translate_session_token() -> Option<String> {
+        std::env::var("KAGI_SESSION_TOKEN")
+            .ok()
+            .and_then(|value| normalize_session_token(&value).ok())
+    }
 
     #[test]
     fn parses_summarize_envelope() {
@@ -1910,6 +1994,91 @@ mod tests {
         assert_eq!(parsed_array.label, "French");
     }
 
+    #[test]
+    fn rejects_empty_translate_detect_array() {
+        let error = parse_translate_detect_value(Value::Array(vec![]))
+            .expect_err("empty array should fail");
+        assert!(error.to_string().contains("empty array"));
+    }
+
+    #[test]
+    fn rejects_translate_target_auto_value() {
+        let mut request = sample_translate_request();
+        request.to = "auto".to_string();
+
+        let error = validate_translate_request(&request).expect_err("auto target should fail");
+        assert!(error.to_string().contains("explicit target language code"));
+    }
+
+    #[test]
+    fn uses_detected_source_language_when_translate_from_is_auto() {
+        let source = effective_translate_source_language("auto", &sample_detected_language());
+        assert_eq!(source, "fr");
+    }
+
+    #[test]
+    fn preserves_explicit_translate_source_language() {
+        let source = effective_translate_source_language("es", &sample_detected_language());
+        assert_eq!(source, "es");
+    }
+
+    #[test]
+    fn backfills_translate_language_metadata() {
+        let translation = TranslateTextResponse {
+            translation: "Hello everyone".to_string(),
+            source_language: None,
+            target_language: None,
+            detected_language: None,
+            definition: None,
+        };
+
+        let finalized =
+            finalize_translate_text_response(translation, &sample_detected_language(), "fr", "en");
+
+        assert_eq!(finalized.source_language.as_deref(), Some("fr"));
+        assert_eq!(finalized.target_language.as_deref(), Some("en"));
+        assert_eq!(
+            finalized
+                .detected_language
+                .as_ref()
+                .map(|value| value.iso.as_str()),
+            Some("fr")
+        );
+    }
+
+    #[test]
+    fn keeps_existing_translate_detected_language_when_present() {
+        let translation = TranslateTextResponse {
+            translation: "Hello everyone".to_string(),
+            source_language: None,
+            target_language: None,
+            detected_language: Some(TranslateDetectedLanguage {
+                iso: "es".to_string(),
+                label: "Spanish".to_string(),
+                is_uncertain: false,
+                is_mixed: false,
+                alternatives: vec![],
+            }),
+            definition: None,
+        };
+
+        let finalized =
+            finalize_translate_text_response(translation, &sample_detected_language(), "fr", "en");
+
+        assert_eq!(
+            finalized
+                .detected_language
+                .as_ref()
+                .map(|value| value.iso.as_str()),
+            Some("es")
+        );
+    }
+
+    #[test]
+    fn omits_empty_translate_option_state() {
+        assert!(build_translate_option_state(&sample_translate_request()).is_none());
+    }
+
     #[test]
     fn builds_translate_payload_with_optional_fields() {
         let request = TranslateCommandRequest {
@@ -1958,6 +2127,7 @@ mod tests {
 
     #[test]
     fn normalizes_aux_quality_values() {
+        assert_eq!(normalize_aux_quality(None), None);
         assert_eq!(normalize_aux_quality(Some("best")).as_deref(), Some("best"));
         assert_eq!(
             normalize_aux_quality(Some("deep_contextual")).as_deref(),
@@ -1968,4 +2138,101 @@ mod tests {
             Some("standard")
         );
     }
+
+    #[tokio::test]
+    async fn skips_disabled_translate_optional_sections_without_polling() {
+        let polled = Arc::new(AtomicBool::new(false));
+        let future_polled = Arc::clone(&polled);
+
+        let (value, warning) =
+            capture_optional_translate_section("word_insights", false, async move {
+                future_polled.store(true, Ordering::SeqCst);
+                Ok::<_, crate::error::KagiError>("value")
+            })
+            .await;
+
+        assert!(value.is_none());
+        assert!(warning.is_none());
+        assert!(!polled.load(Ordering::SeqCst));
+    }
+
+    #[tokio::test]
+    async fn captures_translate_optional_section_failures_as_warnings() {
+        let (value, warning) = capture_optional_translate_section("word_insights", true, async {
+            Err::<Value, _>(crate::error::KagiError::Network(
+                "temporary upstream failure".to_string(),
+            ))
+        })
+        .await;
+
+        assert!(value.is_none());
+        let warning = warning.expect("warning should be returned");
+        assert_eq!(warning.section, "word_insights");
+        assert!(warning.message.contains("temporary upstream failure"));
+    }
+
+    #[tokio::test]
+    #[ignore = "requires live KAGI_SESSION_TOKEN"]
+    async fn live_translate_populates_language_metadata_and_sections() {
+        let token = live_translate_session_token().expect("set KAGI_SESSION_TOKEN for live tests");
+        let request = TranslateCommandRequest {
+            text: "Bonjour tout le monde".to_string(),
+            ..sample_translate_request()
+        };
+
+        let response = super::execute_translate(&request, &token)
+            .await
+            .expect("live translate should succeed");
+
+        assert_eq!(response.detected_language.iso, "fr");
+        assert_eq!(response.translation.source_language.as_deref(), Some("fr"));
+        assert_eq!(response.translation.target_language.as_deref(), Some("en"));
+        assert!(!response.translation.translation.trim().is_empty());
+
+        for (section, present) in [
+            ("alternatives", response.alternatives.is_some()),
+            ("text_alignments", response.text_alignments.is_some()),
+            (
+                "translation_suggestions",
+                response.translation_suggestions.is_some(),
+            ),
+            ("word_insights", response.word_insights.is_some()),
+        ] {
+            let warned = response
+                .warnings
+                .iter()
+                .any(|warning| warning.section == section);
+            assert!(
+                present || warned,
+                "expected {section} to be present or downgraded to a warning"
+            );
+        }
+    }
+
+    #[tokio::test]
+    #[ignore = "requires live KAGI_SESSION_TOKEN"]
+    async fn live_translate_core_only_skips_auxiliary_sections() {
+        let token = live_translate_session_token().expect("set KAGI_SESSION_TOKEN for live tests");
+        let request = TranslateCommandRequest {
+            text: "Bonjour tout le monde".to_string(),
+            to: "ja".to_string(),
+            fetch_alternatives: false,
+            fetch_word_insights: false,
+            fetch_suggestions: false,
+            fetch_alignments: false,
+            ..sample_translate_request()
+        };
+
+        let response = super::execute_translate(&request, &token)
+            .await
+            .expect("live translate should succeed");
+
+        assert_eq!(response.translation.source_language.as_deref(), Some("fr"));
+        assert_eq!(response.translation.target_language.as_deref(), Some("ja"));
+        assert!(response.alternatives.is_none());
+        assert!(response.text_alignments.is_none());
+        assert!(response.translation_suggestions.is_none());
+        assert!(response.word_insights.is_none());
+        assert!(response.warnings.is_empty());
+    }
 }
diff --git a/src/types.rs b/src/types.rs
index 5924ba3..0765518 100644
--- a/src/types.rs
+++ b/src/types.rs
@@ -402,6 +402,10 @@ pub struct TranslateDetectedLanguage {
 pub struct TranslateTextResponse {
     pub translation: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source_language: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub target_language: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub detected_language: Option<TranslateDetectedLanguage>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub definition: Option<Value>,

From 96741055b3c3f835a41319593d127cd349510005 Mon Sep 17 00:00:00 2001
From: Microck <contact@micr.dev>
Date: Wed, 18 Mar 2026 22:04:12 +0000
Subject: [PATCH 4/7] refactor(translate): replace python bootstrap with
 reqwest

---
 Cargo.lock                         |  21 ---
 Cargo.toml                         |   2 +-
 README.md                          |   1 -
 docs/api-coverage.md               |   3 +-
 docs/commands/translate.mdx        |  19 +--
 docs/index.mdx                     |   1 -
 docs/reference/auth-matrix.mdx     |   2 +-
 docs/reference/coverage.mdx        |   2 -
 docs/reference/error-reference.mdx |  18 ++-
 docs/reference/output-contract.mdx |   2 +-
 src/api.rs                         | 232 +++++++++++------------------
 11 files changed, 109 insertions(+), 194 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 4eceeb6..62edc34 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -241,16 +241,6 @@ version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
 
-[[package]]
-name = "errno"
-version = "0.3.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
-dependencies = [
- "libc",
- "windows-sys 0.52.0",
-]
-
 [[package]]
 name = "fastrand"
 version = "2.3.0"
@@ -1197,16 +1187,6 @@ version = "1.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
 
-[[package]]
-name = "signal-hook-registry"
-version = "1.4.8"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
-dependencies = [
- "errno",
- "libc",
-]
-
 [[package]]
 name = "siphasher"
 version = "1.0.2"
@@ -1374,7 +1354,6 @@ dependencies = [
  "libc",
  "mio",
  "pin-project-lite",
- "signal-hook-registry",
  "socket2",
  "tokio-macros",
  "windows-sys 0.61.2",
diff --git a/Cargo.toml b/Cargo.toml
index 26ef15f..677d5a9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -30,5 +30,5 @@ scraper = "0.25.0"
 serde = { version = "1.0.219", features = ["derive"] }
 serde_json = "1.0.140"
 thiserror = "2.0.12"
-tokio = { version = "1.44.2", features = ["macros", "process", "rt-multi-thread"] }
+tokio = { version = "1.44.2", features = ["macros", "rt-multi-thread"] }
 toml = "1.0.6"
diff --git a/README.md b/README.md
index 34ed3ab..1903383 100644
--- a/README.md
+++ b/README.md
@@ -125,7 +125,6 @@ notes:
 - base `kagi search` defaults to the session-token path when both credentials are present
 - set `[auth] preferred_auth = "api"` if you want base search to prefer the API path instead
 - `search --lens` always requires `KAGI_SESSION_TOKEN`
-- `translate` currently also requires `python3` with the `curl_cffi` package installed
 - `auth check` validates the selected primary credential without using search fallback logic
 
 for the full command-to-token matrix, use the [`auth-matrix`](https://kagi.micr.dev/reference/auth-matrix) docs page.
diff --git a/docs/api-coverage.md b/docs/api-coverage.md
index f71bab8..4bcb2d5 100644
--- a/docs/api-coverage.md
+++ b/docs/api-coverage.md
@@ -36,8 +36,7 @@ This CLI also implements non-public or product-only seams:
 - Base-search fallback to session-token search happens on the user-facing `search` command only. `auth check` validates the selected primary credential without fallback.
 - The paid public Summarizer, FastGPT, and Enrichment APIs require `KAGI_API_TOKEN` and sufficient API credit.
 - The subscriber web Summarizer requires `KAGI_SESSION_TOKEN` and uses the authenticated `GET /mother/summary_labs?...` stream path instead of the public `/api/v0/summarize` endpoint.
-- Live verification on March 18, 2026 showed that direct raw-cookie HTTP bootstrap still fails, but a browserless `python3 + curl_cffi` bootstrap can mint `translate_session` from the same `KAGI_SESSION_TOKEN`.
+- Live verification on March 18, 2026 showed that direct HTTP bootstrap can mint `translate_session` from the same `KAGI_SESSION_TOKEN` by reading the `Set-Cookie` header from `https://translate.kagi.com/`.
 - After bootstrap, the CLI uses normal Rust HTTP requests for `/api/detect`, `/api/translate`, `/api/alternative-translations`, `/api/text-alignments`, `/api/translation-suggestions`, and `/api/word-insights`.
-- `translate` requires `python3` with the `curl_cffi` package installed at runtime.
 - Assistant requires `KAGI_SESSION_TOKEN` and currently targets `/assistant/prompt` with the same tagged stream protocol used by the web app.
 - News uses `https://news.kagi.com/api/...` JSON endpoints and does not require auth.
diff --git a/docs/commands/translate.mdx b/docs/commands/translate.mdx
index a1800f0..078c7f4 100644
--- a/docs/commands/translate.mdx
+++ b/docs/commands/translate.mdx
@@ -42,14 +42,9 @@ The command follows the same Session Link auth story as other subscriber feature
 kagi auth set --session-token 'https://kagi.com/search?token=...'
 ```
 
-## Runtime Dependency
+## Bootstrap
 
-Translate bootstrap currently requires:
-
-- `python3`
-- the Python package `curl_cffi`
-
-The CLI shells out once to mint `translate_session`, then uses normal Rust HTTP requests for the rest of the flow.
+The CLI uses your existing `KAGI_SESSION_TOKEN` to fetch `https://translate.kagi.com/`, reads the returned `translate_session` cookie from `Set-Cookie`, then uses normal Rust HTTP requests for the rest of the flow.
 
 ## Arguments
 
@@ -165,7 +160,7 @@ Skip the text alignments call.
 ```json
 {
   "bootstrap": {
-    "method": "python3+curl_cffi(chrome136)",
+    "method": "reqwest(set-cookie bootstrap)",
     "authenticated": true
   },
   "detected_language": {
@@ -173,7 +168,9 @@ Skip the text alignments call.
     "label": "French"
   },
   "translation": {
-    "translation": "Hello everyone"
+    "translation": "Hello everyone",
+    "source_language": "fr",
+    "target_language": "en"
   },
   "alternatives": {
     "elements": []
@@ -240,9 +237,9 @@ kagi translate "Bonjour tout le monde" | jq -r '.translation.translation'
 
 ## Troubleshooting
 
-### Missing bootstrap dependency
+### Bootstrap failure
 
-If you see an error mentioning `python3` or `curl_cffi`, install the missing dependency and retry.
+If translate bootstrap fails before detection or translation starts, the session token is likely invalid for the current account state or Kagi changed the cookie bootstrap behavior.
 
 ### Invalid session token
 
diff --git a/docs/index.mdx b/docs/index.mdx
index 30fa254..85349fb 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -170,7 +170,6 @@ Choose your path based on your current needs:
 - **For scripting**: `jq` for JSON processing (recommended)
 - **For development**: Rust toolchain 1.70+
 - **For npm install**: Node.js 16+ and npm, pnpm, or bun
-- **For `kagi translate`**: `python3` with the `curl_cffi` package installed
 
 ## Design Principles in Practice
 
diff --git a/docs/reference/auth-matrix.mdx b/docs/reference/auth-matrix.mdx
index a37de66..df9421b 100644
--- a/docs/reference/auth-matrix.mdx
+++ b/docs/reference/auth-matrix.mdx
@@ -20,7 +20,7 @@ This reference provides a complete mapping of which commands require which authe
 | `summarize --subscriber` | `KAGI_SESSION_TOKEN` | None | Subscriber web product |
 | `news` | None | None | Public endpoint |
 | `assistant` | `KAGI_SESSION_TOKEN` | None | Subscriber feature |
-| `translate` | `KAGI_SESSION_TOKEN` | None | Text mode only; runtime bootstrap needs `python3 + curl_cffi` |
+| `translate` | `KAGI_SESSION_TOKEN` | None | Text mode only; bootstraps `translate_session` over HTTP |
 | `fastgpt` | `KAGI_API_TOKEN` | None | Paid public API |
 | `enrich web` | `KAGI_API_TOKEN` | None | Paid public API |
 | `enrich news` | `KAGI_API_TOKEN` | None | Paid public API |
diff --git a/docs/reference/coverage.mdx b/docs/reference/coverage.mdx
index 6993f5a..df09252 100644
--- a/docs/reference/coverage.mdx
+++ b/docs/reference/coverage.mdx
@@ -180,8 +180,6 @@ All commands output JSON:
 | GitHub Releases | ✅ |
 | Build from source | ✅ |
 
-**Translate runtime note:** `kagi translate` additionally requires `python3` with the `curl_cffi` package installed.
-
 ## Feature Comparison Matrix
 
 ### vs Kagi Web Product
diff --git a/docs/reference/error-reference.mdx b/docs/reference/error-reference.mdx
index fd07110..b14a78d 100644
--- a/docs/reference/error-reference.mdx
+++ b/docs/reference/error-reference.mdx
@@ -155,18 +155,24 @@ rm ./.kagi.toml
 kagi auth set --session-token 'YOUR_TOKEN'
 ```
 
-### "kagi translate requires `python3` with the `curl_cffi` package installed"
+### "translate bootstrap did not mint a translate_session cookie"
 
-**Meaning:** The translate bootstrap helper is missing a local runtime dependency.
+**Meaning:** The translate site accepted the request but did not issue the session cookie the CLI needs for follow-on API calls.
+
+**Likely causes:**
+- `KAGI_SESSION_TOKEN` is invalid or expired
+- the current Kagi account state no longer authorizes Translate
+- Kagi changed the bootstrap cookie behavior
 
 **Solution:**
 ```bash
-python3 -m pip install --user curl_cffi
-```
+# refresh and save the current Session Link
+kagi auth set --session-token 'https://kagi.com/search?token=...'
 
-Then retry:
+# verify the token still works for subscriber features
+kagi auth check
 
-```bash
+# retry translate
 kagi translate "Bonjour tout le monde"
 ```
 
diff --git a/docs/reference/output-contract.mdx b/docs/reference/output-contract.mdx
index 745f298..3bbcda3 100644
--- a/docs/reference/output-contract.mdx
+++ b/docs/reference/output-contract.mdx
@@ -142,7 +142,7 @@ Subscriber mode:
 ```json
 {
   "bootstrap": {
-    "method": "python3+curl_cffi(chrome136)",
+    "method": "reqwest(set-cookie bootstrap)",
     "authenticated": true
   },
   "detected_language": {
diff --git a/src/api.rs b/src/api.rs
index f90ef3a..27b2907 100644
--- a/src/api.rs
+++ b/src/api.rs
@@ -1,6 +1,5 @@
 use std::collections::HashMap;
 use std::future::Future;
-use std::process::Stdio;
 
 use reqwest::{Client, StatusCode, header};
 use serde::Deserialize;
@@ -9,7 +8,6 @@ use serde::Serialize;
 use serde::de::DeserializeOwned;
 use serde_json::json;
 use serde_json::{Map, Value};
-use tokio::process::Command;
 
 use crate::error::KagiError;
 #[cfg(test)]
@@ -583,132 +581,41 @@ async fn execute_enrich(
 async fn bootstrap_translate_session(
     session_token: &str,
 ) -> Result<TranslateBootstrapResult, KagiError> {
-    const BOOTSTRAP_SCRIPT: &str = r#"import json
-import os
-import sys
-
-def finish(ok, **kwargs):
-    payload = {"ok": ok}
-    payload.update(kwargs)
-    print(json.dumps(payload))
-    sys.exit(0 if ok else 1)
-
-token = os.environ.get("KAGI_SESSION_TOKEN_RAW", "").strip()
-if not token:
-    finish(False, kind="config", message="missing normalized KAGI session token")
-
-try:
-    from curl_cffi import requests
-except Exception as exc:
-    finish(
-        False,
-        kind="config",
-        message="kagi translate requires python3 with the curl_cffi package installed",
-        detail=str(exc),
-    )
-
-try:
-    session = requests.Session(impersonate="chrome136")
-    session.cookies.set("kagi_session", token, domain=".kagi.com", path="/", secure=True)
-    response = session.get("https://translate.kagi.com/", timeout=30, allow_redirects=True)
-except Exception as exc:
-    finish(False, kind="network", message="translate bootstrap request failed", detail=str(exc))
-
-if response.status_code >= 400:
-    finish(
-        False,
-        kind="network",
-        message=f"translate bootstrap returned HTTP {response.status_code}",
-    )
-
-translate_session = ""
-for cookie in session.cookies.jar:
-    if cookie.name == "translate_session" and cookie.value:
-        translate_session = cookie.value
-        break
-
-if not translate_session:
-    finish(
-        False,
-        kind="auth",
-        message="translate bootstrap did not mint a translate_session cookie",
-    )
-
-finish(
-    True,
-    translate_session=translate_session,
-    method="python3+curl_cffi(chrome136)",
-)
-"#;
-
-    let output = Command::new("python3")
-        .arg("-c")
-        .arg(BOOTSTRAP_SCRIPT)
-        .env("KAGI_SESSION_TOKEN_RAW", session_token)
-        .stdout(Stdio::piped())
-        .stderr(Stdio::piped())
-        .output()
+    let client = build_client()?;
+    let response = client
+        .get("https://translate.kagi.com/")
+        .header(header::COOKIE, format!("kagi_session={session_token}"))
+        .send()
         .await
-        .map_err(|error| match error.kind() {
-            std::io::ErrorKind::NotFound => KagiError::Config(
-                "kagi translate requires `python3` with the `curl_cffi` package installed"
-                    .to_string(),
-            ),
-            _ => KagiError::Config(format!(
-                "failed to start translate bootstrap helper: {error}"
-            )),
-        })?;
-
-    let stdout = String::from_utf8(output.stdout).map_err(|error| {
-        KagiError::Parse(format!(
-            "translate bootstrap helper returned non-UTF-8 output: {error}"
-        ))
-    })?;
-    let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
-    let trimmed_stdout = stdout.trim();
-
-    if trimmed_stdout.is_empty() {
-        return Err(KagiError::Config(if stderr.is_empty() {
-            "translate bootstrap helper returned no output".to_string()
-        } else {
-            format!("translate bootstrap helper failed: {stderr}")
-        }));
-    }
-
-    let parsed: TranslateBootstrapScriptOutput =
-        serde_json::from_str(trimmed_stdout).map_err(|error| {
-            KagiError::Parse(format!(
-                "failed to parse translate bootstrap helper output: {error}"
-            ))
-        })?;
+        .map_err(map_transport_error)?;
 
-    if parsed.ok {
-        let translate_session = parsed.translate_session.ok_or_else(|| {
-            KagiError::Parse(
-                "translate bootstrap helper did not return translate_session".to_string(),
+    match response.status() {
+        StatusCode::OK => {
+            let translate_session = extract_set_cookie_value(
+                response.headers(),
+                "translate_session",
             )
-        })?;
-        let method = parsed
-            .method
-            .unwrap_or_else(|| "python3+curl_cffi".to_string());
-
-        return Ok(TranslateBootstrapResult {
-            translate_session,
-            method,
-        });
-    }
+            .ok_or_else(|| {
+                KagiError::Auth(
+                    "translate bootstrap did not mint a translate_session cookie".to_string(),
+                )
+            })?;
 
-    let mut message = parsed
-        .message
-        .unwrap_or_else(|| "translate bootstrap failed".to_string());
-    if !stderr.is_empty() {
-        message.push_str(&format!("; stderr: {stderr}"));
+            Ok(TranslateBootstrapResult {
+                translate_session,
+                method: "reqwest(set-cookie bootstrap)".to_string(),
+            })
+        }
+        StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN => Err(KagiError::Auth(
+            "invalid or expired Kagi session token for Kagi Translate".to_string(),
+        )),
+        status if status.is_server_error() => Err(KagiError::Network(format!(
+            "Kagi Translate bootstrap server error: HTTP {status}"
+        ))),
+        status => Err(KagiError::Network(format!(
+            "unexpected Kagi Translate bootstrap response status: HTTP {status}"
+        ))),
     }
-
-    Err(map_bootstrap_kind_to_error(
-        parsed.kind.as_deref().unwrap_or("config"),
-        &message,
-    ))
 }
 
 async fn execute_translate_detect(
@@ -1453,13 +1360,33 @@ fn parse_translate_detect_value(value: Value) -> Result<TranslateDetectedLanguag
     })
 }
 
-fn map_bootstrap_kind_to_error(kind: &str, message: &str) -> KagiError {
-    match kind {
-        "auth" => KagiError::Auth(message.to_string()),
-        "network" => KagiError::Network(message.to_string()),
-        "parse" => KagiError::Parse(message.to_string()),
-        _ => KagiError::Config(message.to_string()),
+fn extract_set_cookie_value(headers: &header::HeaderMap, name: &str) -> Option<String> {
+    let prefix = format!("{name}=");
+
+    headers
+        .get_all(header::SET_COOKIE)
+        .iter()
+        .find_map(|value| {
+            let raw = value.to_str().ok()?;
+            let cookie = raw.strip_prefix(&prefix)?;
+            cookie
+                .split(';')
+                .next()
+                .filter(|value| !value.is_empty())
+                .map(str::to_string)
+        })
+}
+
+#[cfg(test)]
+fn fake_header_map(set_cookies: &[&str]) -> header::HeaderMap {
+    let mut headers = header::HeaderMap::new();
+    for value in set_cookies {
+        headers.append(
+            header::SET_COOKIE,
+            header::HeaderValue::from_str(value).expect("header value should parse"),
+        );
     }
+    headers
 }
 
 #[derive(Debug, Deserialize)]
@@ -1535,19 +1462,6 @@ struct AssistantMessagePayload {
     profile: Option<Value>,
 }
 
-#[derive(Debug, Deserialize)]
-struct TranslateBootstrapScriptOutput {
-    ok: bool,
-    #[serde(default)]
-    kind: Option<String>,
-    #[serde(default)]
-    message: Option<String>,
-    #[serde(default)]
-    translate_session: Option<String>,
-    #[serde(default)]
-    method: Option<String>,
-}
-
 #[derive(Debug)]
 struct TranslateBootstrapResult {
     translate_session: String,
@@ -1696,11 +1610,11 @@ mod tests {
     use super::{
         ApiErrorBody, KagiEnvelope, build_translate_option_state, build_translate_payload,
         capture_optional_translate_section, effective_translate_source_language,
-        finalize_translate_text_response, normalize_aux_quality,
-        normalize_subscriber_summary_input, normalize_subscriber_summary_length,
-        normalize_subscriber_summary_type, parse_assistant_prompt_stream,
-        parse_subscriber_summarize_stream, parse_translate_detect_value, resolve_news_category,
-        validate_translate_request,
+        extract_set_cookie_value, fake_header_map, finalize_translate_text_response,
+        normalize_aux_quality, normalize_subscriber_summary_input,
+        normalize_subscriber_summary_length, normalize_subscriber_summary_type,
+        parse_assistant_prompt_stream, parse_subscriber_summarize_stream,
+        parse_translate_detect_value, resolve_news_category, validate_translate_request,
     };
     use crate::auth::normalize_session_token;
     use crate::types::SubscriberSummarizeRequest;
@@ -2010,6 +1924,30 @@ mod tests {
         assert!(error.to_string().contains("explicit target language code"));
     }
 
+    #[test]
+    fn extracts_translate_session_from_set_cookie_headers() {
+        let headers = fake_header_map(&[
+            "translate_language=en; Max-Age=31536000; Path=/; HttpOnly; Secure; SameSite=Lax",
+            "translate_session=abc.def.ghi; Path=/; Expires=Wed, 18 Mar 2026 23:41:41 GMT; HttpOnly; Secure; SameSite=Lax",
+        ]);
+
+        let cookie = extract_set_cookie_value(&headers, "translate_session");
+
+        assert_eq!(cookie.as_deref(), Some("abc.def.ghi"));
+    }
+
+    #[test]
+    fn returns_none_when_set_cookie_name_is_missing() {
+        let headers = fake_header_map(&[
+            "translate_language=en; Max-Age=31536000; Path=/; HttpOnly; Secure; SameSite=Lax",
+        ]);
+
+        assert_eq!(
+            extract_set_cookie_value(&headers, "translate_session"),
+            None
+        );
+    }
+
     #[test]
     fn uses_detected_source_language_when_translate_from_is_auto() {
         let source = effective_translate_source_language("auto", &sample_detected_language());

From 7cc75af4d58b527e3ae2b465d90ddb162729c3e5 Mon Sep 17 00:00:00 2001
From: Microck <contact@micr.dev>
Date: Wed, 18 Mar 2026 22:07:21 +0000
Subject: [PATCH 5/7] fix(ci): satisfy clippy for translate

---
 src/api.rs  | 36 +++++++++++++++++++++---------------
 src/cli.rs  |  2 +-
 src/main.rs |  2 +-
 3 files changed, 23 insertions(+), 17 deletions(-)

diff --git a/src/api.rs b/src/api.rs
index 27b2907..bd596a9 100644
--- a/src/api.rs
+++ b/src/api.rs
@@ -447,11 +447,13 @@ pub async fn execute_translate(
                 &client,
                 &cookie_header,
                 &translate_session,
-                request.text.trim(),
-                &translated_text,
-                &effective_source_language,
-                &target_language,
-                translation_options.as_ref(),
+                TranslateSuggestionContext {
+                    source_text: request.text.trim(),
+                    target_text: &translated_text,
+                    source_language: &effective_source_language,
+                    target_language: &target_language,
+                    translation_options: translation_options.as_ref(),
+                },
             ),
         ),
         capture_optional_translate_section(
@@ -740,32 +742,36 @@ async fn execute_translate_text_alignments(
     decode_translate_json(response, "text alignments").await
 }
 
+struct TranslateSuggestionContext<'a> {
+    source_text: &'a str,
+    target_text: &'a str,
+    source_language: &'a str,
+    target_language: &'a str,
+    translation_options: Option<&'a TranslateOptionState>,
+}
+
 async fn execute_translate_suggestions(
     client: &Client,
     cookie_header: &str,
     translate_session: &str,
-    source_text: &str,
-    target_text: &str,
-    source_language: &str,
-    target_language: &str,
-    translation_options: Option<&TranslateOptionState>,
+    context: TranslateSuggestionContext<'_>,
 ) -> Result<TranslationSuggestionsResponse, KagiError> {
     let mut payload = Map::new();
     payload.insert(
         "originalText".to_string(),
-        Value::String(source_text.to_string()),
+        Value::String(context.source_text.to_string()),
     );
     payload.insert(
         "translatedText".to_string(),
-        Value::String(target_text.to_string()),
+        Value::String(context.target_text.to_string()),
     );
     payload.insert(
         "sourceLanguage".to_string(),
-        Value::String(source_language.to_string()),
+        Value::String(context.source_language.to_string()),
     );
     payload.insert(
         "targetLanguage".to_string(),
-        Value::String(target_language.to_string()),
+        Value::String(context.target_language.to_string()),
     );
     payload.insert("language".to_string(), Value::String("en".to_string()));
     payload.insert(
@@ -773,7 +779,7 @@ async fn execute_translate_suggestions(
         Value::String(translate_session.to_string()),
     );
 
-    if let Some(options) = translation_options {
+    if let Some(options) = context.translation_options {
         payload.insert(
             "translationOptions".to_string(),
             serde_json::to_value(options).map_err(|error| {
diff --git a/src/cli.rs b/src/cli.rs
index af01ad5..fbc990a 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -82,7 +82,7 @@ pub enum Commands {
     /// Prompt Kagi Assistant with subscriber session-token auth
     Assistant(AssistantArgs),
     /// Translate text through Kagi Translate using session-token auth
-    Translate(TranslateArgs),
+    Translate(Box<TranslateArgs>),
     /// Answer a query with Kagi's FastGPT API
     Fastgpt(FastGptArgs),
     /// Query Kagi's enrichment indexes
diff --git a/src/main.rs b/src/main.rs
index 9dd7552..5d05d37 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -144,7 +144,7 @@ async fn run() -> Result<(), KagiError> {
         }
         Commands::Translate(args) => {
             let token = resolve_session_token()?;
-            let request = build_translate_request(args)?;
+            let request = build_translate_request(*args)?;
             let response = execute_translate(&request, &token).await?;
             print_json(&response)
         }

From 26bca45d576f589a2166de7e3804215109550631 Mon Sep 17 00:00:00 2001
From: Microck <contact@micr.dev>
Date: Wed, 18 Mar 2026 22:15:47 +0000
Subject: [PATCH 6/7] test(translate): harden edge cases and refresh demo

---
 docs/demo-assets/translate.gif | Bin 9556 -> 9556 bytes
 images/demos/translate.gif     | Bin 9556 -> 9556 bytes
 src/api.rs                     | 152 ++++++++++++++++++++++++++-------
 src/search.rs                  |   8 --
 4 files changed, 122 insertions(+), 38 deletions(-)

diff --git a/docs/demo-assets/translate.gif b/docs/demo-assets/translate.gif
index 6495486e7751e3c8777fc722587e347899ff04ed..648d27174615517e2de8f5c75ede32a3ffa50b8b 100644
GIT binary patch
delta 20
ccmccOb;WCfDU$=^MspVy#uJ-sSZ*i)08zdNX#fBK

delta 20
bcmccOb;WCfDN`@QMspVy#>UMxEH@MYQ}G9G

diff --git a/images/demos/translate.gif b/images/demos/translate.gif
index 6495486e7751e3c8777fc722587e347899ff04ed..648d27174615517e2de8f5c75ede32a3ffa50b8b 100644
GIT binary patch
delta 20
ccmccOb;WCfDU$=^MspVy#uJ-sSZ*i)08zdNX#fBK

delta 20
bcmccOb;WCfDN`@QMspVy#>UMxEH@MYQ}G9G

diff --git a/src/api.rs b/src/api.rs
index bd596a9..10817c2 100644
--- a/src/api.rs
+++ b/src/api.rs
@@ -591,33 +591,7 @@ async fn bootstrap_translate_session(
         .await
         .map_err(map_transport_error)?;
 
-    match response.status() {
-        StatusCode::OK => {
-            let translate_session = extract_set_cookie_value(
-                response.headers(),
-                "translate_session",
-            )
-            .ok_or_else(|| {
-                KagiError::Auth(
-                    "translate bootstrap did not mint a translate_session cookie".to_string(),
-                )
-            })?;
-
-            Ok(TranslateBootstrapResult {
-                translate_session,
-                method: "reqwest(set-cookie bootstrap)".to_string(),
-            })
-        }
-        StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN => Err(KagiError::Auth(
-            "invalid or expired Kagi session token for Kagi Translate".to_string(),
-        )),
-        status if status.is_server_error() => Err(KagiError::Network(format!(
-            "Kagi Translate bootstrap server error: HTTP {status}"
-        ))),
-        status => Err(KagiError::Network(format!(
-            "unexpected Kagi Translate bootstrap response status: HTTP {status}"
-        ))),
-    }
+    resolve_translate_bootstrap(response.status(), response.headers())
 }
 
 async fn execute_translate_detect(
@@ -1383,6 +1357,36 @@ fn extract_set_cookie_value(headers: &header::HeaderMap, name: &str) -> Option<S
         })
 }
 
+fn resolve_translate_bootstrap(
+    status: StatusCode,
+    headers: &header::HeaderMap,
+) -> Result<TranslateBootstrapResult, KagiError> {
+    match status {
+        StatusCode::OK => {
+            let translate_session = extract_set_cookie_value(headers, "translate_session")
+                .ok_or_else(|| {
+                    KagiError::Auth(
+                        "translate bootstrap did not mint a translate_session cookie".to_string(),
+                    )
+                })?;
+
+            Ok(TranslateBootstrapResult {
+                translate_session,
+                method: "reqwest(set-cookie bootstrap)".to_string(),
+            })
+        }
+        StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN => Err(KagiError::Auth(
+            "invalid or expired Kagi session token for Kagi Translate".to_string(),
+        )),
+        status if status.is_server_error() => Err(KagiError::Network(format!(
+            "Kagi Translate bootstrap server error: HTTP {status}"
+        ))),
+        status => Err(KagiError::Network(format!(
+            "unexpected Kagi Translate bootstrap response status: HTTP {status}"
+        ))),
+    }
+}
+
 #[cfg(test)]
 fn fake_header_map(set_cookies: &[&str]) -> header::HeaderMap {
     let mut headers = header::HeaderMap::new();
@@ -1397,8 +1401,6 @@ fn fake_header_map(set_cookies: &[&str]) -> header::HeaderMap {
 
 #[derive(Debug, Deserialize)]
 struct ApiErrorBody {
-    #[allow(dead_code)]
-    meta: Option<serde_json::Value>,
     error: Option<Vec<ApiErrorItem>>,
 }
 
@@ -1620,7 +1622,8 @@ mod tests {
         normalize_aux_quality, normalize_subscriber_summary_input,
         normalize_subscriber_summary_length, normalize_subscriber_summary_type,
         parse_assistant_prompt_stream, parse_subscriber_summarize_stream,
-        parse_translate_detect_value, resolve_news_category, validate_translate_request,
+        parse_translate_detect_value, resolve_news_category, resolve_translate_bootstrap,
+        validate_translate_request,
     };
     use crate::auth::normalize_session_token;
     use crate::types::SubscriberSummarizeRequest;
@@ -1628,6 +1631,7 @@ mod tests {
         FastGptAnswer, NewsBatchCategory, NewsCategoryMetadata, Reference, Summarization,
         TranslateCommandRequest, TranslateDetectedLanguage, TranslateTextResponse,
     };
+    use reqwest::StatusCode;
     use serde_json::{Value, json};
     use std::sync::{
         Arc,
@@ -1930,6 +1934,37 @@ mod tests {
         assert!(error.to_string().contains("explicit target language code"));
     }
 
+    #[test]
+    fn rejects_empty_translate_text() {
+        let mut request = sample_translate_request();
+        request.text = "   ".to_string();
+
+        let error = validate_translate_request(&request).expect_err("empty text should fail");
+        assert!(error.to_string().contains("translate text cannot be empty"));
+    }
+
+    #[test]
+    fn rejects_empty_translate_source_language() {
+        let mut request = sample_translate_request();
+        request.from = "   ".to_string();
+
+        let error = validate_translate_request(&request).expect_err("empty source should fail");
+        assert!(
+            error
+                .to_string()
+                .contains("translate --from cannot be empty")
+        );
+    }
+
+    #[test]
+    fn rejects_empty_translate_target_language() {
+        let mut request = sample_translate_request();
+        request.to = "   ".to_string();
+
+        let error = validate_translate_request(&request).expect_err("empty target should fail");
+        assert!(error.to_string().contains("translate --to cannot be empty"));
+    }
+
     #[test]
     fn extracts_translate_session_from_set_cookie_headers() {
         let headers = fake_header_map(&[
@@ -1954,6 +1989,48 @@ mod tests {
         );
     }
 
+    #[test]
+    fn resolves_translate_bootstrap_from_success_cookie() {
+        let headers = fake_header_map(&[
+            "translate_session=abc.def.ghi; Path=/; HttpOnly; Secure; SameSite=Lax",
+        ]);
+
+        let bootstrap =
+            resolve_translate_bootstrap(StatusCode::OK, &headers).expect("bootstrap resolves");
+
+        assert_eq!(bootstrap.translate_session, "abc.def.ghi");
+        assert_eq!(bootstrap.method, "reqwest(set-cookie bootstrap)");
+    }
+
+    #[test]
+    fn rejects_translate_bootstrap_success_without_cookie() {
+        let headers = fake_header_map(&[]);
+
+        let error = resolve_translate_bootstrap(StatusCode::OK, &headers)
+            .expect_err("missing cookie should fail");
+
+        assert!(
+            error
+                .to_string()
+                .contains("did not mint a translate_session cookie")
+        );
+    }
+
+    #[test]
+    fn maps_translate_bootstrap_auth_statuses() {
+        let headers = fake_header_map(&[]);
+
+        for status in [StatusCode::UNAUTHORIZED, StatusCode::FORBIDDEN] {
+            let error =
+                resolve_translate_bootstrap(status, &headers).expect_err("auth status should fail");
+            assert!(
+                error
+                    .to_string()
+                    .contains("invalid or expired Kagi session token")
+            );
+        }
+    }
+
     #[test]
     fn uses_detected_source_language_when_translate_from_is_auto() {
         let source = effective_translate_source_language("auto", &sample_detected_language());
@@ -1966,6 +2043,21 @@ mod tests {
         assert_eq!(source, "es");
     }
 
+    #[test]
+    fn falls_back_to_requested_source_when_detected_iso_is_empty() {
+        let detected_language = TranslateDetectedLanguage {
+            iso: String::new(),
+            label: "Unknown".to_string(),
+            is_uncertain: true,
+            is_mixed: false,
+            alternatives: vec![],
+        };
+
+        let source = effective_translate_source_language("auto", &detected_language);
+
+        assert_eq!(source, "auto");
+    }
+
     #[test]
     fn backfills_translate_language_metadata() {
         let translation = TranslateTextResponse {
diff --git a/src/search.rs b/src/search.rs
index a296d3f..a7a636d 100644
--- a/src/search.rs
+++ b/src/search.rs
@@ -161,14 +161,6 @@ pub async fn execute_api_search(
     }
 }
 
-/// Legacy search function for backward compatibility.
-/// Consider using `search_with_lens` for lens support.
-#[allow(dead_code)]
-pub async fn search(query: &str, token: &str) -> Result<String, KagiError> {
-    let request = SearchRequest::new(query);
-    search_with_lens(&request, token).await
-}
-
 pub async fn execute_search(
     request: &SearchRequest,
     token: &str,

From 79bdb5b8ca293d989caefd387a7b1e3684bef230 Mon Sep 17 00:00:00 2001
From: Microck <contact@micr.dev>
Date: Wed, 18 Mar 2026 23:34:43 +0000
Subject: [PATCH 7/7] fix(translate): localize auxiliary metadata

---
 src/api.rs | 254 ++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 181 insertions(+), 73 deletions(-)

diff --git a/src/api.rs b/src/api.rs
index 10817c2..a8fc6d8 100644
--- a/src/api.rs
+++ b/src/api.rs
@@ -465,6 +465,7 @@ pub async fn execute_translate(
                 &translate_session,
                 request.text.trim(),
                 &translated_text,
+                &target_language,
                 translation_options.as_ref(),
             ),
         ),
@@ -730,45 +731,11 @@ async fn execute_translate_suggestions(
     translate_session: &str,
     context: TranslateSuggestionContext<'_>,
 ) -> Result<TranslationSuggestionsResponse, KagiError> {
-    let mut payload = Map::new();
-    payload.insert(
-        "originalText".to_string(),
-        Value::String(context.source_text.to_string()),
-    );
-    payload.insert(
-        "translatedText".to_string(),
-        Value::String(context.target_text.to_string()),
-    );
-    payload.insert(
-        "sourceLanguage".to_string(),
-        Value::String(context.source_language.to_string()),
-    );
-    payload.insert(
-        "targetLanguage".to_string(),
-        Value::String(context.target_language.to_string()),
-    );
-    payload.insert("language".to_string(), Value::String("en".to_string()));
-    payload.insert(
-        "session_token".to_string(),
-        Value::String(translate_session.to_string()),
-    );
-
-    if let Some(options) = context.translation_options {
-        payload.insert(
-            "translationOptions".to_string(),
-            serde_json::to_value(options).map_err(|error| {
-                KagiError::Parse(format!(
-                    "failed to serialize translate suggestion options: {error}"
-                ))
-            })?,
-        );
-    }
-
     let response = client
         .post(KAGI_TRANSLATE_SUGGESTIONS_URL)
         .header(header::COOKIE, cookie_header)
         .header(header::CONTENT_TYPE, "application/json")
-        .json(&Value::Object(payload))
+        .json(&build_translate_suggestions_payload(context, translate_session).map(Value::Object)?)
         .send()
         .await
         .map_err(map_transport_error)?;
@@ -782,42 +749,23 @@ async fn execute_translate_word_insights(
     translate_session: &str,
     source_text: &str,
     target_text: &str,
+    explanation_language: &str,
     translation_options: Option<&TranslateOptionState>,
 ) -> Result<WordInsightsResponse, KagiError> {
-    let mut payload = Map::new();
-    payload.insert(
-        "original_text".to_string(),
-        Value::String(source_text.to_string()),
-    );
-    payload.insert(
-        "translated_text".to_string(),
-        Value::String(target_text.to_string()),
-    );
-    payload.insert(
-        "target_explanation_language".to_string(),
-        Value::String("en".to_string()),
-    );
-    payload.insert(
-        "session_token".to_string(),
-        Value::String(translate_session.to_string()),
-    );
-
-    if let Some(options) = translation_options {
-        payload.insert(
-            "translation_options".to_string(),
-            serde_json::to_value(options).map_err(|error| {
-                KagiError::Parse(format!(
-                    "failed to serialize translate word-insight options: {error}"
-                ))
-            })?,
-        );
-    }
-
     let response = client
         .post(KAGI_TRANSLATE_WORD_INSIGHTS_URL)
         .header(header::COOKIE, cookie_header)
         .header(header::CONTENT_TYPE, "application/json")
-        .json(&Value::Object(payload))
+        .json(
+            &build_translate_word_insights_payload(
+                source_text,
+                target_text,
+                explanation_language,
+                translate_session,
+                translation_options,
+            )
+            .map(Value::Object)?,
+        )
         .send()
         .await
         .map_err(map_transport_error)?;
@@ -1296,6 +1244,89 @@ fn build_translate_payload(
     Value::Object(payload)
 }
 
+fn build_translate_suggestions_payload(
+    context: TranslateSuggestionContext<'_>,
+    translate_session: &str,
+) -> Result<Map<String, Value>, KagiError> {
+    let mut payload = Map::new();
+    payload.insert(
+        "originalText".to_string(),
+        Value::String(context.source_text.to_string()),
+    );
+    payload.insert(
+        "translatedText".to_string(),
+        Value::String(context.target_text.to_string()),
+    );
+    payload.insert(
+        "sourceLanguage".to_string(),
+        Value::String(context.source_language.to_string()),
+    );
+    payload.insert(
+        "targetLanguage".to_string(),
+        Value::String(context.target_language.to_string()),
+    );
+    payload.insert(
+        "language".to_string(),
+        Value::String(context.target_language.to_string()),
+    );
+    payload.insert(
+        "session_token".to_string(),
+        Value::String(translate_session.to_string()),
+    );
+
+    if let Some(options) = context.translation_options {
+        payload.insert(
+            "translationOptions".to_string(),
+            serde_json::to_value(options).map_err(|error| {
+                KagiError::Parse(format!(
+                    "failed to serialize translate suggestion options: {error}"
+                ))
+            })?,
+        );
+    }
+
+    Ok(payload)
+}
+
+fn build_translate_word_insights_payload(
+    source_text: &str,
+    target_text: &str,
+    explanation_language: &str,
+    translate_session: &str,
+    translation_options: Option<&TranslateOptionState>,
+) -> Result<Map<String, Value>, KagiError> {
+    let mut payload = Map::new();
+    payload.insert(
+        "original_text".to_string(),
+        Value::String(source_text.to_string()),
+    );
+    payload.insert(
+        "translated_text".to_string(),
+        Value::String(target_text.to_string()),
+    );
+    payload.insert(
+        "target_explanation_language".to_string(),
+        Value::String(explanation_language.to_string()),
+    );
+    payload.insert(
+        "session_token".to_string(),
+        Value::String(translate_session.to_string()),
+    );
+
+    if let Some(options) = translation_options {
+        payload.insert(
+            "translation_options".to_string(),
+            serde_json::to_value(options).map_err(|error| {
+                KagiError::Parse(format!(
+                    "failed to serialize translate word-insight options: {error}"
+                ))
+            })?,
+        );
+    }
+
+    Ok(payload)
+}
+
 fn insert_optional_string(payload: &mut Map<String, Value>, key: &str, value: Option<&str>) {
     if let Some(value) = value {
         payload.insert(key.to_string(), Value::String(value.to_string()));
@@ -1616,14 +1647,15 @@ pub struct KagiEnvelope<T> {
 #[cfg(test)]
 mod tests {
     use super::{
-        ApiErrorBody, KagiEnvelope, build_translate_option_state, build_translate_payload,
-        capture_optional_translate_section, effective_translate_source_language,
-        extract_set_cookie_value, fake_header_map, finalize_translate_text_response,
-        normalize_aux_quality, normalize_subscriber_summary_input,
-        normalize_subscriber_summary_length, normalize_subscriber_summary_type,
-        parse_assistant_prompt_stream, parse_subscriber_summarize_stream,
-        parse_translate_detect_value, resolve_news_category, resolve_translate_bootstrap,
-        validate_translate_request,
+        ApiErrorBody, KagiEnvelope, TranslateSuggestionContext, build_translate_option_state,
+        build_translate_payload, build_translate_suggestions_payload,
+        build_translate_word_insights_payload, capture_optional_translate_section,
+        effective_translate_source_language, extract_set_cookie_value, fake_header_map,
+        finalize_translate_text_response, normalize_aux_quality,
+        normalize_subscriber_summary_input, normalize_subscriber_summary_length,
+        normalize_subscriber_summary_type, parse_assistant_prompt_stream,
+        parse_subscriber_summarize_stream, parse_translate_detect_value, resolve_news_category,
+        resolve_translate_bootstrap, validate_translate_request,
     };
     use crate::auth::normalize_session_token;
     use crate::types::SubscriberSummarizeRequest;
@@ -2161,6 +2193,43 @@ mod tests {
         );
     }
 
+    #[test]
+    fn localizes_translate_suggestions_payload_to_target_language() {
+        let payload = build_translate_suggestions_payload(
+            TranslateSuggestionContext {
+                source_text: "Bonjour tout le monde",
+                target_text: "みなさん、こんにちは",
+                source_language: "fr",
+                target_language: "ja",
+                translation_options: None,
+            },
+            "translate-session",
+        )
+        .expect("payload should build");
+
+        assert_eq!(
+            payload.get("language"),
+            Some(&Value::String("ja".to_string()))
+        );
+    }
+
+    #[test]
+    fn localizes_translate_word_insights_payload_to_target_language() {
+        let payload = build_translate_word_insights_payload(
+            "Bonjour tout le monde",
+            "みなさん、こんにちは",
+            "ja",
+            "translate-session",
+            None,
+        )
+        .expect("payload should build");
+
+        assert_eq!(
+            payload.get("target_explanation_language"),
+            Some(&Value::String("ja".to_string()))
+        );
+    }
+
     #[test]
     fn normalizes_aux_quality_values() {
         assert_eq!(normalize_aux_quality(None), None);
@@ -2271,4 +2340,43 @@ mod tests {
         assert!(response.word_insights.is_none());
         assert!(response.warnings.is_empty());
     }
+
+    #[tokio::test]
+    #[ignore = "requires live KAGI_SESSION_TOKEN"]
+    async fn live_translate_localizes_auxiliary_metadata_for_non_english_targets() {
+        let token = live_translate_session_token().expect("set KAGI_SESSION_TOKEN for live tests");
+        let request = TranslateCommandRequest {
+            text: "Bonjour tout le monde".to_string(),
+            to: "ja".to_string(),
+            ..sample_translate_request()
+        };
+
+        let response = super::execute_translate(&request, &token)
+            .await
+            .expect("live translate should succeed");
+
+        let suggestions = response
+            .translation_suggestions
+            .as_ref()
+            .expect("suggestions should be present for ja target");
+        let insights = response
+            .word_insights
+            .as_ref()
+            .expect("word insights should be present for ja target");
+
+        assert!(
+            suggestions
+                .suggestions
+                .iter()
+                .any(|entry| !entry.label.is_ascii()),
+            "expected at least one localized suggestion label"
+        );
+        assert!(
+            insights
+                .insights
+                .iter()
+                .any(|entry| !entry.r#type.is_ascii()),
+            "expected at least one localized insight type"
+        );
+    }
 }