i18n-Ready (bilingual by design, not by patch)
Design for the longest honest string; translate meaning, not words. English/Spanish is the worked pair; the method generalizes.
Make a locale contract before translating or resizing
Record a locale contract before resizing/translating:
| Boundary | Required decision/evidence |
|---|---|
| locale/reader | concrete BCP 47 tag, fallback/owner, formality and regional vocabulary |
| content | whole-message keys, variables/plurals, protected legal/safety language |
| mechanics | formats and data source for date/time zone/number/currency/address/name |
| stress/direction | longest approved fixture by surface; current dir, RTL/bidi/logical-property path |
Never invent locale, idiom, translation, or formality; pending source/approval is structural readiness only.
The decision order
- Set
<html lang>and inlinelangswitches. - Test the longest approved fixture; text containers/content-sized controls avoid fixed widths. Intentional truncation exposes full text.
- Use logical inline/block properties for RTL and
Intlwith real locales for formats. - Re-express native voice/idiom/formality (including tú/usted); do not calque.
- For an in-product language choice, self-label/persist the control, update
lang, and providehreflang/per-locale metadata for indexed locale routes where applicable.
Non-negotiables
- Correct language attributes, longest-string-safe layout, and logical CSS—no text images or concatenated fragments.
- Explicit-locale
Intl; native Spanish with consistent formality, accents/ñ/¿¡, andcognitive-a11ypass per locale.
Verify meaning, layout, and mechanics separately
Keep three lanes distinct: meaning (native/approved intent, formality, idiom,
plural/protected wording); layout (longest fixtures in real views/states;
pseudo-localization finds width defects only); mechanical (Intl, time zones, currencies,
inputs, lang/dir, logical properties, toggle persistence). A date changing calendar day
is a data defect.
Repair order and evidence
Require locale contract and approved fixtures first. Repair boundaries, formats, keys, wrapping, logical CSS/bidi, and native voice; record separate three-lane checks per locale/surface with reviewer/source authority.
Self-check (per language, before shipping)
- Correct
lang, logical CSS, longest-fixture layout, and no fragmented/image text? - Explicit-locale
Intl, native/formality-safe copy, and per-language cognitive pass? - Honest persisted toggle/metadata where applicable, with separate meaning/layout/mechanical proof?
How to deliver
Deliver tag/fallback, formality source, longest fixture, three-lane evidence, bidi/format
risk, and owner. Keep locales in DESIGN-SYSTEM.md; hand off voice/type/accessibility.
Reference files
references/decision-records.md— meta-patterns + ADR rules.assets/locale-fixtures.json— EN/ES keys, formats, and longest-string fixtures.
Contract (generated)
Canonical detail: contract.json.
- Route: A UI or copy system must survive English/Spanish expansion, locale formatting, bidi, or locale-native voice.; avoid: The request is only English copy polish or a non-locale accessibility defect.
- Exclude: Do not translate word-for-word when locale-native meaning is required. (+1 in contract.json)
- Stop / handoff: Stop when supported locales or source meaning are undefined. (+1 in contract.json); receives [humanize-copy, responsive-layout, form-ux, improve-existing-website, web-typography] -> sends [a11y-pass, tastecheck-pass]
- Output: multilingual resilience repair ledger
- Evidence:
table_with_evidencewithstatus,reason,remediation,evidence,provenance.


