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

SCRATCHPAD — MSP i18n Infrastructure Sprint (Phase 0)

Key Discoveries

Current State (Pre-Phase 0)

• I18N_CONFIG.ns is ['common', 'client-portal', 'msp'] — ALL namespaces loaded eagerly on every page
• msp.json exists for all 7 languages (en, fr, es, de, nl, it, pl) — ~73 lines, ~60 keys
• msp/ directory does NOT yet exist under any locale folder
• Zero MSP components currently call useTranslation('msp') — the namespace exists but is unused in component code
• Phase 1 test file at server/src/test/unit/i18n/mspI18nPhase1.test.ts references 'msp' namespace (lines 280, 284, 285) — needs update to 'msp/core'
• I18nWrapper currently does NOT use usePathname() — it only resolves locale, not route-specific namespaces
• I18nProvider does NOT accept a namespaces prop — no lazy loading mechanism exists yet
• packages/core/src/lib/i18n/config.ts is a near-exact copy of packages/ui/src/lib/i18n/config.ts (exists to break circular dependency: ui → analytics → tenancy → ui)
• http-backend loadPath /locales/{{lng}}/{{ns}}.json naturally resolves nested paths (e.g., msp/core → /locales/en/msp/core.json) — no config change needed for nested namespaces

Key Infrastructure Already in Place

Component	Path	Status
I18nProvider	packages/ui/src/lib/i18n/client.tsx	Exists, needs namespaces prop
I18nWrapper	packages/tenancy/src/components/i18n/I18nWrapper.tsx	Exists, needs usePathname() + namespace passing
i18n config (ui)	packages/ui/src/lib/i18n/config.ts	Exists, needs ROUTE_NAMESPACES + getNamespacesForRoute()
i18n config (core)	packages/core/src/lib/i18n/config.ts	Exists, needs sync with ui config
useFormatters()	packages/ui/src/lib/i18n/client.tsx:214-257	Exists, locale-aware (uses useI18n() context)
Feature flag	msp-i18n-enabled	Exists, gates MSP i18n
Phase 1 tests	server/src/test/unit/i18n/mspI18nPhase1.test.ts	Exists, needs 'msp' → 'msp/core' update
MSP layout (standard)	server/src/app/msp/layout.tsx + MspLayoutClient.tsx	Exists, conditionally wraps I18nWrapper
MSP layout (EE)	ee/server/src/app/msp/layout.tsx + MspLayoutClient.tsx	Exists, conditionally wraps I18nWrapper
Translation files	server/public/locales/{lang}/msp.json	7 files, to be renamed to msp/core.json

useTranslation('msp') References

Grep found zero references in actual source code — only in documentation/plan files:

• docs/plans/2026-02-19-msp-i18n-infrastructure-sprint/features.json
• docs/plans/2026-02-19-msp-i18n-infrastructure-sprint/PRD.md
• docs/plans/2026-02-18-msp-i18n-full-translation-plan.md
• docs/plans/2026-02-12-msp-i18n-phase1/SCRATCHPAD.md

This means F017 ("Update all useTranslation('msp') references") only affects the Phase 1 test file (lines 280, 284, 285) and the config ns array. No component code references 'msp' namespace directly.

Decisions

Decision	Rationale
ns: ['common'] — only common on init	Future-proof; as 12+ MSP namespaces are added, eager loading would be 20+ HTTP requests per page
Route-based lazy loading via ROUTE_NAMESPACES	Deterministic — developer adds route entry, namespaces auto-load. No guessing.
getNamespacesForRoute() uses exact → longest prefix → fallback	Handles both exact routes (/msp/tickets) and sub-routes (/msp/tickets/123)
Pseudo-locales xx/yy available in all environments	Visual QA for extraction completeness; useful in staging/production for verification
Pseudo-locale files NOT committed to git	They're generated artifacts; add server/public/locales/xx/ and yy/ to .gitignore
msp.json → msp/core.json rename now	Establishes the msp/ directory convention before batch 1 adds msp/settings.json
I18nWrapper uses usePathname() from next/navigation	Standard Next.js hook; re-renders on route change, triggering namespace re-resolution

Implementation Order

Recommended order to minimize breakage:

1. Rename msp.json → msp/core.json (F016) — file system change, update test references (F017, F023)
2. Add ROUTE_NAMESPACES + getNamespacesForRoute() (F002, F003, F018) — config additions, no behavioral change yet
3. Change I18N_CONFIG.ns to ['common'] (F001) — behavioral change, client portal will need route-based loading from this point
4. Update I18nProvider (F004, F005) — accept namespaces prop, add loadNamespaces() effect
5. Update I18nWrapper (F006, F007, F008) — usePathname() + pass namespaces to I18nProvider
6. Sync core config (F019) — copy changes to packages/core
7. Add pseudo-locale support (F009-F015) — script + config
8. Verify (F020-F024) — client portal, MSP flag off, MSP flag on, tests, build

Key File Paths

Purpose	Path
i18n config (ui)	packages/ui/src/lib/i18n/config.ts
i18n config (core)	packages/core/src/lib/i18n/config.ts
I18nProvider	packages/ui/src/lib/i18n/client.tsx
I18nWrapper	packages/tenancy/src/components/i18n/I18nWrapper.tsx
Phase 1 tests	server/src/test/unit/i18n/mspI18nPhase1.test.ts
MSP layout (standard)	server/src/app/msp/layout.tsx
MSP layout client (standard)	server/src/app/msp/MspLayoutClient.tsx
MSP layout (EE)	ee/server/src/app/msp/layout.tsx
MSP layout client (EE)	ee/server/src/app/msp/MspLayoutClient.tsx
Translation files	server/public/locales/{lang}/msp.json (current) → server/public/locales/{lang}/msp/core.json (target)
Pseudo-locale script	scripts/generate-pseudo-locale.ts (new)
Feature flags	server/src/lib/feature-flags/featureFlags.ts

Gotchas

• Config duplication: packages/ui/src/lib/i18n/config.ts and packages/core/src/lib/i18n/config.ts MUST stay in sync. The core copy exists to break a circular dependency (ui → analytics → tenancy → ui).
• http-backend loadPath: /locales/{{lng}}/{{ns}}.json already resolves nested paths — msp/core becomes /locales/en/msp/core.json. No backend config change needed.
• Client portal must keep working: After changing ns: ['common'], the client portal relies on I18nWrapper → getNamespacesForRoute() to load client-portal namespace. Test this carefully.
• Build memory: Phase 1 build needed NODE_OPTIONS=--max-old-space-size=8192. Expect the same here.
• Pseudo-locale .gitignore: Remember to add server/public/locales/xx/ and server/public/locales/yy/ to .gitignore.
• i18next.loadNamespaces(): This is an async operation. The I18nProvider effect needs to handle the promise and potentially show a loading state while namespaces are being fetched.
• usePathname() requires 'use client': I18nWrapper is already a client component, so this is fine.
• ROUTE_NAMESPACES entries for future routes: Include entries for routes that don't have feature namespace files yet (e.g., /msp/settings with just ['common', 'msp/core']). Missing namespace files simply won't be fetched — i18next http-backend handles 404s gracefully.

Commands

# Run Phase 1 tests (to verify msp/core rename doesn't break them)
npx jest server/src/test/unit/i18n/mspI18nPhase1.test.ts

# Build with enough memory
NODE_OPTIONS=--max-old-space-size=8192 npm run build

# Generate pseudo-locale (after script is created)
npx ts-node scripts/generate-pseudo-locale.ts --locale xx --fill 1111
npx ts-node scripts/generate-pseudo-locale.ts --locale yy --fill 5555

# Check for remaining 'msp' namespace references (should be zero after rename)
grep -r "useTranslation('msp')" --include="*.ts" --include="*.tsx" server/ packages/ ee/
grep -r "'msp'" server/src/test/unit/i18n/

# Verify msp/core.json exists for all languages
ls server/public/locales/*/msp/core.json

# Verify old msp.json removed
ls server/public/locales/*/msp.json  # should fail (files removed)

Updates

