Initial Commit

openspec/changes/enterprise-react-translate/proposal.md

@@ -0,0 +1,106 @@
+# 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
+```