Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(i18n): explain how to translate copy that JS builds instead of markup

nirholas23bfd3b524a6
diff --git a/docs/i18n.md b/docs/i18n.md
index 9b96d2ccb..03a39583c 100644
--- a/docs/i18n.md
+++ b/docs/i18n.md
@@ -71,6 +71,53 @@ npm run i18n:extract -- --prune # drop keys no element references anymore
Existing values are preserved by default, so re-running never clobbers a reviewed
string. Collisions (same key, different English in two files) fail the command.
+### Copy that JS builds, not markup
+
+The extractor reads `data-i18n` attributes, so it sees every static page and none
+of the copy a module assembles at runtime. That gap is real: the connected-home
+lane renders its rooms, its devices, its refusals, its confirmation and every
+spoken announcement from live data, and none of it has markup to annotate. Those
+call sites go through a tiny bridge instead
+([`src/home/i18n-home.js`](../src/home/i18n-home.js)), where the English argument
+IS the source value, exactly as an element's own text is for an annotated tag:
+
+```js
+import { plural, t } from './i18n-home.js';
+
+t('home_floorplan.saved_title', 'Floorplan saved');
+plural('home_floorplan.loose_count', n, '{{count}} device not in a room', '{{count}} devices not in a room');
+```
+
+`npm run i18n:home` ([`scripts/i18n-home-keys.mjs`](../scripts/i18n-home-keys.mjs))
+reads those call sites and reports the difference against `en.json`; `--write`
+applies it. Run it after adding a string, before `i18n:translate`, or the key
+never reaches a translator:
+
+```bash
+npm run i18n:home # report drift, exit 1 if any
+npm run i18n:home -- --write # add and update keys in en.json
+```
+
+**User data is never part of a source string.** A room name, an area name, a
+scene name, a device name, an address somebody pasted and a message their own
+Home Assistant returned are their words, not ours. They are passed as
+interpolated values, which the masker already protects byte for byte:
+
+```js
+t('home_floorplan.filed_title', '{{device}} is in {{room}} now', { device: entityId, room: nameOf(areaId) });
+```
+
+and never as `` t('...', `${entityId} is in ${nameOf(areaId)} now`) ``, which
+would put somebody's "Nursery" into the source catalog and hand it back to them
+machine-translated. `i18n:home` refuses any source value that interpolates a
+template expression, so the rule is mechanical rather than remembered.
+
+Two things do **not** belong in the catalog at all. Relative times
+(`relativeAge` in the same bridge) go through `Intl.RelativeTimeFormat`, and
+numbers through `Intl.NumberFormat`, because an English `s` appended in code is
+the wrong plural in most of these languages and several need forms English has
+no word for. The browser already ships every rule.
+
## 3. Translate
```bash
@@ -154,6 +201,20 @@ billing enforcement against the whole GCP project, so every Vertex model in ever
region returns it and no amount of re-authenticating helps; the fix is on the
billing account. `402` is the balance. `401` really is the credential.
+Two more failures abort rather than degrade, and both cost a catalog before they
+did. A GCP credential that exists but no longer refreshes (this workspace's
+Application Default Credentials, once its refresh token was revoked) used to
+escape the Vertex token path as an ordinary error and route every key into the
+English fallback; it is now a config error that names both the credential's
+reason and `gcloud`'s. And a 5xx that outlives its whole backoff budget is
+treated exactly like a 429 that does: a gateway that is down is a property of the
+backend, not of the string being translated, and no amount of halving the chunk
+brings it back. On 2026-09-09 the `threews` proxy answered
+`502 {"error":"upstream_error","status":403}` and then
+`503 {"error":"provider_unavailable"}` on every request because its own free-tier
+chain was exhausted, and the run walked an entire Arabic catalog baking English
+one key at a time, printing a warning per key, heading for exit 0.
+
`i18n:backfill` (below) exists to clean up catalogs damaged by this before the
guard existed.