# OSHUN Studio Internationalization and Localization Dependency and Data Contract Map

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.
