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.mddocs/adr/ADR-0012-analytics-taxonomy-and-event-naming.mddocs/adr/ADR-0044-oshun-studio-accessibility-governance.mddocs/adr/ADR-0045-oshun-studio-internationalization-and-localization.mdapps/oshun/web/src/i18n/config.tsapps/oshun/web/src/i18n/locale-store.tsapps/oshun/web/src/i18n/formatting.tsapps/oshun/web/src/i18n/request.tsapps/oshun/web/src/components/LanguageSwitcher.tsxapps/oshun/web/src/components/__tests__/LanguageSwitcher.test.tsxlibs/oshun/analytics/src/types.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/design/readability-standards.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for catalog definitions, validation, formatting, policy decisions, remediation, and governance audits are documented.
- Ownership boundaries and validation rules are explicit.