Oshun Platform · Architecture

Content, Localization, Documentation, and Launch Readiness

A focused page within the Oshun Platform Architecture documentation. The full map and every sibling page live in the Architecture hub.

5sections9 minread1table
← Back to the Architecture hubMarkdown source
On this page

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.

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. Backlog: §32 (content/localization/docs), §33 (launch readiness), plus the Help Center / Knowledge Base substrate in §20. The hub is ../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 CustomerMessageKeys, 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 and Oshun Studio — Authoring, Editorial, Curation).

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 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.