Oshun V1 Translation Workflow

Companion to docs/launch/locale-coverage.md. Defines the workflow, glossary ownership, language fallback, RTL handling, and text-expansion QA that govern customer-facing strings in libs/oshun/i18n/ and domain-owned catalogs.

Catalog ownership#

Shared shell strings — anything that appears in the customer shell chrome or in the assistant compliance/disclosure copy — live in the canonical catalog at libs/oshun/i18n/. Domain-owned content records may carry source text, but their customer-visible shared labels, disclosures, status copy, formatting rules, fallback rules, and launch-locale metadata depend on this package and may not redefine its keys.

Glossary#

A single glossary, owned by the localization lead, governs proper nouns, persona names, domain names (Tara, Veritas, Nyx, Arete, Nisaba, Metis), and trust-and-safety terminology that must read identically across surfaces.

• Glossary location: libs/oshun/i18n/glossary/. Each glossary entry is JSON: source term, allowed translations per locale, do-not- translate flag, gender/animacy hints, disclosure context.
• Glossary review: localization lead + T&S lead sign-off for terms that touch persona identity or refusal copy.
• Glossary lint: a glossary-coverage check runs against every PR that adds or modifies a translation: terms in the glossary must translate to the allowed values per locale; do-not-translate terms must remain in source language. Failures block merge.

Fallback chain#

The runtime fallback for a missing key is:

1. Requested locale (e.g., es-US).
2. Language-only locale (e.g., es).
3. en-US.

The chain is implemented in resolveFallbackChain and translate in libs/oshun/i18n/src/index.ts. The same package also exposes the mapping from legacy customer language preferences (en, es, etc.) to launch locales (en-US, es-US, etc.) so web and mobile selectors cannot advertise languages outside the V1 launch coverage list. A fallback hit emits an analytics event so that gaps surface in the launch dashboards.

A fallback gap discovered on a critical surface (disclosure, privacy, crisis) is a sev2 — it does not block GA, but it blocks the locale from being marked launch-quality for that surface.

RTL handling#

ar and he are RTL launch locales. Every shell, domain, and admin surface must:

1. Mirror the layout: the primary visual flow runs right-to-left.
2. Mirror icons that imply direction (back/forward, next/previous, chevrons, sliders).
3. Preserve bidi safety: customer-controlled strings appear inside bidi-isolated runs.
4. Number and digit policy: western numerals by default; Arabic-Indic digits opt-in per content piece for ar.
5. Punctuation: locale-correct quotation marks, dashes, ellipsis.

The cross-cutting RTL test suite lives at tests/locale/rtl-smoke.spec.ts and runs against every locale-tagged view in Playwright.

Text-expansion QA#

Every shell layout is verified against the LOCALE_EXPANSION_BUDGET table in the i18n library:

• en-US: 1.0 baseline.
• es-US: 1.25.
• fr-FR: 1.3.
• de-DE: 1.4.
• ar: 1.2 (script width plus mirroring).
• he: 1.15.
• ja-JP: 0.7 (denser script).
• pt-BR: 1.3.

The customer preference aliases exposed in profile settings and the language switcher are launch-scoped: en, es, fr, de, ar, he, ja, and pt. Unsupported prelaunch aliases such as zh, ko, and hi are not surfaced to customers until they receive a launch-locale coverage row and full catalog coverage.

QA generates synthetic strings at each locale's budget against every catalog key, drops them into the shell, and verifies no truncation, no unintended wrap, no overflow into the next region. Failures are filed against the shell owner; layout fixes are required before the locale can be marked launch-quality.

Translation workflow#

1. Author the source string in en-US in the matching catalog. PRs must include a one-sentence translator note when the meaning is non-obvious (e.g., "disclosure copy — must read calmly, not alarming").
2. Run the catalog-lint check locally; this verifies the key is declared in the type union and the placeholder convention is correct.
3. Trigger the localization pipeline: the localization lead routes the new key to the contracted translators with context (surface, character budget, tone, glossary references).
4. Review the returned translations: locale leads + glossary lint + visual review against the actual surface (Storybook or staging) at the expansion-budget length.
5. Land the translations: PR merges only when every launch locale has a translation (the every customer message key has a translation in every launch locale test enforces this).
6. Run the runtime smoke: in staging, render the surface in every locale; verify no fallback hits, no truncation, no RTL break.

Audit and provenance#

• Every change to CUSTOMER_MESSAGES lands with the i18n maintainer + matching domain maintainer review.
• Trust-and-safety disclosure copy changes require T&S sign-off.
• Privacy disclosure copy changes require privacy + legal sign-off.
• The translation pipeline records translator identity (team or contractor), timestamp, and source-language hash so customer-facing disclosures have a clean provenance audit trail.

Adding a new launch locale#

Adding a locale is a launch-class change:

1. Add the locale to OSHUN_LAUNCH_LOCALES.
2. Add a row to LOCALE_EXPANSION_BUDGET, LOCALE_CALENDAR, and RTL_LOCALES if applicable.
3. Translate every key in CUSTOMER_MESSAGES.
4. Run the RTL smoke and the expansion-budget QA across every shell.
5. Update docs/launch/locale-coverage.md to reflect the locale's coverage tier.
6. Run the locale-coverage gate at the next release-readiness review.

Until every catalog entry passes the test suite, the locale stays in the staging-only tier and is not surfaced to customers.

Owner#

Localization lead owns this workflow. Platform UI lead, T&S lead, privacy lead, and legal counsel co-review changes that affect disclosure or trust-touching copy. Updates require sign-off from localization plus any affected co-owner.