Translator service API: GET/POST /_api/translate/{lang}

docs/localization.md

@@ -213,8 +213,11 @@ def get_translation(path, lang, data) -> Translation | None:
 ### Explicitly out of scope for phase 2
 
 - The machine translation itself: chunking output goes in, translated chunks
-  come back. A background job writes `trans` entries; this doc only defines
-  the storage key (`chunk_hash:lang`) and the merge semantics.
+  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).
 - 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

@@ -91,7 +91,12 @@ 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`.
+  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.
 - **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: