# ADR-0045: OSHUN Studio Internationalization and Localization

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web Engineering, OSHUN
Data/Analytics Engineering  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio surfaces are increasingly cross-domain and globally consumed. Locale
selection, message catalogs, formatting, and RTL readiness exist in web shell
assets, but governance is not yet unified at Studio workflow level. Without a
canonical i18n/l10n model, Studio risks inconsistent locale behavior,
translation drift, and weak release confidence for localized workflows.

Without unified i18n/l10n governance, OSHUN risks:

- inconsistent translation and formatting semantics across domains
- locale regressions in critical governance and operations workflows
- weak observability and auditability for localization quality
- poor readiness for RTL and expansion-heavy locales

## Decision Drivers

- **Consistency**: one localization contract across Studio domains.
- **Quality**: deterministic translation and formatting correctness.
- **Inclusivity**: RTL, expansion, and locale-safe interaction behavior.
- **Operability**: clear ownership and fast remediation for localization issues.
- **Governance**: release gates enforce localization quality posture.

## Considered Options

### Option 1: Domain-Local Translation Governance

Each domain controls independent translation pipelines and locale behavior.

**Pros**:

- High local autonomy.

**Cons**:

- Drift in locale behavior and inconsistent release quality.
- Difficult cross-domain diagnostics and governance.

### Option 2: UI-Only Translation with Minimal Runtime Governance

Localize labels/messages but avoid contract-based validation and policy gates.

**Pros**:

- Lower implementation overhead.

**Cons**:

- Weak detection of formatting/RTL/coverage regressions.
- Poor release safety for localized workflows.

### Option 3: Canonical Studio I18n/L10n Governance Framework (Chosen)

Adopt typed locale/message contracts, deterministic formatting and RTL rules,
policy-aware governance, and telemetry-backed release gates.

**Pros**:

- Consistent locale behavior and stronger global quality posture.
- Better diagnostics, ownership, and remediation workflows.
- Safer release gating for localization regressions.

**Cons**:

- Requires ongoing catalog governance and validation discipline.

## Decision Outcome

**Chosen option**: Option 3.

I18n/l10n requirements:

1. **Canonical locale/message contracts** for Studio workflows.
2. **Formatting contracts** for numbers, dates, currency, and relative time.
3. **RTL and text-expansion contracts** for interaction/layout safety.
4. **Validation/release contracts** for coverage and correctness checks.
5. **Telemetry/audit contracts** for localization posture and remediation.

## Normative Rules

### Locale and Message Contract

- Governed workflows must define locale coverage and namespace ownership.
- Message catalogs require owner and version metadata.
- Missing owner/coverage metadata invalidates release eligibility.

### Formatting Contract

- Date/time/number/currency rendering must use locale-aware formatters.
- Hard-coded locale assumptions are prohibited in governed flows.
- Formatting fallbacks must remain deterministic and traceable.

### RTL and Expansion Contract

- Layout and interaction controls must remain operable under RTL locales.
- Surfaces must tolerate bounded text expansion without clipping critical
  controls.
- RTL/expansion regressions in critical workflows are release-blocking.

### Validation and Release Contract

- CI must validate catalog coverage, formatting semantics, and RTL readiness.
- Production release blocks on unresolved critical localization failures.
- Waivers require owner, rationale, scope, and expiry metadata.

## Architecture Implications

- Existing i18n modules (`config`, `locale-store`, `formatting`, message
  catalogs) become canonical Studio dependencies.
- Studio workspaces surface localization posture and governance actions.
- Metrics/observability and accessibility governance correlate localization
  posture with release quality.
- Analytics contracts include locale dimensions for attribution and diagnostics.

## Acceptance Criteria (OST-00257)

`OST-00257` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0051-oshun-studio-internationalization-and-localization.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines locale/message, formatting, RTL/expansion, and validation/release
   contracts.
4. ADR aligns with `ADR-0007` through `ADR-0044`, especially `ADR-0008`,
   `ADR-0012`, and `ADR-0044`.
5. ADR aligns with existing i18n implementation surfaces in
   `apps/oshun/web/src/i18n`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Stronger, consistent localization quality across Studio.
- Earlier detection and safer remediation of locale regressions.
- Better operational accountability for translation and formatting posture.

### Negative

- Increased governance overhead for catalog/version lifecycle management.
- Requires coordinated rollout discipline across domain teams.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0014-oshun-web-and-pwa-strategy.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0050-oshun-studio-accessibility-governance.md`

## References

- `apps/oshun/web/src/i18n/config.ts`
- `apps/oshun/web/src/i18n/locale-store.ts`
- `apps/oshun/web/src/i18n/formatting.ts`
- `apps/oshun/web/src/i18n/request.ts`
- `apps/oshun/web/src/components/LanguageSwitcher.tsx`
- `apps/oshun/web/src/components/__tests__/LanguageSwitcher.test.tsx`
- `docs/releases/v1/design/readability-standards.md`
- `docs/domains/yemaya/features.md`
- `docs/domains/isis/features.md`
- `docs/domains/hathor/features.md`
- `docs/domains/aja/features.md`
- `docs/domains/bellona/features.md`