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

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

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

File layout

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

3.7 KiB Raw Blame History