PSA/ee/docs/plans/2026-06-10-i18n-formatting-and-gaps/PRD.md

PRD — i18n Hardening: Locale-Aware Formatting, Gap Backfill, Pluralization, CI Enforcement

• Slug: 2026-06-10-i18n-formatting-and-gaps
• Date: 2026-06-10
• Status: Draft

Summary

Close the remaining systemic i18n gaps that sit around string translation rather than in it. Five phases, each independently shippable as a PR:

Phase	Area	Size
P1	Locale-aware formatting components + pseudo-locales in dev mode	~8 files
P2	Backfill 555 missing English locale keys (+ 7 locale translations)	~20 namespaces
P3	Translate skipped surfaces: msp-composition client/contact tabs + interactions feeds	6 components
P4	Pluralization: migrate dead legacy _plural keys, fix CLDR-unaware validator	4 keys + validator
P5	CI enforcement: find-missing-i18n-keys.cjs in CI with full path triggers	1 workflow

Problem

1. Formatting ignores locale. CurrencyInput, DatePicker, DateTimePicker, Calendar, and ReportEngine hardcode en-US/MM/dd/yyyy, so even fully translated screens render US formats for all users.
2. 555 keys referenced in code don't exist in English locale files (find-missing-i18n-keys.cjs), so users see default-value fallbacks or raw keys. Concentrated in workflows (131), email-providers (111), integrations (81), features/tickets (81), clients (54), assets (40), user-activities (37).
3. packages/msp-composition was never claimed by any translation batch. The MSP i18n plans were organized by feature package; the composition layer that renders the Tickets/Assets tabs on client and contact pages (MspClientTickets, MspClientAssets, MspContactTickets) is fully hardcoded. The interactions feeds (InteractionsFeed, OverallInteractionsFeed, SchedulingInteractionDetails) were similarly skipped.
4. Legacy key_plural keys are dead. i18next v25 runs in v4 plural mode (no compatibilityJSON is set anywhere), so the 4 legacy _plural keys in en/msp/settings.json and en/msp/profile.json never resolve. Worse, validate-translations.cjs is CLDR-unaware: it falsely warns on Polish _few/_many forms (which are required for Polish) while not flagging genuinely missing plural forms.
5. Pseudo-locales (xx/yy) were meant to be selectable in dev mode but filterPseudoLocales() strips them unconditionally — the original intent slipped through the cracks.
6. No CI guard against the "missing key" class of regression. find-missing-i18n-keys.cjs exits 1 on failure but is manual-only, and the validate-translations.yml workflow only triggers on locale-file paths, so component changes never run it.

Goals

1. All shared formatting components and ReportEngine derive formats from the active locale (purely locale-derived; no new preference UI).
2. Pseudo-locales appear in all language pickers when NODE_ENV === 'development'.
3. find-missing-i18n-keys.cjs reports 0 missing keys; backfilled keys translated into all 7 non-English production locales + regenerated pseudo-locales.
4. Client-page Tickets/Assets/Interactions tabs (and contact-page tickets) are fully translated.
5. All plural keys use i18next v4 count-based forms (_one/_other/_few/_many per CLDR); validator understands CLDR plural categories per locale.
6. Both i18n scripts run in CI on every PR that touches components or locale files.

Non-goals

• Transactional EJS emails (verify/reset/welcome) — explicitly deferred.
• Invoice PDF / AssemblyScript-WASM renderer localization.
• Page metadata (generateMetadata) localization.
• RTL support.
• Explicit user-facing date-format preference (separate future effort; this plan stays locale-derived so that effort layers on top).
• ESLint rule against hardcoded JSX strings (deferred; revisit after P5 proves out).
• Completing the pt locale (stays in INCOMPLETE_LOCALES).
• Translating ui-reflection label/helperText automation metadata (not user-visible UI).

Requirements

P1a — Locale-aware formatting components

