# Content, Localization, Documentation, and Launch Readiness

This page covers the last mile before V1 ships: how strings and content are
localized, how the product is documented for customers and operators, and the
operational gates that must clear before general availability. It serves
everyone who touches a customer-visible artifact — the domain teams (Tara,
Veritas, Nyx, Arete, Nisaba, Metis), the Studio editorial/translation surface,
support, and launch operations — and it sits at the top of the quality stack, on
top of the observability, design-system, and testing machinery described in
[Observability, Design System, Testing, and Performance](./observability-and-quality.md).

The localization layer is real, working code: there is a complete shared
translation catalog with fallback telemetry, eight launch locales fully
populated, and a per-locale text-expansion budget. The launch-readiness side is
honestly part code, part process — several launch-readiness _manifests_ exist
and are test-locked, but the operational drills they describe (rollback,
residency, DSAR, red-team) are process gates that this audit did not confirm
have actually been executed.

Product scope:
[`V1/features.md` § Content, Localization, Documentation, and Launch](../features.md#content-localization-documentation-and-launch).
Backlog: §32 (content/localization/docs), §33 (launch readiness), plus the Help
Center / Knowledge Base substrate in §20. The hub is
[../ARCHITECTURE.md](../ARCHITECTURE.md).

---

## UI Localization

V1 localization runs at two layers that the older architecture text described
only partially: the **next-intl** runtime in the web app, and the shared
**`@oshun/i18n`** catalog that sits beneath it.

### The web runtime — next-intl

The customer web app uses `next-intl`. `apps/oshun/web/package.json` depends on
`next-intl` (via the pnpm catalog), and the wiring lives in
`apps/oshun/web/src/i18n/request.ts` and `apps/oshun/web/src/i18n/config.ts`.
`config.ts` derives its locale set _from_ the shared library — `locales` is
`OSHUN_LAUNCH_LANGUAGE_PREFERENCES` re-exported from `@oshun/i18n`, the labels
come from `LANGUAGE_PREFERENCE_LABELS`, and `isRtlLocale()` is computed from
`RTL_LOCALES` — so the web layer does not maintain a parallel locale list.
`request.ts` is a `next-intl/server` `getRequestConfig` that loads namespaced
message JSON (`shell`, `tara`, `arete`, `veritas`, `nyx`) for the active locale.
Mobile localizes through Expo's i18n flow over the same tokens and catalog.

Locale fallback is enforced at the component, route, and BFF layers, and the
user's locale lives in their profile/settings.

### The shared catalog — `libs/oshun/i18n`

The layer that the architecture text omits is `@oshun/i18n`
(`libs/oshun/i18n/src/index.ts`), the canonical catalog of shared customer
strings with its own fallback engine and telemetry. This is the place where
"externalized strings" stops being a slogan and becomes a complete, tested
catalog.

**Launch locales.** `OSHUN_LAUNCH_LOCALES` is the eight-locale launch set, with
`OSHUN_DEFAULT_LAUNCH_LOCALE = 'en-US'`:

| Locale  | Label              | Direction | Expansion budget (vs `en-US`) |
| ------- | ------------------ | --------- | ----------------------------- |
| `en-US` | English (US)       | ltr       | 1.0 (baseline)                |
| `es-US` | Espanol (US)       | ltr       | 1.25                          |
| `fr-FR` | Francais           | ltr       | 1.3                           |
| `de-DE` | Deutsch            | ltr       | 1.4 (widest)                  |
| `ar`    | Arabic             | **rtl**   | 1.2                           |
| `he`    | Hebrew             | **rtl**   | 1.15                          |
| `ja-JP` | Japanese           | ltr       | 0.7 (narrowest)               |
| `pt-BR` | Portugues (Brasil) | ltr       | 1.3                           |

`RTL_LOCALES` is the set `{ ar, he }`, and `localeDirection()` returns `'rtl'`
for those two and `'ltr'` otherwise. The `LOCALE_EXPANSION_BUDGET` numbers are
the multiplier by which a shell must be able to render a string longer than its
`en-US` baseline without truncating or breaking grid columns — German (1.4) is
the stress case layout QA must clear, while Japanese (0.7) is _narrower_ than
the baseline. There is also a `LANGUAGE_PREFERENCE_TO_LAUNCH_LOCALE` map (and
its inverse) so a stored `'de'` preference resolves to `'de-DE'`, plus
`normalizeLaunchLocale()` to canonicalize arbitrary input.

**The string catalog.** `CUSTOMER_MESSAGES` is a frozen map of 28
`CustomerMessageKey`s, each fully translated in all eight locales — including
real Arabic, Hebrew, and Japanese strings, not English placeholders. The keys
span the shell (`shell.home.title`, `shell.nav.*`), the assistant
(`assistant.disclosure.ai`, `assistant.disclosure.persona_changed`,
`assistant.memory.on`/`off`), evidence (`evidence.provenance.open`,
`evidence.confidence.low`, `evidence.citation.mismatch`), offline state, errors,
status, auth (`auth.session_expired`, `auth.minimum_version_required`), and
privacy (`privacy.consent_revoked`, `privacy.dsar_received`).

**Fallback with telemetry.** `resolveFallbackChain()` implements the documented
chain `requested → language-only → en-US`: `es-US` tries `es-US` → `es` →
`en-US`; a bare `ar` tries `ar` → `en-US`. `translate(key, locale, options)`
walks that chain, returns a `TranslationResult` (`value`, `resolvedLocale`,
`fallbackApplied`), and — crucially — emits a `TranslationFallbackEvent` through
the optional `onFallback` callback whenever a fallback fired, carrying the
`fallbackChain`, the originating `surface`, and a `critical` flag. Criticality
is not guessed: `isCriticalMessageKey()` flags any key under the prefixes
`assistant.disclosure.`, `evidence.`, `privacy.`, or the exact
`auth.minimum_version_required` — i.e. exactly the trust-bearing strings that
must never silently fall back to a less-precise language. Coverage tooling is
built in: `listCustomerMessageKeys()` and `findFallbackGaps()` return every
`<key, locale>` pair that resolves via fallback rather than a direct hit, so a
non-empty result is a pre-launch translation gap that fails the catalog test.

**Locale-aware formatting.** `formatForLocale()` builds date, time, date-time,
time-zone, currency, number, region, and relative-time formatters over the
standard `Intl.*` APIs (`Intl.DateTimeFormat`, `Intl.NumberFormat`,
`Intl.RelativeTimeFormat`, `Intl.DisplayNames`), honoring an explicit per-locale
calendar from `LOCALE_CALENDAR` (all eight launch locales use `gregory` in the
formal Oshun shells, with the Japanese imperial calendar reserved for specific
opted-in cultural surfaces).

> Reconciliation note: the older architecture text described UI localization
> only as "next-intl for web/admin; Expo i18n for mobile" and never named this
> catalog, while `V1/features.md` correctly points to `OSHUN_LAUNCH_LOCALES`.
> The two are layers of one system, not a contradiction: `@oshun/i18n` is the
> typed catalog and fallback engine; next-intl/Expo are the runtimes that
> consume it.

---

## Content Localization

Localized _content_ (as opposed to UI chrome) is modeled as first-class objects.
Veritas stories, Nisaba passages, and Metis lessons carry per-language editions
and translations via the `Translation` and `Edition` contracts, so a translated
passage is a distinct, addressable artifact with its own provenance rather than
a column on the original. The Studio translation surface consumes the
Localization and Translation Workspace (see
[`V1/features.md` § Localization and Translation Workspace](../features.md) and
[Oshun Studio — Authoring, Editorial, Curation](./oshun-studio.md)).

The expected content-bundle and locale coverage are themselves recorded as data:
`libs/oshun/analytics/src/v1-32-content-localization-documentation.ts` exports
`OSHUN_V1_32_DOMAINS`, `OSHUN_V1_32_CONTENT_BUNDLE_GATES`, and
`OSHUN_V1_32_LOCALE_COVERAGE` (alongside seed-data, documentation, runbook, and
training-program manifests), so "is the launch content bundle complete?" is a
checkable manifest, not a manual tally.

---

## Documentation and Onboarding

- **In-app help center** — contextual articles, in-help search, video
  walkthroughs, and feedback capture, backed by a tenant- and
  operator-authorable Help Center / Knowledge Base substrate (§20).
- **Onboarding and changelog** — a "what's new" feed, walkthrough overlays,
  contextual help, and a keyboard-shortcut reference. First run gates on
  domain-tour completion before exposing the full shell, so a new user is not
  dropped into the whole multi-domain surface cold.
- **Public documentation** — V1 launch requires published runbooks, privacy
  copy, rights/license notices, an accessibility statement, status-page copy,
  and app-store listings. The documentation/runbook/training inventories are
  tracked as `OSHUN_V1_32_DOCUMENTATION_ARTIFACTS`, `OSHUN_V1_32_RUNBOOKS`, and
  `OSHUN_V1_32_TRAINING_PROGRAMS` in the §32 manifest above.

---

## Launch Readiness

The launch-readiness backlog is §33. Everything documented across the
architecture is _necessary but not sufficient_ for launch; this section names
the operational gates the architecture must satisfy before V1 ships. Be candid
about status: the **manifests** that enumerate these gates exist and are
test-locked (`v1-launch-readiness-manifest`, `v1-security-readiness-manifest`,
`v1-release-and-exit-criteria-manifest`, `v1-33-launch-gate-signoff`,
`v1-33-launch-readiness-evidence`), but the **drills** themselves are
operational acts this audit did not confirm have been executed.

### Operational drills

Each of the following must be _executed and signed off_ before general
availability — not merely planned:

- **Rollback drills.** Every surface that generates customer-visible artifacts —
  Living Scenes workflow classes, generation tiers, the assistant, search — must
  demonstrate an executable rollback to a prior version, with in-flight sessions
  completing on the current version.
- **Data-residency drills.** Exercise primary-to-failover routing for each
  launch region; confirm logs stay segregated by region and caches respect
  residency boundaries.
- **DSAR exercises.** Run the full DSAR / deletion sequence end to end against a
  seeded user, verifying tombstone propagation across every domain and audit
  completeness before the receipt is issued. (The
  `privacy.dsar_received`/`privacy.consent_revoked` strings above are the
  customer-facing edge of this flow.)
- **Tenant-isolation tests.** `tests/security/tenant-isolation/` must pass with
  zero cross-tenant cache, feature-flag, or experiment leakage.

### Quality and safety gates

- **Eval-set passes.** Every V1-launching surface clears its release-gate eval
  thresholds, and champion–challenger promotion is gated on a passing gold-set
  eval — the discipline encoded in `evaluation-manifest.ts` and described in
  [Observability, Design System, Testing, and Performance](./observability-and-quality.md).
- **Observability budgets.** Structured tracing, Prometheus metrics, and OTLP
  export are live across the shell, BFF, and every substrate; SLO dashboards and
  breach alerts are wired.
- **Performance budgets.** The Lighthouse budgets in
  `apps/oshun/web/lighthouse-budget.json` hold on customer web, and mobile
  budgets hold on the device matrix. The conceptual targets are LCP ≤ 2.5 s,
  input latency ≤ 200 ms, and CLS ≤ 0.1. Note, though, that the file enforces
  input latency via the `max-potential-fid` key (200 ms), the older FID proxy,
  rather than an INP metric, which Lighthouse `budgets.json` does not support.
  LCP and CLS map directly.
- **Accessibility compliance.** WCAG 2.1 AA across customer and admin surfaces,
  including reduced-motion variants and screen-reader flows.
- **Security review.** Pre-GA penetration testing and red-team exercises
  covering auth, RBAC, privacy, Metis institutional workflows, grounded
  generation, and admin escalation paths, with documented scope and signoff. The
  expected scope is enumerated in `OSHUN_V1_SECURITY_READINESS_MANIFEST`
  (`v1-security-readiness-manifest.ts`), but the pen-test execution itself is an
  external act.
- **Runbooks.** Published runbooks for shell outages, grounding failures,
  provider failover, moderation surges, privacy incidents, and
  model/workflow/persona rollback.

### Exit criteria as data

The release/exit gates are themselves a manifest:
`libs/oshun/analytics/src/v1-release-and-exit-criteria-manifest.ts` exports
`OSHUN_V1_RELEASE_AND_EXIT_CRITERIA_MANIFEST`, a list of `ReleaseExitEntry`
records grouped by `ReleaseExitGroup` — `pre_launch_gate`, `beta_and_ga`,
`verification_completion`, `customer_product_exit`, `admin_product_exit`,
`platform_exit`, `quality_exit`, `platform_integration_exit` — each pointing at
a `sourcePath` (an actual repo path) plus an `artifactKind` (`code`, `repo_doc`,
or `external`) so that "what proves this gate?" is recorded next to the gate.
The §33 launch-gate signoff (`OSHUN_V1_33_LAUNCH_GATE_SIGNOFF`) and its
companion launch-readiness evidence manifest carry the beta-blocking remediation
and exit-criteria-signoff sections (e.g. `33.4_exit_criteria_signoff`).

### The completion bar

V1 is feature-complete only when three conditions hold together:

1. Every `V1/TODOS.md` section is fully checked.
2. The adversarial stub scan (`scripts/stub-indicator-scan.sh`) turns up zero
   actionable hits.
3. The launch-readiness drills above have all run and been signed off.

That third condition is the honest line between code and operations: the
catalog, manifests, budgets, and gates are in the tree and locked by tests, but
the drills are operational acts whose execution lives outside this repository's
source.

---

## Related

- [Observability, Design System, Testing, and Performance](./observability-and-quality.md)
  — the evaluation, budget, and design-token machinery these launch gates depend
  on
- [Security, Privacy, and Compliance](./security-privacy-compliance.md) — the
  security-readiness manifest and pen-test scope
- [Trust, Safety, and Privacy](./trust-safety-and-privacy.md) — the DSAR/consent
  flows the launch drills exercise
- [Oshun Studio — Authoring, Editorial, Curation](./oshun-studio.md) — the
  translation/editorial workspace
- [Data Architecture and Tenancy](./data-architecture-tenancy.md) — the
  residency/tenant-isolation foundations the drills test
- [`V1/features.md` § Content, Localization, Documentation, and Launch](../features.md#content-localization-documentation-and-launch)
- Backlog: §20, §32, §33 in [`V1/TODOS.md`](../TODOS.md)