# OpenSpec Change: enterprise-react-translate

- **Change ID**: enterprise-react-translate
- **Package**: `@suaveplan/react-translate`
- **Category**: react
- **Target path**: `react/platform/react-translate`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-translate.md`

---

## Summary

Deliver `@suaveplan/react-translate` on genesis from scratch at enterprise quality. React i18n substrate built on `i18next` + `react-i18next` with `TranslationProvider`, `useTranslation`, `useErrorMessage`, `withTranslation` HOC, and per-language bundles (en/en-gb, cy/cy-gb, de, es, fr, ar, zh/zh-cn plus auth namespace variants). Genesis ships clean: no debug test files, no wildcard `export *`, dev-mode loud error when no provider is mounted, lazy-bundle loading, missing-key telemetry, `useDirection()` hook for RTL, Storybook, and Playwright E2E for live language switching. This package is the foundation all other React packages depend on, so it lands first.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `TranslationError` |
| `@suaveplan/logger` (`workspace:^`) | Missing-key telemetry logging |
| `@opentelemetry/api` (`catalog:observability`) | Missing-key OTel counter |

External: `i18next catalog:i18n`, `react-i18next catalog:i18n`, `i18next-browser-languagedetector catalog:i18n`, `i18next-http-backend catalog:i18n`, `tslib catalog:build`. React 18 peer.

---

## Preserved public API surface

```ts
// Provider
TranslationProvider, TranslationProviderProps

// Hooks
useTranslation, UseTranslationReturn
useErrorMessage, UseErrorMessageReturn
useDirection, UseDirectionReturn

// HOC
withTranslation

// Config
createI18nConfig, I18nConfig

// Types
I18nNamespace, SupportedLanguage, LanguageBundle

// Bundles (named exports per language)
en, enGb, cy, cyGb, de, es, fr, ar, zh, zhCn
authEn, authEnGb, authCy, authCyGb, authDe, authEs, authFr, authAr, authZh, authZhCn
```

---

## New additions for genesis

1. **`TranslationError`** — codes: `TRANSLATION_INIT_FAILED`, `TRANSLATION_LOAD_FAILED`.
2. **No `export *`** — explicit named re-exports in `index.ts`; legacy aliases (`cy`, `en`, `zh`) documented.
3. **Dev-mode loud error** — `useTranslation` throws `TranslationError` when no provider is mounted (soft-fails with logger warning in production).
4. **`useDirection()` hook** — returns `{ direction: 'ltr' | 'rtl', locale }` for layout mirroring.
5. **Lazy bundle loader** — `src/i18n/lazy/` with dynamic `import()` per language + Suspense boundary.
6. **Missing-key telemetry** — `missingKeyHandler` forwards to `@suaveplan/logger` + OTel counter.
7. **Storybook** — language switching, RTL flip, plurals, formatting stories.
8. **Playwright E2E** — live language switch, RTL rendering, lazy load with suspense, missing-key detection.

---

## File layout

```text
react/platform/react-translate/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    types/
    provider/
      provider/ (tsx + md + test + index)
    hooks/
      use-translation/ (ts + md + test + index)
      use-error-message/ (tsx + md + test + index)
      use-direction/ (ts + md + test + index)
    hoc/
      with-translation/ (tsx + md + test + index)
    i18n/
      config/ (ts + md + test + index)
      lazy/ (ts + md + test + index)
      i18n.types.ts
    translations/
      en.ts en-gb.ts cy.ts cy-gb.ts de.ts es.ts fr.ts ar.ts zh.ts zh-cn.ts
      auth-en.ts auth-en-gb.ts auth-cy.ts auth-de.ts auth-es.ts auth-fr.ts auth-ar.ts auth-zh.ts
    utils/
      utils.ts utils.types.ts
  e2e/
    translate.spec.ts
```