Document the translator WebSocket API and reference client

docs/localization.md

@@ -210,14 +210,38 @@ def get_translation(path, lang, data) -> Translation | None:
   updates `Data.chunks` / `node.chunks` — only genuinely new text lands in
   the kanta change diff (see docs/migrate.md).
 
+### Translator service API
+
+An external machine-translation service connects over WebSocket at
+`/_translate/{key}` — deliberately **not** under `/_api`: the SSO
+forward-auth does not cover that route, and the key in the path is the
+access control. The key is `Data.translate_key`, generated once at startup
+and surfaced to the admin in `GET /_api/settings` as `translate_key`. A
+wrong or empty key rejects the handshake (close-before-accept → HTTP 403).
+
+Frames are JSON-encoded tagged msgspec structs (`pagerite/translate.py`;
+`bytes` fields ride as base64):
+
+- `{"type": "hello", "langs": [...]}` — client greeting: the target
+  languages it handles (normalized to base subtags; `en`/empty dropped).
+- `{"type": "job", "lang", "items": [{key, text, path, kind}]}` — server
+  push: pending fragments (article titles and chunks), deduped by key.
+- `{"type": "result", "lang", "items": [{key, text}]}` — client reply:
+  translated fragments, matched to content by chunk key alone.
+
+The model is **push**, not polling: on `hello` the server sends everything
+pending per announced language; afterwards `_invalidate_pages()` (called by
+every content/translation write) schedules a delta push of newly pending
+items. Outstanding-item tracking is per connection, so a reconnecting client
+simply re-receives everything still pending. Results are stored into `trans`
+in one transaction and set `node.langs[lang]` on every article they touch
+(shared chunks make several pages gain a language from one fragment).
+
 ### Explicitly out of scope for phase 2
 
-- The machine translation itself: chunking output goes in, translated chunks
-  come back. The **service API exists** — `GET /_api/translate/{lang}` lists
-  pending items (`{"key", "text", "path", "kind"}`, key = base64 chunk hash),
-  `POST /_api/translate/{lang}` stores a batch (`{"items": [{key, text}]}`)
-  into `trans` and maintains `node.langs`; an external service does the
-  actual translating (gated by the /_api forward-auth like everything else).
+- The machine translation itself: the API above moves fragments in and out;
+  the translating is external. `scripts/translator.py` is the reference
+  client (Seed-X-PPO-7B only — its 28 languages are the ceiling).
 - Garbage collection of orphaned chunks/translations (see docs/migrate.md).
 - sitemap.xml per-language entries; translated UI chrome; per-language
   typographer options; multi-locale date/number formatting.

docs/migrate.md

@@ -52,6 +52,9 @@ class Node(msgspec.Struct, omit_defaults=True):
 
 class Data(msgspec.Struct):
     ...
+    #: API key gating the translator service WebSocket (/_translate/{key});
+    #: generated lazily at startup (see the lifespan in app.py).
+    translate_key: str = ""
     #: All original-language text, content-addressed: blake3(normalized)
     #: digest[:9] -> Markdown chunk. Shared by every article. Keys are
     #: bytes; kanta/msgspec base64-encode them at the JSON level.
@@ -90,13 +93,12 @@ that article rendering, `select_language`'s availability check, and hreflang
 alternate links never enumerate chunks. It is written by whoever writes
 translation data, in the same transaction:
 
-- **Translator job:** after writing `trans[h][lang]` entries for an
-  article's chunks (or its title), set `node.langs[lang] = True`. The
-  translation service API does both: `GET /_api/translate/{lang}` lists
-  pending items (titles + translatable chunks lacking an entry, deduped by
-  hash), `POST /_api/translate/{lang}` stores a batch into `trans`, sets
-  `langs` on every article that gained an entry and invalidates the page
-  cache — all in one transaction.
+- **Translator service:** the WebSocket API at `/_translate/{key}` (see
+  docs/localization.md) pushes pending fragments (titles + translatable
+  chunks lacking an entry, deduped by hash) and receives result batches;
+  storing a batch writes `trans[h][lang]` entries, sets
+  `node.langs[lang] = True` on every article that gained one and
+  invalidates the page cache — all in one transaction.
 - **Translated-view save:** appending the first patch for `f"{path}:{lang}"`
   sets `node.langs[lang] = True` (patches alone make the version exist).
 - **Removals:** deleting a patch or GC'ing translations re-derives the key: