Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + Platform SRE + OSHUN
Data/Analytics Engineering + OSHUN Security + Compliance
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0045-oshun-studio-internationalization-and-localization.mddocs/releases/v1/specs/studio-internationalization-and-localization-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for Studio internationalization and localization workflows.
This document is the execution artifact for OST-00259.
Personas#
- Collaboration Lead
- Program Operator
- Localization Reviewer
- Security Reviewer
- Compliance Auditor
Journey Principles#
- Locale and message coverage must remain contract-backed and owner-attributed.
- Formatting and RTL behavior must be deterministic across governed workflows.
- Waiver and release decisions must enforce role/tier/approval controls.
- Remediation closure requires post-fix localization validation evidence.
1. Primary Journeys#
J1. Publish Locale Catalog Contract#
Goal: Define/update canonical locale/namespace contract for Studio workflow.
Entry: Internationalization and localization workspace
Steps:
- Select locale, namespace, and workflow identity.
- Provide owner, version, and release-channel scope.
- Validate coverage thresholds and RTL metadata.
- Publish catalog contract.
- Emit catalog-publish audit event.
Success State:
- Catalog contract is valid, versioned, and governance-ready.
J2. Execute Localization Validation Suites#
Goal: Validate catalog coverage, RTL readiness, and text expansion posture.
Entry: Release candidate or scheduled validation cycle
Steps:
- Run coverage, RTL, and expansion suite set.
- Aggregate pass/warning/fail verdict by locale/namespace.
- Persist validation artifacts and violation counts.
- Trigger release block on critical localization failures.
- Emit validation telemetry and audit events.
Success State:
- Validation posture is deterministic and release-gate consumable.
J3. Monitor Runtime Formatting and Fallback Behavior#
Goal: Track real-world formatting correctness across locales.
Entry: Runtime formatting telemetry stream
Steps:
- Ingest formatter events for date/time/number/currency/list rendering.
- Detect fallback usage and localization degradation signals.
- Correlate degradation with locale and domain workflows.
- Classify issue severity and ownership.
- Emit formatting posture summary event.
Success State:
- Teams can detect and triage formatting regressions quickly.
J4. Decide Waiver or Release Block#
Goal: Apply governance controls for unresolved localization failures.
Entry: Open localization issue near release
Steps:
- Evaluate severity, scope, and channel impact.
- Validate role/tier/CAB prerequisites.
- Decide waiver create/extend/revoke or release block.
- Persist decision with reason code and expiry.
- Emit policy decision audit event.
Success State:
- Decision is policy-compliant and audit-ready.
J5. Execute Remediation and Release Unblock#
Goal: Resolve localization issue and safely unblock release.
Entry: Approved remediation plan
Steps:
- Execute remediation (
catalog_patch,rtl_fix,fallback_repair,release_rollback). - Re-run localization validation suites.
- Confirm failures resolved and coverage restored.
- Close issue and unblock release path.
- Emit remediation + release-unblock evidence events.
Success State:
- Release is unblocked only with verified localization recovery evidence.
2. Critical Edge Cases#
E1. Catalog Definition Missing Owner#
- Trigger: catalog published without
owner. - Required behavior: reject publish and require ownership attribution.
E2. Unsupported Locale Submission#
- Trigger: catalog locale not in canonical locale registry.
- Required behavior: hard reject and emit locale-registry violation event.
E3. Namespace Collision Across Versions#
- Trigger: same namespace/version pair reused with conflicting payload shape.
- Required behavior: reject publish with deterministic version conflict error.
E4. Coverage Validation Without Artifact#
- Trigger: validation verdict emitted without artifact reference.
- Required behavior: mark verdict incomplete and block release promotion.
E5. RTL Violation Misclassified#
- Trigger: critical RTL layout defect reported as warning.
- Required behavior: auto-upgrade severity and open governance incident.
E6. Formatting Fallback Spike#
- Trigger: fallback usage exceeds threshold for governed locale.
- Required behavior: open degradation issue and enforce release hold for critical flows.
E7. Role/Tier Mismatch on Waiver Request#
- Trigger: actor requests waiver with unauthorized tier.
- Required behavior: deny action and emit policy-denial audit event.
E8. Production Waiver Without CAB Ticket#
- Trigger: production waiver action missing approval evidence.
- Required behavior: hard deny waiver and require CAB reference.
E9. Remediation Closure Without Revalidation#
- Trigger: closure requested before post-fix validation pass.
- Required behavior: deny closure and require deterministic revalidation.
E10. Locale Store Drift During Runtime#
- Trigger: runtime locale state diverges from governed locale contract.
- Required behavior: force state reconciliation and emit integrity incident.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Publish Locale Catalog Contract | I18n/l10n governance panel | Locale registry + catalog contract services |
| J2 Execute Localization Validation | Validation execution panel | Coverage/RTL/expansion test pipelines |
| J3 Monitor Runtime Formatting Behavior | Runtime localization posture panel | Formatting telemetry and fallback monitors |
| J4 Decide Waiver or Release Block | Policy decision panel | RBAC/tier policy engine + CAB governance |
| J5 Execute Remediation and Release Unblock | Remediation panel | Catalog rollout services + validation reruns |
4. Instrumentation Requirements#
Required events:
internationalization_localization.journey.startedinternationalization_localization.journey.step.completedinternationalization_localization.journey.blockedinternationalization_localization.journey.recoveredinternationalization_localization.journey.completed
Required dimensions:
catalogId,locale,namespace,sourceDomain,validationSourcemissingMessageCount,rtlViolationCount,expansionViolationCountformatter,fallbackUsed,actorId,actorRole,permissionTierreleaseChannel,approvalTicketRef,journeyId,stepId,outcome,latencyMs
5. Acceptance Criteria (OST-00259)#
OST-00259 is complete only when:
- At least five i18n/l10n journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.