# OSHUN Studio Internationalization and Localization Runbook

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + Platform SRE + OSHUN
Data/Analytics + OSHUN Security + Compliance + Program Operations  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0045-oshun-studio-internationalization-and-localization.md`
- `docs/releases/v1/specs/studio-internationalization-and-localization-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-internationalization-and-localization-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioInternationalizationLocalizationWorkspace.tsx`
- `apps/oshun/web/src/analytics/studioInternationalizationLocalizationTelemetry.ts`

## Purpose

Define operational ownership, SLOs, incident playbooks, and escalation paths for
Studio internationalization and localization governance workflows.

This document is the execution artifact for `OST-00264`.

## 1. Ownership Model

| Surface                                        | Primary Owner            | Backup Owner       | Dependencies                                                |
| ---------------------------------------------- | ------------------------ | ------------------ | ----------------------------------------------------------- |
| i18n/l10n governance workspace route           | OSHUN Web                | Platform Web       | route contracts + governance UX orchestration               |
| Locale catalog lifecycle and ownership         | OSHUN BFF + Domain teams | Platform SRE       | catalog schemas + ownership/version governance              |
| Localization validation and runtime monitoring | Platform SRE + Web QA    | Data Platform      | coverage/RTL/expansion suites + runtime fallback probes     |
| Waiver/block policy and approval controls      | Security + Compliance    | Program Operations | role/tier policy bundles + CAB governance                   |
| Remediation execution and closure workflows    | Web + Platform SRE       | Domain integrators | issue-state transitions + post-fix validation reruns        |
| Telemetry and audit evidence continuity        | Data Platform + Security | Platform SRE       | analytics sinks + retention/export controls + replay safety |

## 2. Core SLOs

| Metric                                          | Target    | Alert Threshold      |
| ----------------------------------------------- | --------- | -------------------- |
| Localization governance flow success rate       | >= 99.0%  | < 98.0% over 15 min  |
| Locale catalog integrity                        | >= 99.5%  | < 99.0% over 15 min  |
| Validation/monitoring/remediation flow p95      | <= 2500ms | > 3500ms over 15 min |
| Runtime fallback posture signal continuity      | >= 99.5%  | < 99.0% over 15 min  |
| Policy-tier/CAB enforcement correctness         | >= 99.5%  | < 99.0% over 15 min  |
| Critical localization issue closure determinism | >= 99.5%  | < 99.0% over 15 min  |
| Telemetry/audit event delivery continuity       | >= 99.5%  | < 99.0% over 15 min  |

## 3. Operational Playbooks

### 3.1 Locale Catalog Publish Failures

Trigger: repeated `LOCALIZATION_CATALOG_PUBLISH_FAILED` outcomes.

Actions:

1. Validate catalog identity (`catalogId`, `locale`, `namespace`, `version`) and
   ownership metadata.
2. Inspect catalog schema compatibility and contract version drift.
3. Re-run publish in preview channel with validation diagnostics enabled.
4. Block production waiver/remediation actions until catalog integrity recovers.

### 3.2 Localization Validation Failures

Trigger: repeated `LOCALIZATION_VALIDATION_SUITE_FAILED` outcomes.

Actions:

1. Validate failing coverage/RTL/expansion evidence artifacts.
2. Inspect validation harness drift, flaky suites, and stale fixtures.
3. Re-run localization validation against known-good baseline snapshots.
4. Maintain release block while critical localization failures remain
   unresolved.

### 3.3 Runtime Formatting/Fallback Degradation

Trigger: repeated `LOCALIZATION_RUNTIME_MONITORING_FAILED` outcomes.

Actions:

1. Validate runtime telemetry ingestion and locale-catalog binding identity.
2. Inspect fallback-rate spikes and delayed formatter signal streams.
3. Re-run runtime posture checks with bounded diagnostic windows.
4. Escalate to Platform SRE for sustained critical locale degradation.

### 3.4 Waiver/Block Decision Failures

Trigger: repeated `LOCALIZATION_POLICY_DECISION_FAILED` outcomes.

Actions:

1. Validate role/tier/CAB prerequisites and denial reason codes.
2. Inspect policy bundle drift and production-governance anomalies.
3. Re-run waiver/block decisions with compliance auditor supervision.
4. Freeze production promotions while decision integrity is degraded.

### 3.5 Remediation Closure Failures

Trigger: repeated `LOCALIZATION_REMEDIATION_CLOSURE_FAILED` outcomes.

Actions:

1. Validate issue-state and remediation-action preconditions.
2. Verify post-fix localization validation pass evidence before closure.
3. Re-run remediation closure under incident command oversight.
4. Prevent issue closure until deterministic revalidation is complete.

### 3.6 Policy Denial Spike

Trigger: sustained increase in `ROLE_POLICY_DENIED`,
`PERMISSION_TIER_ROLE_DENIED`, `FLOW_PERMISSION_TIER_INSUFFICIENT`,
`POLICY_JUSTIFICATION_REQUIRED`, `PRODUCTION_APPROVAL_REQUIRED`, or
`PRODUCTION_WAIVER_REQUIRES_COMPLIANCE_AUDITOR`.

Actions:

1. Compare active role/tier/CAB policy bundles against intended controls.
2. Inspect recent policy releases for deny-path regressions.
3. Roll back or patch policy bundle and revalidate all decision paths.
4. Confirm denial-rate normalization across localization governance flows.

### 3.7 Telemetry and Audit Degradation

Trigger: missing or delayed `studio_internationalization_localization_*`
telemetry events.

Actions:

1. Validate analytics sink health and ingestion backlog.
2. Enable degraded-observability notice in localization workspace.
3. Replay buffered events where replay semantics are supported.
4. Confirm SLO panel and audit-evidence continuity after recovery.

## 4. Release Checklist

- [ ] Validate `/studio/internationalization-localization` renders and executes
      required flows.
- [ ] Validate optimistic, error, and retry behavior for all localization
      governance flows.
- [ ] Validate permission-tier and production CAB policy enforcement.
- [ ] Validate telemetry/audit emissions and SLO panel updates.
- [ ] Validate integration/e2e/accessibility/performance evidence artifacts.

## 5. Incident Communication Templates

### Incident Start

```text
[P{severity}] Studio Localization Governance Incident
Detected: {timestamp}
Impact: {catalog-publish | validation-suite | runtime-monitoring | waiver-block | remediation-closure}
Suspected cause: {policy drift | schema regression | telemetry degradation | localization regression}
Owner: {on-call}
```

### Incident Update

```text
[P{severity}] Studio Localization Governance Update
Time: {timestamp}
Mitigation: {rollback | hotfix | policy patch | release hold}
Affected flows: {publishLocalizationCatalog | runLocalizationValidationSuite | monitorRuntimeFormattingFallbacks | decideLocalizationWaiverOrBlock | executeLocalizationRemediationClosure}
ETA: {time}
```

### Incident Resolved

```text
[P{severity}] Studio Localization Governance Incident Resolved
Resolved: {timestamp}
Root cause: {description}
Fix: {release/hotfix id}
Validation: {tests + telemetry checks}
Postmortem: {link}
```

## 6. Escalation Paths

| Area                                       | Primary Channel        | Escalate To           |
| ------------------------------------------ | ---------------------- | --------------------- |
| Localization governance workspace UX       | `#oshun-web`           | Platform on-call      |
| Locale catalogs and validation APIs        | `#oshun-bff`           | BFF lead              |
| Runtime fallback and formatter telemetry   | `#oshun-platform-sre`  | SRE lead              |
| Policy-tier/CAB governance controls        | `#oshun-security`      | Security + Compliance |
| Localization analytics and audit reporting | `#oshun-data-platform` | Data platform lead    |

## 7. Acceptance Criteria (OST-00264)

`OST-00264` is complete only when:

1. Ownership and decision authority are documented.
2. Localization-governance SLOs and alert thresholds are documented.
3. At least five playbooks are documented for major failure modes.
4. Release checklist, communication templates, and escalation paths exist.
