Initial Commit
This commit is contained in:
106
openspec/changes/enterprise-react-translate/proposal.md
Normal file
106
openspec/changes/enterprise-react-translate/proposal.md
Normal file
@@ -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
|
||||
```
|
||||
117
openspec/changes/enterprise-react-translate/tasks.md
Normal file
117
openspec/changes/enterprise-react-translate/tasks.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# Tasks: enterprise-react-translate
|
||||
|
||||
**Change ID**: enterprise-react-translate
|
||||
**Package**: `@suaveplan/react-translate`
|
||||
**Target path**: `react/platform/react-translate`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/logger`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create directory tree. Write `package.json` at `0.1.0`, `tsconfig.json`, `vitest.config.ts`, scripts.
|
||||
- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/logger workspace:^`, `i18next catalog:i18n`, `react-i18next catalog:i18n`, `i18next-browser-languagedetector catalog:i18n`, `i18next-http-backend catalog:i18n`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Error codes and types
|
||||
|
||||
- [ ] Define `TranslationError`; codes: `TRANSLATION_INIT_FAILED`, `TRANSLATION_LOAD_FAILED`.
|
||||
- [ ] Define types: `I18nConfig`, `I18nNamespace`, `SupportedLanguage`, `LanguageBundle`, `TranslationProviderProps`, `UseTranslationReturn`, `UseErrorMessageReturn`, `UseDirectionReturn`.
|
||||
|
||||
---
|
||||
|
||||
## 3. i18n config and lazy loader
|
||||
|
||||
- [ ] `createI18nConfig(options)` — builds i18next config with `missingKeyHandler` that forwards to `@suaveplan/logger` + OTel counter. Throws `TranslationError(TRANSLATION_INIT_FAILED)` on invalid config.
|
||||
- [ ] `src/i18n/lazy/` — `createLazyLoader(namespaces)` returns dynamic-import factory per language for Suspense-compatible lazy bundles.
|
||||
- [ ] Write `i18n-config.test.ts` + `lazy-loader.test.ts` (≤500 lines total): config init, missing-key telemetry fires, lazy-load resolves. `{ timeout: 10000 }`.
|
||||
- [ ] Write `.md` for each.
|
||||
|
||||
---
|
||||
|
||||
## 4. Translation bundles
|
||||
|
||||
- [ ] Write all 10 base bundles: `en.ts`, `en-gb.ts`, `cy.ts`, `cy-gb.ts`, `de.ts`, `es.ts`, `fr.ts`, `ar.ts`, `zh.ts`, `zh-cn.ts`.
|
||||
- [ ] Write 8 auth-namespace bundles: `auth-en.ts`, `auth-cy.ts`, `auth-de.ts`, `auth-es.ts`, `auth-fr.ts`, `auth-ar.ts`, `auth-zh.ts`, `auth-en-gb.ts`.
|
||||
- [ ] Export legacy aliases: `cy` → `cyGb`, `en` → `enGb`, `zh` → `zhCn` with JSDoc deprecation notes documenting the aliasing.
|
||||
|
||||
---
|
||||
|
||||
## 5. Provider
|
||||
|
||||
### TranslationProvider
|
||||
|
||||
- [ ] Wraps app with i18next instance. Accepts `config`, `language`, `bundles`. OTel span on init.
|
||||
- [ ] Write test + md.
|
||||
|
||||
---
|
||||
|
||||
## 6. Hooks
|
||||
|
||||
### useTranslation
|
||||
|
||||
- [ ] Wraps `react-i18next` `useTranslation`. Throws `TranslationError` in `NODE_ENV !== 'production'` when no provider is mounted; logs warning via `@suaveplan/logger` in production.
|
||||
- [ ] Write `use-translation.test.ts` (≤500 lines): happy path, missing-key stub-guard dev throw, prod soft-fail, namespace overrides. `{ timeout: 5000 }`.
|
||||
- [ ] Write md.
|
||||
|
||||
### useErrorMessage
|
||||
|
||||
- [ ] Maps `SuaveplanError` instances to i18n strings via error code lookup. Falls back to `error.message`.
|
||||
- [ ] Write test + md.
|
||||
|
||||
### useDirection
|
||||
|
||||
- [ ] Returns `{ direction: 'ltr' | 'rtl', locale }` based on current i18next language. RTL languages: ar, he, fa, ur.
|
||||
- [ ] Write test + md.
|
||||
|
||||
---
|
||||
|
||||
## 7. HOC
|
||||
|
||||
### withTranslation
|
||||
|
||||
- [ ] Higher-order component wrapping a component with `t` and `i18n` props injected.
|
||||
- [ ] Write test + md.
|
||||
|
||||
---
|
||||
|
||||
## 8. Utils
|
||||
|
||||
- [ ] `utils.ts` — `formatDate(date, locale)`, `formatCurrency(amount, currency, locale)`, `negotiateLanguage(preferred, available)`.
|
||||
- [ ] Write `utils.test.ts` (≤500 lines). `{ timeout: 5000 }`.
|
||||
- [ ] Write md.
|
||||
|
||||
---
|
||||
|
||||
## 9. Storybook
|
||||
|
||||
- [ ] `provider.stories.tsx` — language switcher playground (dropdown to switch en/de/ar/fr).
|
||||
- [ ] `rtl.stories.tsx` — Arabic layout with mirrored direction.
|
||||
- [ ] `plurals.stories.tsx` — count-based plural form demo.
|
||||
- [ ] `formatting.stories.tsx` — date + currency formatting bridge.
|
||||
|
||||
---
|
||||
|
||||
## 10. E2E
|
||||
|
||||
- [ ] `e2e/translate.spec.ts` — Playwright:
|
||||
- Switch language from English to German; verify UI strings change.
|
||||
- Switch to Arabic; verify `dir="rtl"` applied to layout.
|
||||
- Test lazy-bundle load; verify Suspense fallback then content.
|
||||
- Verify missing-key counter increments when a key is absent.
|
||||
|
||||
---
|
||||
|
||||
## 11. Verify and publish
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-translate` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-translate` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/react-translate`.
|
||||
- [ ] Archive change folder.
|
||||
Reference in New Issue
Block a user