PSA/ee/docs/plans/2026-04-05-msp-i18n-tickets-migration/PRD.md

# PRD — MSP i18n Batch 2b-21a: Tickets Migration

- Slug: `2026-04-05-msp-i18n-tickets-migration`
- Date: `2026-04-05`
- Status: Draft
- Parent plan: `/.ai/translation/MSP_i18n_plan.md` (Batch 2b-21a)

## Summary

Wire the existing `features/tickets` namespace into 23 unwired MSP ticket components in
`packages/tickets/src/components/`. Infrastructure is already in place: the JSON file
(`features/tickets.json`, 147 keys across 7 languages) exists and `ROUTE_NAMESPACES` already
loads it for `/msp/tickets`. The client-portal equivalents are 100% wired; this batch closes
the MSP-side gap.

## Problem

MSP users currently see translated navigation, sidebar, dashboard, and settings chrome, but
the ticket module — one of the highest-traffic MSP surfaces — is still hardcoded English.
5 of 28 production ticket components (18%) are wired; 23 remain. Because `ROUTE_NAMESPACES`
for `/msp/tickets` already loads `features/tickets`, the translation assets are downloaded
but unused. Non-English MSP users switch from a translated sidebar into an English wall of
tickets every day.

This is not a new-translation project — it is a mechanical wiring pass plus gap-filling for
MSP-specific strings (bulk operations, dispatch hooks, display settings, dashboard filters)
that the client portal didn't need.

## Goals

1. Wire `useTranslation('features/tickets')` into all 23 unwired production MSP ticket components
2. Identify and add MSP-specific keys missing from `features/tickets.json` (bulk actions,
   export options, watch list, materials, display/category settings, dashboard filters,
   agent schedule drawer)
3. Regenerate translations for 6 non-English locales + 2 pseudo-locales for any new keys
4. Preserve 100% test pass rate and zero user-facing regressions
5. Measurable: MSP tickets coverage goes from 18% → 100% of production components wired

## Non-goals

- Retranslating existing 147 keys — they already have 7-language coverage and are actively used
- Moving `features/tickets.json` keys into a separate `msp/tickets.json` — the shared namespace
  is the correct design per the parent plan
- Translating ticket content itself (titles, descriptions, comments) — those are tenant data,
  not UI chrome
- Wiring test-only components (23 `.test.tsx` files in `packages/tickets/src/components/`)
- Extending `ROUTE_NAMESPACES` — `/msp/tickets` is already wired; only verify route coverage
- Translating EE-only ticket components (ITIL extras) beyond what's exported through
  `@alga-psa/tickets/components`

## Users and Primary Flows

**Primary user:** MSP technicians, dispatchers, and managers using non-English UI language
(any of fr, es, de, nl, it, pl).

**Primary flows affected:**
1. `/msp/tickets` list — dashboard, filters, bulk actions, quick-add
2. `/msp/tickets/[id]` detail — ticket info, properties, materials, watch list, email notifications
3. `/msp/settings/*` for ticket configuration — categories, display settings, response states
4. `/msp/service-requests/*` — CategoryPicker reused from tickets package
5. Quick-create dialog (global nav) — QuickAddTicket reused in `layout/QuickCreateDialog`

## UX / UI Notes

- No visual changes. Text replaced inline via `t('key', 'English fallback')`.
- Toast messages (`toast.success` / `toast.error`) also translated.
- `throw new Error('...')` strings that surface to users (handled by error boundaries) translated;
  those that only appear in logs stay in English.
- Skeletons, badges, and style-only files (`TicketOriginBadge`, `ResponseSourceBadge`,
  `TicketListSkeleton`, `TicketDetailsSkeleton`, `AgentScheduleDrawerStyles`) have no or 0-1
  strings — confirm and skip if truly zero.

## Requirements

### Functional Requirements

**Sub-batch A: Large dashboard + quick-add components (4 files, ~150-200 strings)**

| Component | LOC | Est. strings | Key content |
|-----------|-----|--------------|-------------|
| TicketingDashboard.tsx | 2,024 | ~65 | Page title, add button, filter chrome (status/priority/assignee/response state/due date), bulk actions (move/delete/bundle), empty states, toast messages |
| QuickAddTicket.tsx | 1,596 | ~50 | Dialog title, field labels, placeholders, validation errors, toast messages, tag-creation errors |
| ticket/TicketInfo.tsx | 1,587 | ~45 | Ticket detail header, field labels, action buttons, confirmations |
| ticket/TicketProperties.tsx | 1,234 | ~45 | Side panel labels, inline edit controls, status/priority/board selects, assignment UI |

**Sub-batch B: Settings + mid-size (4 files, ~90 strings)**

| Component | LOC | Est. strings | Key content |
|-----------|-----|--------------|-------------|
| settings/CategoriesSettings.tsx | 865 | ~30 | Board/channel scoping, category tree, add/edit/delete dialogs |
| TicketExportDialog.tsx | 243 | ~25 | Export format options, column picker, date range, toast messages |
| ticket/TicketMaterialsCard.tsx | 444 | ~20 | Materials list, add material dialog, cost display, confirmations |
| settings/DisplaySettings.tsx | 250 | ~20 | Column visibility, sort options, per-user preferences |

**Sub-batch C: Small + utility components (15 files, ~50-70 strings)**

| Component | LOC | Est. strings | Notes |
|-----------|-----|--------------|-------|
| ticket/TicketWatchListCard.tsx | 512 | ~10 | Watcher list, add/remove |
| ticket/TicketEmailNotifications.tsx | 172 | ~8 | Notification toggle labels |
| ResponseStateSelect.tsx | 110 | ~6 | Response state options |
| QuickAddCategory.tsx | 274 | ~6 | Inline category creation |
| ticket/TicketDetailsContainer.tsx | 252 | ~5 | Loading/error states |
| CategoryPicker.tsx | 274 | ~5 | Picker placeholder + empty state |
| ticket/CommentMetadataDebugModal.tsx | 97 | ~4 | Debug modal (dev only, low priority) |
| ticket/TicketNavigation.tsx | 143 | ~3 | Prev/next buttons |
| TicketingDashboardContainer.tsx | 607 | ~2 | Mostly logic, few strings |
| ticket/TicketDetailsSkeleton.tsx | 155 | 0 | Skeleton — confirm zero |
| TicketOriginBadge.tsx | 143 | 0-2 | Origin labels — may need small key set |
| ticket/AgentScheduleDrawerStyles.tsx | 93 | 0 | Styles only |
| ResponseSourceBadge.tsx | 56 | 0-2 | Source labels — may need small key set |
| TicketListSkeleton.tsx | 32 | 0 | Skeleton |
| ticket/AgentScheduleDrawer.tsx | 16 | 0 | Re-export shim |

**Namespace key gaps to fill (preliminary):**

The current `features/tickets.json` covers client-portal needs. Likely MSP gaps:

- `bulk.*` — bulk move/delete/bundle actions and their toast messages
- `dashboard.*` — page title, bulk action bar, "N tickets selected"
- `export.*` — export dialog labels, format options
- `settings.categories.*` — board-scoped category management
- `settings.display.*` — column visibility, sort preferences
- `watchList.*` — watcher add/remove, empty state
- `materials.*` — materials add/edit, cost labels
- `quickAdd.*` — extended quickAdd labels beyond existing `create.*`
- `properties.*` — inline-edit side panel labels (many overlap with `fields.*` — reuse where possible)
- `errors.*` — toast error strings (session required, permission denied, partial failure)
- `validation.*` — form validation messages beyond existing `create.errors.*`

Final gap list determined during implementation — run pseudo-locale tests to surface missing keys.

### Non-functional Requirements

1. **No regressions:** all existing ticket tests pass after migration
2. **Lang-pack validation:** after every namespace edit, run
   `node scripts/generate-pseudo-locales.cjs && node scripts/validate-translations.cjs`
   and commit only when green. The validator covers key parity, missing/extra keys,
   `{{variable}}` preservation, pseudo-locale fill patterns, and Italian accent preservation
   in a single run. Pseudo-locale files (`xx/`, `yy/`) are **always** regenerated from
   English — never hand-edited.
3. **Naming convention:** follow existing `features/tickets.json` patterns (camelCase, nested under semantic groups)
4. **Fallback-safe:** all `t()` calls use `t('key', 'English fallback')` signature so missing keys don't break UI
5. **Shared with client portal:** before adding a key, check if existing `features/tickets` key covers it

## Data / API / Integrations

- No database changes
- No API changes
- No new npm dependencies
- Reuses existing `useTranslation` hook from `@alga-psa/ui/lib/i18n/client`
- Reuses existing i18next infrastructure loaded via `I18nWrapper` (already in MSP layout)

## Security / Permissions

No change. Translation is a pure presentation-layer concern.

## Observability

N/A — no new operational concerns.

## Rollout / Migration

- **Flag:** work proceeds without feature-flag gating because `I18nWrapper` in MSP layout
  already forces English fallback when `msp-i18n-enabled` is off (see parent plan Phase 0.7)
- **Per-PR rollout:** ship sub-batches A/B/C as independent PRs to keep review scope manageable
- **Deploy path:** translations are static JSON served from `server/public/locales/`; no cache
  invalidation beyond standard Next.js static-asset rebuild
- **Back-out:** each PR is independently revertable; components continue rendering English
  via `defaultValue` fallbacks even if JSON keys are reverted

## Open Questions

1. Should `bulk.*`, `dashboard.*`, `export.*`, `settings.*` keys live in `features/tickets.json`
   or be extracted to a new `msp/ticketing.json` namespace? **Tentative answer:** keep in
   `features/tickets.json` since client portal may eventually surface similar controls
   (bulk operations on client-side ticket list). Revisit after sub-batch A if the file
   grows past ~250 keys.
2. For toast messages using template literals (e.g., `` `${N} tickets moved` ``), use
   i18next interpolation `t('bulk.moved', { count: N })` or keep template string with `t()`
   for the static part? **Tentative answer:** interpolation — matches existing patterns in
   `features/tickets.json` `messages.*`.
3. For `throw new Error('User must be logged in')` — translate or leave English?
   **Tentative answer:** translate only if the error surfaces to user via toast/UI;
   leave English if caught and rethrown by error boundaries or logged only.

## Acceptance Criteria (Definition of Done)

- [ ] All 23 unwired production MSP ticket components either (a) import `useTranslation`
      and wrap all user-visible strings, or (b) are confirmed to have zero user-visible
      strings (skeletons, styles, re-exports)
- [ ] `features/tickets.json` contains all keys referenced by MSP ticket components
- [ ] `node scripts/generate-pseudo-locales.cjs && node scripts/validate-translations.cjs`
      exits 0 (covers key parity across 9 locales, pseudo-locale fill patterns, Italian
      accent preservation, and `{{variable}}` interpolation preservation)
- [ ] All existing ticket-related unit/integration tests pass
- [ ] Visual smoke test: `/msp/tickets`, `/msp/tickets/[id]`, `/msp/settings/ticketing`,
      `/msp/service-requests/[id]` render correctly in `en` and at least one non-English
      locale (de or fr recommended); `xx` pseudo-locale shows pseudo-text for every visible
      string (no bare English leakage)
- [ ] Parent plan `.ai/translation/MSP_i18n_plan.md` updated: sub-batch 2b-21a marked ✅