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

PRD — MSP i18n Batch 2b-21b/c: Projects + Project Templates Migration

• Slug: 2026-04-05-msp-i18n-projects-migration
• Date: 2026-04-05
• Status: Draft
• Parent plan: .ai/translation/MSP_i18n_plan.md (Batches 2b-21b + 2b-21c)
• Sibling plan: ee/docs/plans/2026-04-05-msp-i18n-tickets-migration/ (2b-21a)

Summary

Wire the existing features/projects namespace into ~60 unwired MSP components in packages/projects/src/components/ (projects proper + project-templates subdirectory). Infrastructure is already in place: features/projects.json (128 keys across 9 locales) exists, templates.* subtree is live, and ROUTE_NAMESPACES['/msp/projects'] already loads it. 5 of 65 production components are wired; ~60 remain. Consolidates what the parent plan called 2b-21b (projects) and 2b-21c (project-templates) into one effort because they share the same package, namespace, and patterns.

Problem

MSP users see hardcoded English across the entire project management module — the main projects list, project detail page, task forms, kanban board, project templates, wizard steps, and task dialogs. Only 5 of 65 production components (8%) are wired. Because ROUTE_NAMESPACES['/msp/projects'] already loads features/projects, the translation assets are downloaded but unused. Client-portal project views are 100% wired (9/9), so this is the last major gap in project-related UI.

Project templates were originally considered for a separate features/project-templates namespace, but analysis confirmed that the existing features/projects.json templates.* subtree (17 keys) is already used by wired components (TemplateStatusColumnsStep, TemplateStatusManager) and should be extended rather than split.

Goals

1. Wire useTranslation(['features/projects', 'common']) into all unwired production MSP project components (projects proper + project-templates)
2. Extend features/projects.json with MSP-specific keys missing from the current namespace (task form, task dependencies, project detail tabs, kanban, materials, export, template editor, template wizards, dialogs)
3. Regenerate pseudo-locales via script; validate all 9 locales pass the validator
4. Preserve 100% test pass rate and zero user-facing regressions
5. Measurable: MSP projects coverage 8% → 100%, project-templates coverage 12% → 100%

Non-goals

• Creating a new features/project-templates.json namespace — templates.* lives in features/projects.json per existing pattern
• Retranslating existing 128 keys — 7-language coverage already exists
• Translating project/task content (names, descriptions, comments) — those are tenant data
• Wiring test files (.test.tsx) or test helpers
• Translating client-portal project views — already complete (9/9)
• Extending shared features/projects for client-portal-specific needs not surfaced on MSP
• Translating EE-only project components beyond what packages/projects exports

Users and Primary Flows

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

Primary flows affected:

1. /msp/projects — list page, filters, quick-add
2. /msp/projects/[id] — project detail, phases, tasks, kanban, materials, task forms
3. /msp/projects/templates — template list, categories filter
4. /msp/projects/templates/[templateId] — template editor, task builder, phase manager
5. /msp/projects/templates/create — template creation wizard (4-5 steps)
6. /msp/settings/project-settings — ProjectSettings, ProjectStatusSettings, TenantProjectTaskStatusSettings, TaskPrioritySettings, AddStatusDialog
7. Quick-create dialog (global nav) — ProjectQuickAdd reused in layout/QuickCreateDialog

UX / UI Notes

• No visual changes. Text replaced inline via t('key', 'English fallback').
• Use multi-namespace form: useTranslation(['features/projects', 'common']) — matches existing wired components (TemplateStatusColumnsStep, TemplateStatusManager, ProjectTaskStatusSettings).
• Common strings (Cancel, Save, Delete, Confirm) come from common namespace; scoped domain strings from features/projects.
• Toast messages, inline validation, confirmations all translated.
• Task form is the largest single surface (~39 strings, 2024 LOC) — split mental model by tab (details, dependencies, documents, ticket links, comments, materials).

Requirements

Functional Requirements

Sub-batch A: Projects — core detail, task form, list (15 files, ~250 strings)

High-traffic daily-use components. Ship first.

Component	LOC	Est. strings	Key content
ProjectDetail.tsx	3,038	~50	Project detail page tabs, phases, tasks, budget/hours, kanban controls
TaskForm.tsx	2,024	~39	Task create/edit form, fields, validation, toast messages
PhaseTaskImportDialog.tsx	1,290	~21	Task import dialog, CSV preview, validation errors
Projects.tsx	980	~21	Project list, filters (status/search/deadline), empty state
TaskDocumentsSimple.tsx	856	~21	Task documents panel, upload, attach, download
TaskTicketLinks.tsx	816	~21	Task-ticket linking UI, create/unlink, search
TaskDependencies.tsx	668	~21	Dependency graph, add/remove, blocking indicators
ProjectMaterialsDrawer.tsx	439	~19	Materials list, add/edit/remove, cost labels
ProjectTaskExportDialog.tsx	283	~18	Export format, column picker, toast messages
ProjectQuickAdd.tsx	454	~15	Quick-add project dialog (reused in QuickCreate)
ProjectDetailsEdit.tsx	557	~13	Project detail edit form
PrefillFromTicketDialog.tsx	419	~10	Prefill task from ticket, field mapping
TaskListView.tsx	1,320	~9	Task list table, columns, inline edit
TaskCard.tsx	630	~7	Kanban task card, quick-actions menu
PhaseQuickAdd.tsx	141	~7	Quick-add phase inline

Sub-batch B: Project Templates (15 files, ~150 strings)

Template creation, editing, wizard steps, apply flow.

Component	LOC	Est. strings	Key content
TemplateEditor.tsx	2,315	~28	Template editor, phases, tasks, save/publish
TemplateTaskForm.tsx	1,015	~22	Template task create/edit form
wizard-steps/TemplateTasksStep.tsx	576	~20	Wizard step 3 — tasks
ApplyTemplateDialog.tsx	396	~20	Apply template to project dialog
ProjectTemplatesList.tsx	308	~12	Template list page, columns, filters, delete confirm
CreateTemplateDialog.tsx	267	~11	Create template from project dialog
TemplateTaskListView.tsx	953	~8	Template task list view
wizard-steps/TemplateReviewStep.tsx	290	~7	Wizard review step
wizard-steps/TemplatePhasesStep.tsx	399	~6	Wizard phases step
CreateTemplateForm.tsx	140	~6	Template create form body
TemplateDetail.tsx	308	~4	Template detail sidebar
wizard-steps/TemplateClientPortalStep.tsx	45	~2	Client portal exposure toggle
TemplateCreationWizard.tsx	360	~1	Wizard shell
wizard-steps/TemplateBasicsStep.tsx	81	~1	Wizard basics step
AddTemplateDialog.tsx	30	0	Re-export shim

Sub-batch C: Settings + small/utility components (30 files, ~80-100 strings)

Low-string-count cleanup pass.

Component	LOC	Est. strings	Notes
settings/projects/TenantProjectTaskStatusSettings.tsx	642	~11	Tenant-level status defaults
settings/projects/ProjectStatusSettings.tsx	442	~10	Project status config
ProjectTaskStatusEditor.tsx	350	~7	Inline status editor
CreateTaskFromTicketDialog.tsx	274	~5	Create task from ticket
LinkTicketToTaskDialog.tsx	221	~5	Link ticket to task
DeadlineFilter.tsx	165	~5	Deadline filter dropdown
settings/ProjectSettings.tsx	86	~5	Top-level project settings page
ProjectTaskStatusSelector.tsx	371	~4	Status select dropdown
MoveTaskDialog.tsx	126	~4	Move task to phase dialog
ProjectInfo.tsx	254	~3	Project info card
DuplicateTaskDialog.tsx	216	~3	Duplicate task dialog
TicketLinkedTasksBadge.tsx	160	~3	Badge showing linked tasks
settings/projects/AddStatusDialog.tsx	111	~2	Add status dialog
ProjectPhases.tsx	280	~1	Phases section wrapper
TaskStatusSelect.tsx	156	~1	Task status select
TicketSelect.tsx	136	~1	Ticket select
TaskTypeSelector.tsx	54	~1	Task type selector
Remaining zero-string files (~13)	varies	0	Confirm zero strings: StatusColumn, TaskCommentThread, KanbanBoard, ClientPortalConfigEditor, ProjectPage, KanbanZoomControl, TaskCommentForm, DonutChart, TaskQuickAdd, TaskEdit, HoursProgressBar, ProjectActiveToggle, TaskPrioritySettings

Namespace key gaps to fill (preliminary):

Current features/projects.json covers project list and basic detail. Likely MSP gaps:

• taskForm.* — full task create/edit form (fields, validation, placeholders)
• taskDependencies.* — dependency UI, blocking indicators, cycle detection
• taskDocuments.* — attach/upload/download controls (may overlap with features/documents)
• taskTicketLinks.* — link/unlink task-ticket, search
• projectDetail.* — tabs, budget/hours display, phase management
• kanban.* — column headers, drag helpers, zoom control
• materials.* — materials drawer, add/edit, costs
• export.* — export dialog labels (reuse features/tickets export patterns if possible)
• quickAdd.* — project quick-add dialog labels
• dialogs.* — move/duplicate/create-from-ticket dialogs
• import.* — task import CSV flow
• templates.editor.* — template editor-specific strings
• templates.wizard.* — wizard step titles, nav buttons, review summary
• templates.apply.* — apply-template dialog
• templates.list.* — template list page (columns, filters, delete)
• templates.taskForm.* — template task form (may share with taskForm.*)
• settings.statuses.* — already partially present; extend for tenant/project levels
• filters.deadline.* — deadline filter dropdown options

Final gap list determined during implementation — run the lang-pack loop to surface missing keys.

Non-functional Requirements

1. No regressions: all existing project-related tests pass after migration
2. Lang-pack validation: after every en/features/projects.json edit, run node scripts/generate-pseudo-locales.cjs && node scripts/validate-translations.cjs and commit only when green. Single unified check covers key parity, pseudo fill patterns, Italian accent preservation, and {{variable}} preservation. Never hand-edit xx/ or yy/ pseudo-locale files.
3. Naming convention: follow existing features/projects.json patterns (camelCase, nested under semantic groups); reuse existing keys where possible before adding new ones
4. Fallback-safe: all t() calls use t('key', 'English fallback') signature
5. Multi-namespace: use useTranslation(['features/projects', 'common']) array form to match existing wired components; prefer common for generic actions (save/cancel/delete)
6. Shared with client portal: before adding a key, check if existing features/projects key covers it — client-portal uses the same namespace

Data / API / Integrations

• No database changes
• No API changes
• No new npm dependencies
• Reuses existing useTranslation from react-i18next (as used in wired components)
• 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.

Rollout / Migration

• No feature-flag gating needed — I18nWrapper forces English fallback when msp-i18n-enabled is off
• Ship sub-batches A/B/C as independent PRs
• Translations are static JSON served from server/public/locales/; no cache invalidation beyond standard Next.js static-asset rebuild
• Each PR is independently revertable; components continue rendering English via defaultValue fallbacks even if keys are reverted

Open Questions

1. ROUTE_NAMESPACES does not include /msp/projects/templates or /msp/projects/templates/[templateId] or /msp/projects/templates/create. The best-match fallback to /msp/projects should load features/projects transitively. Action: verify via integration test T108; if not loading, add explicit route entries.
2. Should export dialog (ProjectTaskExportDialog) reuse features/tickets export keys or have its own features/projects.export.*? Tentative answer: own section under features/projects — avoids cross-namespace coupling, patterns may diverge.
3. TaskDocumentsSimple — should document strings live in features/documents or features/projects.taskDocuments.*? Tentative answer: reuse features/documents where keys match (already loaded for /msp/projects via transitive namespace? — verify), add features/projects.taskDocuments.* only for project-task-specific copy.
4. Templates wizard has 5 steps with different content — should wizard strings be flat under templates.wizard.* or nested per-step (templates.wizard.basics.*, templates.wizard.tasks.*)? Tentative answer: nested per-step, matches existing onboarding wizard patterns in msp/onboarding.json.

Acceptance Criteria (Definition of Done)

• All ~60 unwired production MSP project + project-template components either (a) import useTranslation(['features/projects', 'common']) and wrap all user-visible strings, or (b) are confirmed zero-string (re-exports, style-only files, kanban layout components)
• features/projects.json contains all keys referenced by MSP project components
• node scripts/generate-pseudo-locales.cjs && node scripts/validate-translations.cjs exits 0
• All existing project-related unit/integration tests pass
• Visual smoke test: /msp/projects, /msp/projects/[id], /msp/projects/templates, /msp/projects/templates/[templateId], /msp/projects/templates/create, /msp/settings/project-settings render correctly in en and at least one non-English locale (de or fr); xx pseudo-locale shows pseudo-text for every visible string (no bare English leakage)
• Global quick-create dialog (ProjectQuickAdd reused in layout/QuickCreateDialog) renders translated in non-English locale
• Parent plan .ai/translation/MSP_i18n_plan.md updated: sub-batches 2b-21b and 2b-21c marked ✅ with final string counts