107 lines
3.7 KiB
Markdown
107 lines
3.7 KiB
Markdown
# 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
|
|
```
|