atelier/domains/i18n/locale-resources.md

# Locale Resources — Derived Rules

> Derives from `domains/i18n/first-principles.md`. Covers P1 (Source
> Language is a Locale), P2 (Locale Identifiers Standardized), P3
> (Resources External, Not Inline), P4 (Plural/Gender Parameterized),
> and P10 (Translation Reversible and Versioned). Referenced by
> `formatting.md` (strings the formatter resolves) and
> `rtl-bidi.md` (the `dir` the resource layer carries).

## Resources are the Boundary (P3 Resources are External, Not Inline)

- User-facing strings live in locale resource files, addressed by
  key. Code references a key; the resource layer resolves the key to
  the active locale. The source language is itself a locale
  (`en-US`), not a fallback baked into code.
- String concatenation in code (`"Welcome, " + name + "!"`) is the
  cardinal violation: it bakes in source-language word order and
  breaks for every locale with different grammar. Replace every
  concatenation with a parameterized message:
  `t("welcome", { name })`.
- The resource is the single place a string lives. Editing a string
  in code instead of the resource is a locality violation (C4): the
  string and its locale consequences now live apart.

## Resource File Formats

| Format | Shape | When | Notes |
|--------|-------|------|-------|
| `.po` / `.pot` | gettext; msgid → msgstr, plural headers | Server-side, GNU ecosystem, PHP/Python/C | Mature tooling (`xgettext`, `msgmerge`); supports plural categories via header |
| JSON (flat or namespaced) | `{ "key": "value" }` per locale | JS/web, i18next, FormatJS | Simple, machine-readable, but no native plural support — wrap with ICU MessageFormat |
| Fluent `.ftl` | Mozilla FTL; asymmetric, resolver-driven | Browser-grade l10n, asymmetric translations | One message can resolve differently per locale without code changes; supports attributes, selectors |
| ICU Resource Bundle | ICU binary/text resources | ICU-native, JVM, C++ | Tightest integration with ICU formatting/CLDR; steeper tooling |

- None is advocated over the others. The choice is ecosystem fit,
  not correctness. All four satisfy P3/P4 when used as the boundary.
- A custom format (a hand-rolled `.csv` of strings) is a violation:
  it is unsupported by standard tooling, has no plural grammar, and
  cannot compose with `formatting.md`'s ICU layer.

## Key Naming and Namespaces (P2 Locale Identifiers Standardized)

- Locale identifiers are BCP 47 tags (`en-US`, `ar-EG`, `zh-Hans-CN`).
  No ad-hoc codes. The resource file is named for its locale:
  `en-US.json`, `ar-EG.po`, `ftl/ar-EG/main.ftl`.
- Message keys are stable, semantic, and structured — not prose.
  `checkout.cart.item_count` not `"You have 3 items in your cart"`.
  A key that is the source string (`t("You have items")`) breaks the
  moment the source copy is edited; the key must outlive the copy.
- Namespaces segment by surface (`checkout.*`, `errors.*`, `onboarding.*`)
  so that a locale can be loaded incrementally and so that key
  collisions across surfaces are impossible. A flat namespace with
  thousands of keys is a C2 (Clarity) violation waiting to happen.

## Fallback Chains

- The fallback chain is explicit: requested locale → language-only
  (`en` from `en-GB`) → default locale → key itself (last resort).
  The default locale is declared once, not re-derived in every call
  site.
- A missing key in the requested locale falling back silently to the
  source locale is a P3 violation: the user is silently shown the
  developer's locale, which is not the locale they asked for. Missing
  keys must be observable (see `testing-i18n.md`).
- Fallback is a property of the resource layer, not of individual
  components. A component that re-implements fallback is duplicating
  a contract (C6 Composability violation).

## Plural and Gender in Resources (P4 Plural/Gender Parameterized)

- Plural variants live in the resource, selected by the formatter,
  parameterized by the count. The code passes the count; the resource
  carries the variants; the formatter picks the right one per the
  locale's CLDR plural rules.

  ```
  // JSON + ICU MessageFormat (FormatJS / i18next)
  {
    "cart.item_count": "{count, plural, one {# item} other {# items}}"
  }
  // ar-EG.json — six plural categories per CLDR
  {
    "cart.item_count": "{count, plural, zero {لا عناصر} one {عنصر واحد} two {عنصران} few {# عناصر} many {# عنصرًا} other {# عنصر}}"
  }
  ```

- `if (n == 1)` branching in code is a violation regardless of
  language. Arabic has six plural categories; Russian has three;
  English has two. A two-branch `if` encodes exactly one locale's
  rules and is wrong for every other.

## Extraction Tooling (P1, P3)

- Strings are extracted mechanically (e.g. `xgettext`, `i18next-
  parser`, FormatJS babel plugin), not by hand-tagging. Mechanical
  extraction produces a `.pot` template that translators work from;
  the template is regenerated on every build.
- A string that cannot be extracted (built at runtime from
  fragments) is a P3 violation: it is invisible to the pipeline. If
  the extractor cannot see it, neither can the translator.
- The extracted template is versioned (`P10`): the diff between
  templates is the change in translatable surface. A template that
  is not committed is a contract that is not reviewable.

## Versioning and Rollback (P10 Translation Reversible and Versioned)

- Resource files are committed to git alongside code. A bad
  translation is a `git revert` of the resource, not a hot-patch over
  the translator's work. Every locale resource has history,
  provenance (which translator / which service produced which
  commit), and a rollback path.
- A locale resource that is generated by a translation service and
  committed without review is a P10 violation: the resource is
  versioned but the provenance is opaque. Review the diff the same
  way you review a code diff.

## What Violates Locale-Resource Discipline

| Violation | Principle |
|-----------|-----------|
| `t("You have " + n + " items")` concatenation | P3 Resources are External, Not Inline |
| A custom `.csv` string store instead of a standard format | P3 Resources are External, Not Inline |
| Locale file named `english.json` not `en-US.json` | P2 Locale Identifiers are Standardized |
| `if (n == 1) { t("item") } else { t("items") }` in code | P4 Plural and Gender are Parameterized |
| A key equal to the source string (`t("Welcome back")`) | P2 / P10 — keys must outlive copy |
| Silent fallback to the source locale with no signal | P3 Resources are External, Not Inline |
| A runtime-built string the extractor cannot see | P3 Resources are External, Not Inline |
| Resource files committed by a bot with no human review | P10 Translation is Reversible and Versioned |

## Relationship to Other Domains

- `domains/uiux/copywriting.md` — copy lives in resources; UI
  microcopy is the source content the resource layer carries.
- `domains/api/error-responses.md` — API error messages are locale-
  resource keys resolved at the boundary, not inline strings.
- `domains/data/schema-design.md` — locale identifiers and resource
  shapes are a data contract; treat them as schema.
- `domains/i18n/formatting.md` — the formatter resolves the
  parameterized message this layer produces.