• 2026-02-20: Updated I18N_CONFIG.ns in packages/ui/src/lib/i18n/config.ts to ['common'] for lazy namespace loading (F001).
• 2026-02-20: Added ROUTE_NAMESPACES mapping in packages/ui/src/lib/i18n/config.ts for client portal and MSP routes (F002).
• 2026-02-20: Added getNamespacesForRoute() helper with exact + longest prefix matching in packages/ui/src/lib/i18n/config.ts (F003).
• 2026-02-20: Added optional namespaces prop to I18nProvider in packages/ui/src/lib/i18n/client.tsx (F004).
• 2026-02-20: I18nProvider now loads missing namespaces on route changes via i18next.loadNamespaces() (F005).
• 2026-02-20: I18nWrapper now reads the current route via usePathname() (F006).
• 2026-02-20: I18nWrapper now resolves namespaces with getNamespacesForRoute() and passes them to I18nProvider (F007).
• 2026-02-20: I18nWrapper memoizes namespace resolution to update on pathname changes (F008).
• 2026-02-20: Added scripts/generate-pseudo-locale.ts with CLI args parsing for pseudo-locale generation (F009).
• 2026-02-20: Pseudo-locale script now walks all English JSON namespaces recursively (including nested features/ and msp/) (F010).
• 2026-02-20: Pseudo-locale output preserves directory structure under server/public/locales/<locale>/ (F011).
• 2026-02-20: Pseudo-locale generator replaces all leaf string values with the fill token (F012).
• 2026-02-20: Pseudo-locale generator preserves {{variables}} in transformed strings (F013).
• 2026-02-20: Pseudo-locale generator preserves JSON key structure (nested objects/arrays) (F014).
• 2026-02-20: Added pseudo-locales xx and yy to LOCALE_CONFIG.supportedLocales in UI config (F015).
• 2026-02-20: Renamed server/public/locales/{lang}/msp.json to server/public/locales/{lang}/msp/core.json for all locales (F016).
• 2026-02-20: Confirmed no useTranslation('msp') references in code; remaining namespace updates handled in Phase 1 tests (F017).
• 2026-02-20: ROUTE_NAMESPACES entries use msp/core for MSP routes (F018).
• 2026-02-20: Synced packages/core/src/lib/i18n/config.ts with UI config (namespaces, route mapping, pseudo-locales) (F019).
• 2026-02-20: Updated Phase 1 i18n tests to use msp/core namespace and file paths (F023).
• 2026-02-20: Added tracking items F025/T053 to ensure pseudo-locale outputs are gitignored per PRD rollout guidance.
• 2026-02-20: Ignored pseudo-locale outputs in .gitignore (server/public/locales/xx/, server/public/locales/yy/) (F025).
• 2026-02-20: Added Phase 0 i18n test suite and made pseudo-locale generator ESM-safe; validated UI I18N_CONFIG.ns via tests (T001).
• 2026-02-20: Verified core I18N_CONFIG.ns via Phase 0 test coverage (T002).
• 2026-02-20: Confirmed ROUTE_NAMESPACES export via Phase 0 tests (T003).
• 2026-02-20: Verified /client-portal route namespace mapping in Phase 0 tests (T004).
• 2026-02-20: Completed T005 checklist entry — ROUTE_NAMESPACES maps '/client-portal/tickets' to ['common', 'client-portal', 'features/tickets']
• 2026-02-20: Completed T006 checklist entry — ROUTE_NAMESPACES maps '/msp' to ['common', 'msp/core'] (at minimum)
• 2026-02-20: Completed T007 checklist entry — ROUTE_NAMESPACES maps '/msp/tickets' to ['common', 'msp/core', 'features/tickets']
• 2026-02-20: Completed T008 checklist entry — ROUTE_NAMESPACES maps '/msp/settings' to ['common', 'msp/core']
• 2026-02-20: Completed T009 checklist entry — All ROUTE_NAMESPACES MSP entries use 'msp/core' (not 'msp')
• 2026-02-20: Completed T010 checklist entry — getNamespacesForRoute is exported from packages/ui/src/lib/i18n/config.ts
• 2026-02-20: Completed T011 checklist entry — getNamespacesForRoute('/msp/tickets') returns namespaces including 'msp/core' and 'features/tickets'
• 2026-02-20: Completed T012 checklist entry — getNamespacesForRoute('/client-portal/billing') returns namespaces including 'client-portal' and 'features/billing'
• 2026-02-20: Completed T013 checklist entry — getNamespacesForRoute exact match takes priority over prefix match (e.g., '/msp/tickets' exact entry wins over '/msp' prefix)
• 2026-02-20: Completed T014 checklist entry — getNamespacesForRoute uses longest prefix match when no exact match (e.g., '/msp/tickets/123' matches '/msp/tickets' entry)
• 2026-02-20: Completed T015 checklist entry — getNamespacesForRoute falls back to ['common'] for unknown routes
• 2026-02-20: Completed T016 checklist entry — I18nProvider accepts optional namespaces prop (string[])
• 2026-02-20: Completed T017 checklist entry — I18nProvider calls i18next.loadNamespaces() for namespaces not yet loaded when namespaces prop is provided
• 2026-02-20: Completed T018 checklist entry — I18nProvider loads new namespaces when namespaces prop changes (simulating route navigation)
• 2026-02-20: Completed T019 checklist entry — I18nProvider does not re-load namespaces that are already loaded
• 2026-02-20: Completed T020 checklist entry — I18nWrapper uses usePathname() to read the current route
• 2026-02-20: Completed T021 checklist entry — I18nWrapper calls getNamespacesForRoute(pathname) and passes result as namespaces prop to I18nProvider
• 2026-02-20: Completed T022 checklist entry — I18nWrapper re-resolves namespaces when pathname changes (route navigation triggers new namespace resolution)
• 2026-02-20: Completed T023 checklist entry — scripts/generate-pseudo-locale.ts exists and is runnable
• 2026-02-20: Completed T024 checklist entry — Pseudo-locale script accepts --locale and --fill CLI arguments
• 2026-02-20: Completed T025 checklist entry — Pseudo-locale script with --locale xx --fill 1111 generates files under server/public/locales/xx/
• 2026-02-20: Completed T026 checklist entry — Pseudo-locale script reads all English namespace JSON files including nested features/ and msp/ directories
• 2026-02-20: Completed T027 checklist entry — Pseudo-locale script output preserves directory structure (e.g., features/tickets.json -> xx/features/tickets.json)
• 2026-02-20: Completed T028 checklist entry — Pseudo-locale script replaces all leaf string values with the fill string
• 2026-02-20: Completed T029 checklist entry — Pseudo-locale script preserves {{variables}} within fill strings (e.g., '1111 {{name}} 1111' for a value containing {{name}})
• 2026-02-20: Completed T030 checklist entry — Pseudo-locale script preserves multiple {{variables}} in a single value (e.g., 'Page {{current}} of {{total}}')
• 2026-02-20: Completed T031 checklist entry — Pseudo-locale script preserves JSON key structure exactly (nested objects maintained, no flattening)
• 2026-02-20: Completed T032 checklist entry — Pseudo-locale output for common.json has same key structure as en/common.json but all leaf values replaced
• 2026-02-20: Completed T033 checklist entry — Pseudo-locales xx and yy are added to LOCALE_CONFIG.supportedLocales
• 2026-02-20: Completed T034 checklist entry — Pseudo-locales xx and yy are present in LOCALE_CONFIG.supportedLocales in all environments
• 2026-02-20: Completed T035 checklist entry — Pseudo-locales xx and yy are added to I18N_CONFIG.supportedLngs
• 2026-02-20: Completed T036 checklist entry — server/public/locales/en/msp/core.json exists with same content as old msp.json
• 2026-02-20: Completed T037 checklist entry — server/public/locales/{lang}/msp/core.json exists for all 7 languages (en, fr, es, de, nl, it, pl)
• 2026-02-20: Completed T038 checklist entry — Old server/public/locales/{lang}/msp.json files are removed for all 7 languages
• 2026-02-20: Completed T039 checklist entry — No useTranslation('msp') references remain in source code (only 'msp/core')
• 2026-02-20: Completed T040 checklist entry — Phase 1 test file references updated from 'msp' to 'msp/core' namespace
• 2026-02-20: Completed T041 checklist entry — i18next.t('nav.home', { ns: 'msp/core' }) returns correct English translation after namespace rename
• 2026-02-20: Completed T042 checklist entry — packages/core/src/lib/i18n/config.ts I18N_CONFIG.ns is synced to ['common']
• 2026-02-20: Completed T043 checklist entry — packages/core/src/lib/i18n/config.ts LOCALE_CONFIG matches packages/ui/src/lib/i18n/config.ts (including any pseudo-locale changes)
• 2026-02-20: Completed T044 checklist entry — Client portal at /client-portal loads common and client-portal namespaces correctly
• 2026-02-20: Completed T045 checklist entry — Client portal at /client-portal/tickets loads features/tickets namespace in addition to common and client-portal
• 2026-02-20: Completed T046 checklist entry — Client portal translations continue displaying correctly after config changes (no regressions)
• 2026-02-20: Completed T047 checklist entry — MSP portal with flag OFF: no I18nWrapper rendered, no namespace HTTP requests for msp/core
• 2026-02-20: Completed T048 checklist entry — MSP portal with flag OFF: layout renders identically to before changes (zero behavior change)
• 2026-02-20: Completed T049 checklist entry — MSP portal with flag ON: msp/core namespace loads correctly via lazy loading
• 2026-02-20: Completed T050 checklist entry — MSP portal with flag ON: navigating to /msp/tickets loads features/tickets namespace in addition to msp/core
• 2026-02-20: Aligned client-portal and appointments locale keys across languages and updated Phase 1 i18n expectations; Phase 1 vitest now passes (T051).
• 2026-02-20: Added pseudo-locale fallback mappings to date-fns locale utilities and confirmed npm run build succeeds (T052).
• 2026-02-20: Verified pseudo-locale output directories are gitignored (T053).
• 2026-02-20: Validated client portal namespace routing via Phase 0 tests (F020).
• 2026-02-20: Confirmed MSP flag-off behavior remains unchanged via Phase 1 layout checks (F021).
• 2026-02-20: Verified MSP flag-on namespace routing loads msp/core and feature namespaces (F022).
• 2026-02-20: Build completed successfully with pseudo-locale support included (F024).