PSA/ee/docs/plans/2026-02-19-msp-i18n-infrastructure-sprint/PRD.md

# PRD — MSP i18n Infrastructure Sprint (Phase 0)

- Slug: `msp-i18n-infrastructure-sprint`
- Date: `2026-02-19`
- Status: Draft
- Parent plan: `docs/plans/2026-02-18-msp-i18n-full-translation-plan.md`
- Depends on: `docs/plans/2026-02-12-msp-i18n-phase1/` (completed)

## Summary

Prepare the i18n infrastructure for batch translation of the entire MSP portal. This sprint makes five changes: (a) lazy namespace loading so only route-relevant namespaces are fetched, (b) pseudo-locale generation for visual QA, (c) rename `msp.json` to `msp/core.json`, (d) update I18nWrapper to load namespaces by route, and (e) sync the core config package. When complete, any subsequent translation batch can be added as a new namespace file without architectural changes.

## Problem

Phase 1 established the MSP i18n foundation (feature flag, I18nWrapper, namespace restructuring, language settings). But the current config eagerly loads ALL namespaces on every page (`ns: ['common', 'client-portal', 'msp']`). As 12+ MSP feature namespaces are added, this becomes 20+ HTTP requests per page load. Additionally, there's no way to visually verify that all hardcoded strings have been extracted. The `msp.json` filename doesn't match the planned `msp/core.json` convention.

## Goals

- **G1**: Change i18next to only load `common` on init, with additional namespaces loaded on-demand per route
- **G2**: Add `ROUTE_NAMESPACES` mapping and `getNamespacesForRoute()` helper to config
- **G3**: Update `I18nWrapper` to use `usePathname()` and load route-appropriate namespaces
- **G4**: Create `scripts/generate-pseudo-locale.ts` that generates `xx` and `yy` pseudo-locale files
- **G5**: Add pseudo-locales (`xx`, `yy`) to config
- **G6**: Rename `msp.json` to `msp/core.json` for all 7 languages
- **G7**: Update all references from `useTranslation('msp')` to `useTranslation('msp/core')`
- **G8**: Keep `packages/core/src/lib/i18n/config.ts` in sync with `packages/ui/src/lib/i18n/config.ts`
- **G9**: Client portal continues working with zero regressions
- **G10**: MSP portal with flag OFF continues working with zero regressions

## Non-goals