Foundation: add useOptionalI18n() to packages/ui/src/lib/i18n/client.tsx — same as useI18n() but returns null outside I18nProvider (DatePicker/CurrencyInput render on auth pages without the provider; they must not crash). Locale falls back to LOCALE_CONFIG.defaultLocale. packages/ui/src/lib/dateFnsLocale.ts already maps all 10 locales to date-fns locale objects.

Component	Change
DatePicker.tsx:117	format(value, 'P', { locale: getDateFnsLocale(locale) }); optional displayFormat prop escape hatch
DateTimePicker.tsx:182	Explicit timeFormat prop wins ('P hh:mm a' / 'P HH:mm'); unset → 'P p'
Calendar.tsx	Pass date-fns locale to DayPicker; localize MonthYearSelect caption format() calls
CurrencyInput.tsx	Locale-aware format and parse (see risk below)
PrintOptionsDialog.tsx:67	formatDefaultPrintValue uses active locale instead of bare toLocaleString()
ReportEngine.ts (both copies)	locale?: string on ReportExecutionOptions, threaded to all 5 format* call sites; default 'en-US' preserves behavior for untouched callers. executeReport action resolves locale via getHierarchicalLocaleAction from @alga-psa/tenancy

Critical risk — CurrencyInput parsing: current code does raw.replace(/,/g, '') + parseFloat. If formatting becomes French (1 234,56) but parsing stays US, typing 12,5 yields 1250 — silent 100× data corruption. Formatting and parsing must change as a unit: derive group/decimal separators from Intl.NumberFormat(locale).formatToParts(), strip group separators, normalize the decimal separator to . before parseFloat. Round-trip tests for en, de, fr, pl mandatory. Only 2 usage sites, limiting blast radius.

Audit step: review DatePicker's 37+ call sites for any that rely on MM/dd/yyyy output for parsing/serialization rather than pure display.

P1b — Pseudo-locales in dev mode

Single change point: filterPseudoLocales() in packages/core/src/lib/i18n/config.ts:127 keeps xx/yy when process.env.NODE_ENV === 'development'. All 7 pickers already route through it. INCOMPLETE_LOCALES (pt) stays filtered even in dev. Precedent for NODE_ENV branching exists in the same file (cookie.secure, i18next debug); Next.js inlines it client-side. Rebuild packages/core dist (npx nx build core).

P2 — Missing English keys backfill (555)

Backfill en first (defaults are mostly recoverable from defaultValue in the t() calls), then translate to fr/es/de/nl/it/pl/pt, then regenerate pseudo-locales. Namespace order by user impact:

Namespace	Keys	Primary files
msp/workflows	131	WorkflowRunList, WorkflowDesigner, RunStudioShell (EE)
msp/email-providers	111	InboundEmailRuleForm (83 refs)
msp/integrations	81	LevelIoIntegrationSettings (61), InboundEmailRulesManager
features/tickets	81	TicketChecklistSection (30), TicketingDashboard (23)
msp/clients	54	Clients.tsx, MeetingAttendeesPicker, ClientDetails
msp/assets	40	AssetDashboardClient (37)
msp/user-activities	37	ActivitiesTableFilters, AdHocDetailPanel
~13 others	~120	incl. cross-namespace actions.print/actions.printOptions cluster (print/export feature shipped without any keys)

Exit criterion: node scripts/find-missing-i18n-keys.cjs exits 0.

P3 — Skipped surfaces

Component	Location	Namespace
MspClientTickets.tsx	packages/msp-composition/src/clients/	msp/clients
MspClientAssets.tsx	packages/msp-composition/src/clients/	msp/clients
MspContactTickets.tsx	packages/msp-composition/src/clients/	msp/contacts
InteractionsFeed.tsx	packages/clients/src/components/interactions/	msp/clients
OverallInteractionsFeed.tsx	packages/clients/src/components/interactions/	msp/clients
SchedulingInteractionDetails.tsx	packages/scheduling/src/components/shared/	msp/schedule

Wire useTranslation(), add keys to en + 7 locales + pseudo-locales. Verify ROUTE_NAMESPACES already loads the chosen namespaces on /msp/clients and /msp/contacts (it does today). Sweep the other 16 msp-composition files and document that they have no user-visible strings (providers/wrappers); record per-file in SCRATCHPAD.

