plan: localizing the web UI, and the scanner that sizes it

not built. an execution plan written to be handed to an agent who did not have the conversation, so it carries the reasons and not just the steps. what it found: there is already a hand-rolled i18n package with typed keys, two catalogs and 46 keys — and exactly three components using it. against 884 distinct hardcoded strings across 436 files. so the system is not missing, it is 5% deployed, and that gap is the job. the decisions worth arguing with are D1 and D6. D1: the server should never emit user-facing prose, it returns a stable code and the UI owns every word — with the trap that a code must not leak more than the prose did, or a deliberately vague 403 becomes an enumeration oracle. D6: catalogs per workspace rather than one file, because one 900-key en.json is a merge conflict on every parallel edit. the scanner reproduces the numbers in the doc and doubles as the guard once an area reaches zero. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-23 01:57:22 +00:00
parent dee0b89bd7
commit e6f1388aa6
3 changed files with 509 additions and 0 deletions
@@ -477,6 +477,10 @@ explaining why it was safe.
  owner-only while the plugin itself stays grantable. What the proxy should pass (`isOwner` and a level,
  never the role name), why declaring owner-only paths in the manifest beats trusting every plugin to
  remember, and the credential-resolution work that has to land first
+- `docs/localization.md` — **plan, not built**, with a working 5% skeleton already in the tree: taking the
+  web UI to more than one language. What exists and what it cannot do yet, why the server should return
+  error CODES rather than prose (and why a code must not leak more than the prose it replaced), the key
+  naming convention, and the four phases. Read before adding a user-facing string
 - `docs/secret-store.md` — **design, not built**: moving the encryption and signing keys out of `.env`
  into a SQLite store, why they cannot live in Postgres, and key rotation. Also records the core/plugin
  split it assumes — light plus `officer-headscale` is the core; Vaultwarden and the wallet are plugins