# Oshun V1 Locale Coverage

Authoritative list of launch locales, the customer and admin surfaces each
covers, and the coverage tier. Companion to
`docs/launch/translation-workflow.md` and the runtime catalog at
`libs/oshun/i18n/`.

## Launch locales

| Locale  | Direction | Calendar  | Customer launch coverage                                                               | Admin launch coverage                        | Tier           |
| ------- | --------- | --------- | -------------------------------------------------------------------------------------- | -------------------------------------------- | -------------- |
| `en-US` | LTR       | Gregorian | Full shell + every domain + assistant + privacy + billing + offline + PWA              | Full admin shell + every operator workspace  | Launch-quality |
| `es-US` | LTR       | Gregorian | Shell, Tara, Arete, Veritas-MVP, assistant disclosures, support, billing               | Operator shell, support workspace            | Launch-quality |
| `fr-FR` | LTR       | Gregorian | Shell, Tara, Nisaba, Veritas (incl. source inspection), assistant disclosures          | Operator shell, support workspace            | Launch-quality |
| `de-DE` | LTR       | Gregorian | Shell, Tara, Veritas-MVP, Nisaba-MVP, assistant disclosures, billing                   | Operator shell                               | Launch-quality |
| `ar`    | RTL       | Gregorian | Shell, Tara, Nisaba reader, assistant disclosures, RTL smoke; minimum-viable assistant | Operator shell (LTR fallback for dense data) | Minimum-viable |
| `he`    | RTL       | Gregorian | Shell, Nisaba reader, assistant disclosures, RTL smoke                                 | Operator shell (LTR fallback)                | Minimum-viable |
| `ja-JP` | LTR       | Gregorian | Shell, Tara, Veritas-MVP, assistant disclosures, Nisaba reader for Japanese editions   | Operator shell                               | Launch-quality |
| `pt-BR` | LTR       | Gregorian | Shell, Tara, Veritas-MVP, Arete, assistant disclosures, billing                        | Operator shell, support workspace            | Launch-quality |

Customer profile preferences and language-switcher values use compact aliases
for backward compatibility with existing preference storage:

| Preference alias | Launch locale |
| ---------------- | ------------- |
| `en`             | `en-US`       |
| `es`             | `es-US`       |
| `fr`             | `fr-FR`       |
| `de`             | `de-DE`       |
| `ar`             | `ar`          |
| `he`             | `he`          |
| `ja`             | `ja-JP`       |
| `pt`             | `pt-BR`       |

Aliases outside this table are staging-only and are not customer-selectable in
V1.

Tier definitions:

- **Launch-quality**: every catalog key resolves directly (no fallback), every
  shell view passes RTL/expansion QA, every shared disclosure has T&S/privacy
  sign-off, the locale appears as a first-class option in the locale picker.
- **Minimum-viable**: every catalog key resolves directly, RTL/ expansion QA
  passes on the supported shell views, the locale appears in the locale picker
  with a note explaining the coverage limit (e.g., "Some content is shown in
  English"). Domains outside the listed coverage fall back to `en-US` per the
  documented chain.

## Fallback rules

- Requested locale → language-only → `en-US`. Implemented in
  `resolveFallbackChain` / `translate` in `libs/oshun/i18n/src/index.ts`.
- A fallback hit on the customer shell emits an analytics event for monitoring;
  a fallback hit on a launch-quality locale's shell is a bug.
- Disclosure and crisis-flow strings never fall back silently — those surfaces
  are gated by the catalog-coverage test and cannot ship with gaps.

## RTL and bidi

- Mirror layout, mirror direction-implying icons, preserve bidi isolation for
  customer-controlled strings.
- Default to western numerals; opt-in Arabic-Indic digits per content piece for
  `ar`.
- Punctuation set switches per locale; the shared shell components centralize
  this.

## Text-expansion QA

- Budget table is canonical in `LOCALE_EXPANSION_BUDGET`
  (`libs/oshun/i18n/src/index.ts`).
- Automated suite renders every shell view at the budget's synthetic length;
  truncation, overflow, or unintended wrap is a layout bug.
- Manual review additionally checks for line-break aesthetics on Asian-script
  locales (CJK) and on RTL locales.

## Date/time, calendar, number, currency, region

- Date/time formatting goes through `Intl.DateTimeFormat` with the customer's
  timezone — never operator timezone, never browser default when the customer
  has set one.
- Currency formatting goes through `Intl.NumberFormat` per locale; the
  customer's billing currency is canonical for billing surfaces and the
  per-region default is canonical for non-billing display.
- Region formatting (addresses, phone numbers, names) follows the CLDR per
  locale.

## Updating the coverage list

Locale coverage moves up a tier when:

1. The catalog-coverage test is green for the locale.
2. RTL/expansion QA passes for every listed shell view.
3. Disclosure and crisis-flow copy is reviewed by T&S/privacy/legal.
4. A locale-coverage launch-readiness review confirms the tier.

The launch gate at `docs/launch/go-no-go.md` reads from this document to verify
that launch-quality locales meet their bar before GA.

## Owner

Localization lead owns this document. T&S lead, privacy lead, and the platform
UI lead co-own the tier transitions. Updates require localization sign-off and
any affected co-owner sign-off.