feat(translate): add text-mode Kagi Translate support

README.md

@@ -15,7 +15,7 @@
 
 ---
 
-`kagi` is a terminal CLI for Kagi that gives you command-line access to search, lenses, ask-page, 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, ask-page, 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 fallback, `search --lens`, filtered search, `ask-page`, `assistant`, `summarize --subscriber` |
+| `KAGI_SESSION_TOKEN` | base search fallback, `search --lens`, filtered search, `ask-page`, `assistant`, `translate`, `summarize --subscriber` |
 | `KAGI_API_TOKEN` | public `summarize`, `fastgpt`, `enrich web`, `enrich news` |
 | none | `news`, `smallweb`, `auth status`, `--help` |
 
@@ -140,6 +140,7 @@ for the full command-to-token matrix, use the [`auth-matrix`](https://kagi.micr.
 | `kagi news` | read Kagi News from public JSON endpoints |
 | `kagi assistant` | prompt Kagi Assistant, continue threads, and manage thread list/export/delete with a subscriber session token |
 | `kagi ask-page` | ask Kagi Assistant about a specific web page |
+| `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 |
@@ -220,6 +221,26 @@ kagi assistant thread list
 kagi assistant thread export <THREAD_ID>
 ```
 
+translate text and keep all text-mode extras:
+
+```bash
+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
+kagi translate "Bonjour tout le monde" --no-alternatives --no-word-insights --no-suggestions --no-alignments
+```
+
 use the subscriber summarizer:
 
 ```bash
@@ -247,7 +268,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 ask-page, the subscriber summarizer, assistant, and the public news feed:
+if you want a quick feel for the cli before installing it, this is the kind of output you get from translate, ask-page, the subscriber summarizer, assistant, and the public news feed:
+
+![translate demo](images/demos/translate.gif)
 
 ![summarize demo](images/demos/summarize.gif)
 
@@ -280,6 +303,3 @@ for the fuller install matrix and platform-specific setup, use the [installation
 ## license
 
 [mit license](LICENSE)
-
-### todo
-- add https://translate.kagi.com/

docs/api-coverage.md

@@ -13,6 +13,7 @@
 - **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 ...`
 - **Subscriber web Assistant thread list/open/delete/export flows** - implemented on the authenticated Assistant thread endpoints via `kagi assistant thread ...`
+- **Kagi Translate text mode** - implemented via `kagi translate ...` with runtime bootstrap from `KAGI_SESSION_TOKEN`
 
 ## Source of truth
 
@@ -29,10 +30,6 @@ This CLI also implements non-public or product-only seams:
 - subscriber web Assistant thread management 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 and runtime search filters are not documented on the official Search API. In this CLI they work through Kagi's live HTML/session flow using the `l`, `r`, `dr`, `from_date`, `to_date`, `order`, `verbatim`, and `personalized` query parameters.
@@ -41,7 +38,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 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 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`.
 - Assistant requires `KAGI_SESSION_TOKEN` and currently targets `/assistant/prompt`, `/assistant/thread_list`, `/assistant/thread_open`, `/assistant/thread_delete`, and `/assistant/<thread_id>/download`.
 - News uses `https://news.kagi.com/api/...` JSON endpoints and does not require auth.

docs/commands/translate.mdx

@@ -0,0 +1,260 @@
+---
+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.
+
+![Translate demo](/images/demos/translate.gif)
+
+## 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`.
+
+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`
+
+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=...'
+```
+
+## Bootstrap
+
+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
+
+### `<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`. `auto` is not accepted for the target language.
+
+### `--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": "reqwest(set-cookie bootstrap)",
+    "authenticated": true
+  },
+  "detected_language": {
+    "iso": "fr",
+    "label": "French"
+  },
+  "translation": {
+    "translation": "Hello everyone",
+    "source_language": "fr",
+    "target_language": "en"
+  },
+  "alternatives": {
+    "elements": []
+  },
+  "text_alignments": {
+    "alignments": []
+  },
+  "translation_suggestions": {
+    "suggestions": []
+  },
+  "word_insights": {
+    "insights": []
+  },
+  "warnings": []
+}
+```
+
+## Examples
+
+### Basic Translation to English
+
+```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
+
+### Bootstrap failure
+
+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
+
+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)