Localization Contract Repair

1. Repair decision

Decision: CROSS-LAYER LOCALIZATION CONTRACT DRIFT FOUND — SAFE LOCAL PATCH AVAILABLE; translation quality and deployed locale behavior remain unverified.

2. Scope and boundary

Reviewed: next-intl config, English/German/French/Polish catalogs, route middleware, format helpers, namespace loaders, extraction scripts, tests, fixtures, docs, and runbook.

Not accessed: production users, translation vendors, live localization platforms, deployed catalog state, analytics, or deployment systems.

3. Localization contract source register

4. Canonical repository contract

Fallback precedence, source-locale authority, stale-key deletion, and supported aliases are

OWNER DECISION REQUIRED.

Safe structure

• one locale registry defines canonical tags and accepted aliases;
• one message-schema extractor records key, namespace, placeholders, ICU argument types, plural/select branches, and rich-text slots;
• catalogs are validated against that schema without judging translation quality;
• SSR and client use one fallback resolver;
• namespace loading is explicit for first render and navigation;
• formatting helpers consume canonical locale identity;
• stale-key detection reports candidates rather than deleting them automatically.

5. Drift findings

F1 — Catalog population drift

German is missing 47 keys and French contains 63 keys outside the current reference population.

Repair: add parity checks that report missing and extra keys by namespace. Do not auto-fill German text or delete French entries.

F2 — Placeholder mismatch

billing.invoice_count uses {count} in code while one locale expects {total}.

Repair: compare placeholder signatures across locales and fail validation on mismatches. Do not rewrite translated prose.

F3 — Polish plural coverage

Affected Polish messages expose only one/other.

Repair: parse ICU plural branches and validate structural coverage against the runtime’s locale categories. Do not generate translations for missing branches.

F4 — Fallback divergence

SSR falls back to English while the browser falls back to German.

Repair: centralize fallback resolution in a shared module. Keep the actual fallback order as owner-approved configuration.

F5 — Lazy namespace race

settings can render before its namespace loads.

Repair: make namespace dependencies explicit at route boundaries and require readiness before localized rendering. Add cold- and warm-navigation tests.

F6 — Locale identity drift

Routing and formatting helpers use different locale tags.

Repair: normalize aliases once, then pass the canonical tag to routing, Intl formatting, SSR, and tests. Preserve the originally requested tag separately if needed.

6. Safe patch plan

No translation generation, live catalog mutation, migration, or deployment.

7. Deterministic test matrix

1. Required namespaces report missing keys by locale.
2. Extra keys are reported separately.
3. {count} versus {total} fails signature validation.
4. Matching placeholders pass regardless of translated word order.
5. Polish plural fixtures cover runtime-required categories represented by the selected ICU library.
6. Server and client resolve the same fallback chain.
7. Cold navigation to settings waits for its namespace.
8. Warm navigation does not render raw keys.
9. Locale aliases normalize consistently.
10. Date, number, and currency helpers use the canonical locale.
11. SSR and hydration use the same namespace set.
12. Tests call no live translation services.

8. Verification steps

Run

• npm test -- localization-contract
• npm test -- locale-routing
• npm test -- namespace-loading
• npm run typecheck
• npm run lint
• npm run build

Run the local catalog validator and inspect missing keys, extras, placeholder signatures, plural/select branches, unresolved aliases, and SSR/client namespace differences.

9. Production boundary

Unknown: deployed catalog versions, translation-management state, CDN caching, legacy locale URLs, old browser bundles, and whether missing German or stale French keys are intentional.

Production work needs separate translation review, compatibility review, rollout, monitoring, and rollback.

10. Human approval request

Safe now: locale registry structure, schema extraction, parity checks, placeholder validation, shared fallback plumbing, namespace readiness, formatting alignment, tests, and docs.

Decisions required: source locale, fallback order, supported aliases, stale-key deletion, intentionally untranslated content, Polish message updates, legacy compatibility, and rollout.

Status: PATCH READY FOR LOCAL REVIEW — TRANSLATION CONTENT, PRODUCT LANGUAGE POLICY, LIVE CATALOGS, AND DEPLOYED LOCALE BEHAVIOR NOT VERIFIED

11. Suggested commit message

fix(i18n): align catalog schema and locale resolution