Document the translator WebSocket API and reference client

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: