# 15 — I18N / LAZY LOCALE GUARD
> snapshot: 2026-07-08. Durable rule for localization work after Wiki/Truth Court exposed an all-locale scope gap.

The app has roughly 100+ locales and a large generated i18n corpus. Treat localization as a scale-sensitive subsystem, not as harmless text editing.

The failure mode is expensive: one eager import can put every locale into the main bundle, slow Cloud Build beyond the normal window, and make some languages crash at runtime.

## 1. Prime Directive
Preserve lazy loading.

Do not import all locale files, generated dictionaries, message packs, or locale registries into:
- app/layout or root providers;
- top-level client components;
- shared barrels such as `index.ts`;
- route handlers that only need one locale;
- feature modules that render for every user.

If a task needs a locale, load only the active locale or the exact checked locale. If a helper must list supported locales, keep it as metadata only; do not make it pull every message object into the runtime path.

## 2. Routing
Use this routing before assigning workers.

| Work type | Route | Notes |
|---|---|---|
| Copy-only translation for known keys in existing locale files | cheap/translation worker allowed | Only after confirming no loader/registry/bundle changes. |
| New feature strings for one feature | standard unless pure copy fill | Needs key inventory and fallback behavior. |
| All-locale expansion across 100+ languages | plan first, then cheap translation shards | Requires xhigh/lead plan before bulk workers. |
| Lazy loader, registry, fallback policy, generated key tooling | standard or premium review | This is runtime/build-shape work, not translation. |
| Locale crash, build-time spike, bundle growth | premium/lead review | Treat as global blast-radius. |

Do not route all-locale work directly to many cheap agents until the plan ticket defines key list, output files, and validation. Cheap workers may fill translations; they must not invent loader architecture.

## 3. Required Plan For All-Locale Work
Before touching 100+ languages, the parent ticket must record:

1. Key inventory: exact namespace/key list and source English strings.
2. Glossary: product terms that must stay consistent (`Brain Wiki`, `Truth Court`, `source`, `quote`, `freshness`, etc.).
3. Lazy path: which file/function loads the active locale and proof that only the active locale is loaded.
4. Fallback policy: what happens when a key is missing and which locale is canonical fallback.
5. Build guard: how the worker proves main bundle/build time did not jump.
6. Locale smoke set: at minimum English plus currently user-visible languages (`uk`, `ru`) and one historically risky locale such as `pt-BR`.
7. Owner-facing acceptance: screenshots/strings in one real feature, not just generated files.

## 4. Worker Do / Do Not
Do:
- keep diffs scoped to locale files when the task is translation-only;
- preserve key parity across locales;
- use existing i18n helpers and namespace conventions;
- add missing keys through the existing generated-data path;
- run focused key-parity and smoke tests if they exist;
- document which locales were generated by machine translation and which were manually checked.

Do not:
- create a new global `import * as messages from ...` pattern;
- build a giant object of every locale in a root module;
- move lazy-loaded locale data into an eager shared barrel;
- run full project `tsc` or broad dev servers on the M1 to validate translations;
- claim all-locale support because ru/uk passed;
- close a localization ticket without checking at least one non-ru/uk locale.

## 5. Proof Checklist
For a feature-local i18n patch:
- changed files are locale/key files plus at most narrow feature callsites;
- no top-level import of `i18n/generated`, all messages, or all locales was added;
- `en`, `uk`, `ru`, and one non-ru/uk locale render without English UI fallback for the changed feature;
- missing-key behavior is intentional and logged in the report.

For all-locale expansion:
- parent plan accepted;
- generated keys have parity;
- cheap translation shards report their assigned locale ranges;
- a reviewer checks glossary terms;
- build/steward sees no abnormal build-time or bundle-shape jump before live acceptance.

## 6. Build-Time Red Flags
Escalate immediately if any of these happen after locale/i18n work:
- Cloud Build goes past the normal 7-10 minute range without infra reason;
- app starts only in English for most locales;
- switching to a locale crashes the app;
- root layout/provider diff imports locale data;
- generated i18n directory appears in an unrelated feature bundle.

The fix is not to raise timeouts first. The fix is to restore lazy loading, then re-run focused proof.

## 7. Ticket Labels
Recommended labels:
- `i18n`, `localization`, `lazy-i18n-preserve` for all localization work;
- `build-size-risk` for loader/registry/all-locale work;
- `translation-only` only when the diff is restricted to strings;
- `no-cheap-until-plan` for all-locale expansions before key inventory;
- `locale-smoke-required` when a user-facing feature has new strings.