P4 — Pluralization

Inventory (confirmed): 4 legacy _plural keys across en/msp/settings.json + en/msp/profile.json (teams.details.memberCount_plural, interaction-types imported_plural, security.sessions.subtitle_plural ×2) plus counterparts in 7 locales.

1. Migrate to i18next v4 forms: _one/_other for English; correct CLDR set per locale (Polish: _one/_few/_many/_other).
2. Fix consumers doing manual plural selection — AdminSessionManagement.tsx:239-240 picks subtitle vs subtitle_plural in code; replace with a single t() call using count. Note: subtitle interpolates two counts (sessionCount, userCount); pass count: sessionCount for plural selection while keeping both interpolation variables.
3. Make validate-translations.cjs CLDR-aware via Intl.PluralRules(locale).resolvedOptions().pluralCategories: stop false-warning on Polish _few/_many; flag locales missing required plural categories for a key that has plural forms in English.
4. Verify generate-pseudo-locales.cjs carries plural-suffixed keys through correctly.

Exit criterion: validate-translations.cjs passes with 0 warnings.

P5 — CI enforcement

• Add a find-missing-i18n-keys job to .github/workflows/validate-translations.yml (script already exits 1 on failure).
• Expand workflow paths triggers to include component sources: packages/**, server/src/**, ee/server/src/**, scripts/find-missing-i18n-keys.cjs (currently locale files only — component changes never trigger validation).
• Must land after P2 (otherwise CI is red on arrival).

Rollout

Five PRs, one per phase, in order P1 → P2 → P3 → P4 → P5 (P3/P4 may proceed in parallel after P2; P5 strictly after P2). Each phase leaves main green: validation scripts pass, existing .i18n.test.* audit suites pass.

Risks

Risk	Mitigation
CurrencyInput locale parsing corrupts amounts (100× errors)	Format+parse change as a unit; round-trip tests across 4 locales; only 2 usage sites
DatePicker call sites depending on fixed MM/dd/yyyy output	Pre-change audit of all 37+ call sites; displayFormat escape hatch
555-key backfill drifts from on-screen defaults	Source keys from defaultValue in code; pseudo-locale visual QA (unlocked by P1b)
Machine-translated backfill quality in 7 locales	Same translation process as prior MSP batches; pt already flagged incomplete
Plural migration changes rendered strings	Per-key before/after snapshot in tests; only 4 keys
CI job surfaces pre-existing failures on unrelated PRs	Land P5 only after P2 zeroes the count

Open Questions

1. Namespace for interactions feed keys: reuse msp/clients interactions.* prefix (where InteractionDetails/QuickAddInteraction keys already live) — assumed yes.
2. Should DateTimePicker's timeFormat default flip to locale-derived everywhere, or keep 12h default where currently explicit? Assumed: explicit prop wins, unset becomes locale-derived.
3. ESLint hardcoded-string rule — deferred to a follow-up after P5; revisit then.

Acceptance Criteria / Definition of Done

• A user with fr locale sees dd/MM/yyyy-style dates in DatePicker/DateTimePicker/Calendar, French month/weekday names, and 1 234,56-style numbers in CurrencyInput — and typed 12,5 parses as 12.5.
• Reports render dates/numbers/currency in the viewer's hierarchical locale; callers passing no locale get unchanged en-US output.
• In dev mode, all language pickers list Pseudo (xx) and Pseudo (yy); in production builds they don't. pt hidden in both.
• node scripts/find-missing-i18n-keys.cjs exits 0.
• Client page Tickets/Assets/Interactions tabs and contact page Tickets tab render fully in the active locale (verified via pseudo-locale).
• No _plural-suffixed keys remain in any locale file; validate-translations.cjs passes with 0 errors and 0 warnings; Polish plural forms render correctly for counts 1, 2, 5.
• Both scripts run in CI on PRs touching packages/**, server/src/**, ee/server/src/**, or locale files.