Eve library

OSHUN Studio Internationalization and Localization Dependency and Data Contract Map

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Data/Analytics Engineering + OSHUN Security + Compliance
Last Updated: 2026-02-23
Related: docs/adr/ADR-0045-oshun-studio-internationalization-and-localization.md

Purpose#

Define dependencies and canonical contracts for Studio internationalization and localization governance across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

This document is the execution artifact for OST-00258.

Sources Used#

  • docs/adr/ADR-0008-oshun-web-and-pwa-strategy.md
  • docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0044-oshun-studio-accessibility-governance.md
  • docs/adr/ADR-0045-oshun-studio-internationalization-and-localization.md
  • 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
  • libs/oshun/analytics/src/types.ts
  • libs/oshun/domain-registry/src/index.ts
  • 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

1. Dependency Overview#

1.1 Control Surfaces#

  • Localization governance UI surfaces: Studio i18n/l10n modules in apps/oshun/web/src/components/studio.
  • Locale and catalog services: locale registry, message namespace loading, and catalog versioning.
  • Formatting services: locale-aware date/time/number/currency/list formatting primitives.
  • Policy and waiver services: role/tier-aware localization waiver and release controls.
  • Validation services: CI/runtime localization coverage, RTL, and expansion checks.
  • Audit and telemetry services: localization posture events and evidence retention.

1.2 Domain Dependency Graph#

  • I18n/L10n Governance -> Yemaya: localized release flow semantics and operational labels.
  • I18n/L10n Governance -> Isis: localized model-workbench and inference controls.
  • I18n/L10n Governance -> Hathor: localized narrative tooling and content controls.
  • I18n/L10n Governance -> Aja: localized timeline/render orchestration labels and states.
  • I18n/L10n Governance -> Bellona: localized runtime safety and governance controls.
  • Project Obsidian -> all: cross-domain locale governance and release orchestration.

2. Ownership and Contract Matrix#

Area Owner Consumers Artifact Contract
Locale and catalog definition Web + Design Systems Domain teams + release operators Locale/catalog definitions StudioLocalizationCatalogDefinition
Localization validation execution Platform SRE + Web QA CI/release workflows Validation result stream StudioLocalizationValidationEvent
Locale-aware formatting instrumentation Web + Data Platform Product operations + observability Formatting event stream StudioLocalizationFormattingEvent
Policy and waiver decisions Security + Compliance Operators + release managers Policy decision envelope StudioLocalizationPolicyDecision
Remediation and catalog rollout Web + Platform SRE Incident responders + domain owners Remediation execution records StudioLocalizationRemediationExecution
Governance audit evidence Security + Data Platform Compliance + audit operations Audit event stream StudioLocalizationAuditEvent

3. Canonical Contracts#

3.1 StudioLocalizationCatalogDefinition#

ts
export interface StudioLocalizationCatalogDefinition {
  catalogId: string;
  locale: string;
  namespace: string;
  owner: string;
  version: string;
  rtl: boolean;
  coverageScore: number;
  releaseChannelScope: 'preview' | 'staging' | 'production' | 'all';
  expiresAt: string;
  createdAt: string;
  updatedAt: string;
}

3.2 StudioLocalizationValidationEvent#

ts
export interface StudioLocalizationValidationEvent {
  eventId: string;
  catalogId: string;
  validationSource:
    | 'ci_catalog_coverage'
    | 'ci_rtl_layout'
    | 'ci_expansion'
    | 'runtime_locale_probe';
  status: 'pass' | 'warning' | 'fail';
  missingMessageCount: number;
  rtlViolationCount: number;
  expansionViolationCount: number;
  artifactRef?: string;
  occurredAt: string;
}

3.3 StudioLocalizationFormattingEvent#

ts
export interface StudioLocalizationFormattingEvent {
  eventId: string;
  locale: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  formatter: 'date' | 'time' | 'relative_time' | 'number' | 'currency' | 'list';
  success: boolean;
  fallbackUsed: boolean;
  reasonCode?: string;
  occurredAt: string;
}

3.4 StudioLocalizationPolicyDecision#

ts
export interface StudioLocalizationPolicyDecision {
  decisionId: string;
  catalogId: string;
  action:
    | 'waiver_create'
    | 'waiver_extend'
    | 'waiver_revoke'
    | 'release_block'
    | 'release_allow';
  actorId: string;
  actorRole: string;
  permissionTier: 'baseline' | 'sensitive' | 'restricted';
  releaseChannel: 'preview' | 'staging' | 'production';
  approvalTicket?: string;
  outcome: 'allowed' | 'denied';
  reasonCode?: string;
  decidedAt: string;
}

3.5 StudioLocalizationRemediationExecution#

ts
export interface StudioLocalizationRemediationExecution {
  remediationId: string;
  catalogId: string;
  locale: string;
  action: 'catalog_patch' | 'fallback_repair' | 'rtl_fix' | 'release_rollback';
  actorId: string;
  success: boolean;
  validationRecheckPassed: boolean;
  latencyMs: number;
  errorCode?: string;
  executedAt: string;
}

3.6 StudioLocalizationAuditEvent#

ts
export interface StudioLocalizationAuditEvent {
  eventId: string;
  action:
    | 'localization.catalog.published'
    | 'localization.validation.failed'
    | 'localization.formatting.degraded'
    | 'localization.policy.denied'
    | 'localization.remediation.executed'
    | 'localization.release.unblocked';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  catalogId?: string;
  locale?: string;
  actorId?: string;
  actorRole?: string;
  reasonCode?: string;
  occurredAt: string;
}

4. Validation Rules#

  • Catalog definitions must include locale, namespace, owner, version, and expiry.
  • Validation events must capture source, status, and coverage/RTL/expansion violation counts.
  • Formatting events must include formatter type, locale, and fallback outcome.
  • Policy decisions must enforce role/tier/approval constraints by channel.
  • Remediation executions must include success and post-fix validation outcomes.
  • Audit events must capture catalog, validation, policy, remediation, and release lifecycle actions end to end.

5. Acceptance Criteria (OST-00258)#

OST-00258 is complete only when:

  1. This dependency and contract map exists.
  2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
  3. Contracts for catalog definitions, validation, formatting, policy decisions, remediation, and governance audits are documented.
  4. Ownership boundaries and validation rules are explicit.