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