- Translating any new MSP page content (that's Batch 1+)
- Creating the actual `msp/settings.json` or other feature namespace files
- Server-side namespace preloading or caching
- CI/CD translation validation pipeline
- Changing the feature flag behavior

## Users and Primary Flows

### Persona: Developer adding a translation batch

**Flow 1: Adding a new MSP feature namespace**
1. Developer creates `server/public/locales/en/msp/<feature>.json`
2. Developer adds route entry to `ROUTE_NAMESPACES` in config
3. Namespaces auto-load when users navigate to that route
4. No changes to I18nWrapper, I18nProvider, or layout files needed

**Flow 2: Visual QA with pseudo-locales**
1. Developer runs `npx ts-node scripts/generate-pseudo-locale.ts --locale xx --fill 1111`
2. Pseudo-locale files generated for all existing namespaces
3. Developer enables `msp-i18n-enabled` flag locally
4. Developer switches browser to `xx` locale
5. All translated strings show `1111`; untranslated strings remain in English (= missed extraction)

### Persona: End user (MSP portal)

**Flow 3: Flag OFF (default) — no change**
- MSP portal stays English-only, identical to today
- No additional HTTP requests for namespace files

**Flow 4: Flag ON — navigating MSP portal**
- Only `common` + `msp/core` + route-specific namespaces are loaded
- No loading of irrelevant namespaces (e.g., `msp/settings` doesn't load on `/msp/tickets`)

### Persona: End user (Client portal)

**Flow 5: Client portal — no change**
- Client portal continues loading `common` + `client-portal` + relevant `features/*` namespaces
- Zero regressions from namespace renaming or config changes

## UX / UI Notes

No user-facing UI changes in this sprint. All changes are developer-facing infrastructure.

## Requirements

### Functional Requirements

#### Lazy Namespace Loading
- **FR1**: `I18N_CONFIG.ns` changed from `['common', 'client-portal', 'msp']` to `['common']`
- **FR2**: `ROUTE_NAMESPACES` constant exported from `packages/ui/src/lib/i18n/config.ts` mapping route prefixes to namespace arrays
- **FR3**: `getNamespacesForRoute(pathname: string): string[]` function exported from config — exact match first, then longest prefix match, fallback to `['common']`
- **FR4**: `I18nWrapper` reads `usePathname()` and passes resolved namespaces to `I18nProvider`
- **FR5**: `I18nProvider` calls `i18next.loadNamespaces()` for any namespaces not yet loaded when route changes
- **FR6**: `I18nProvider` accepts optional `namespaces` prop for route-specific namespace list

#### Pseudo-Locale Generation
- **FR7**: `scripts/generate-pseudo-locale.ts` script exists and is runnable with `npx ts-node`
- **FR8**: Script accepts `--locale <code>` and `--fill <string>` CLI arguments
- **FR9**: Script reads all English namespace JSON files (including nested `features/` and `msp/` directories)
- **FR10**: Script outputs corresponding files under `server/public/locales/<locale>/` preserving directory structure
- **FR11**: Script replaces all leaf string values with the fill string
- **FR12**: Script preserves `{{variables}}` within the fill string (e.g., `"1111 {{name}} 1111"`)
- **FR13**: Script preserves JSON key structure exactly
- **FR14**: Pseudo-locales `xx` and `yy` added to `LOCALE_CONFIG.supportedLocales`

#### Namespace Rename (msp.json → msp/core.json)
- **FR15**: `server/public/locales/{lang}/msp.json` renamed to `server/public/locales/{lang}/msp/core.json` for all 7 languages
- **FR16**: All `useTranslation('msp')` references updated to `useTranslation('msp/core')`
- **FR17**: `I18N_CONFIG.ns` no longer lists `'msp'` (it now only lists `'common'`)
- **FR18**: `ROUTE_NAMESPACES` uses `'msp/core'` (not `'msp'`)

#### Config Sync
- **FR19**: `packages/core/src/lib/i18n/config.ts` updated to match any locale config changes in `packages/ui/src/lib/i18n/config.ts`

#### Backward Compatibility
- **FR20**: Client portal loads correct namespaces per route (no regressions)
- **FR21**: MSP portal with flag OFF has zero behavior change
- **FR22**: MSP portal with flag ON loads `msp/core` namespace correctly
- **FR23**: Existing Phase 1 tests continue passing (with updated namespace name `msp/core`)

## Data / API / Integrations

No database changes. No new API endpoints. Translation files served as static JSON from `server/public/locales/`.

### Key file changes

| File | Change |
|------|--------|
| `packages/ui/src/lib/i18n/config.ts` | Add `ROUTE_NAMESPACES`, `getNamespacesForRoute()`, change `ns` to `['common']`, add pseudo-locales |
| `packages/core/src/lib/i18n/config.ts` | Sync locale config changes |
| `packages/ui/src/lib/i18n/client.tsx` | `I18nProvider` accepts `namespaces` prop, calls `loadNamespaces()` on route change |
| `packages/tenancy/src/components/i18n/I18nWrapper.tsx` | Use `usePathname()` + `getNamespacesForRoute()` to pass namespaces to `I18nProvider` |
| `server/public/locales/{lang}/msp.json` | Renamed to `server/public/locales/{lang}/msp/core.json` (7 languages) |
| `scripts/generate-pseudo-locale.ts` | New file — pseudo-locale generator |

## Rollout / Migration

1. Rename `msp.json` → `msp/core.json` (7 files moved, old files removed)
2. Update config and wrapper in one PR
3. Update Phase 1 tests to reference `msp/core` instead of `msp`
4. All behind existing `msp-i18n-enabled` flag — zero user impact
5. Pseudo-locale files not committed to git (generated on demand, .gitignore the `xx/` and `yy/` directories)

## Open Questions

- Should pseudo-locale directories be gitignored or committed? (Recommendation: gitignore — they're generated artifacts)
- Should `ROUTE_NAMESPACES` include entries for routes that don't have feature namespaces yet (e.g., `/msp/settings` before `msp/settings.json` exists)? (Recommendation: yes, with just `['common', 'msp/core']` — the missing namespace will simply not be fetched until the file exists)

## Acceptance Criteria (Definition of Done)

1. `I18N_CONFIG.ns` is `['common']` — only common loaded on init
2. Navigating to `/msp/tickets` loads `common`, `msp/core`, `features/tickets` (and NOT `client-portal`, `msp/settings`, etc.)
3. Navigating to `/client-portal/billing` loads `common`, `client-portal`, `features/billing`
4. `scripts/generate-pseudo-locale.ts` generates correct pseudo files for all namespaces
5. Pseudo files preserve `{{variables}}` and JSON structure
6. `msp/core.json` exists for all 7 languages with same content as old `msp.json`
7. Old `msp.json` files are removed
8. `useTranslation('msp/core')` returns correct translations
9. Client portal has zero regressions
10. MSP portal with flag OFF has zero behavior change
11. `npm run build` succeeds
12. Phase 1 tests pass (updated to `msp/core` namespace)