PSA/ee/docs/plans/2026-03-20-msp-i18n-clients-assets-onboarding/PRD.md

PRD — MSP i18n Batches 2b-10/11/12/16: Clients, Contacts, Assets, Onboarding

• Slug: 2026-03-20-msp-i18n-clients-assets-onboarding
• Date: 2026-03-20
• Status: Draft

Summary

Translate four high-priority MSP feature areas that were missing from the original translation plan:

Batch	Namespace	Est. Strings	Files	Package
2b-10	msp/clients	~1,000-2,100	31	packages/clients/src/components/clients/ (+panels/)
2b-11	msp/contacts	~550-1,150	12	packages/clients/src/components/contacts/
2b-12	msp/assets	~1,200-2,400	41	packages/assets/src/components/
2b-16	msp/onboarding	~600-1,200	8	packages/onboarding/src/components/steps/ + OnboardingWizard.tsx
Total		~3,350-6,850	92

Note on estimates: String counts are from automated scan using ~0.2 strings/LOC ratio. Previous batches showed this overestimates by ~1.5-2x. The lower bound is the more realistic target. Exact counts will be determined during implementation by reading each file.

Onboarding scope: Only the wizard steps (TicketingConfigStep, BillingSetupStep, TeamMembersStep, ClientInfoStep, AddClientStep, ClientContactStep) and OnboardingWizard.tsx. The dashboard onboarding section (DashboardOnboardingSection, OnboardingChecklist) was already translated in batch 2b-2.

Problem

Clients, contacts, and assets are the three most-used MSP features — operators interact with them daily. The onboarding wizard is the first experience for new tenants. All four areas display entirely English UI regardless of user locale preference.

Goals

1. Create 4 new namespaces: msp/clients.json, msp/contacts.json, msp/assets.json, msp/onboarding.json
2. Wire all ~92 component files with useTranslation()
3. Generate translations for 7 languages + 2 pseudo-locales (36 new locale files)
4. Register namespaces in ROUTE_NAMESPACES
5. Zero regressions with msp-i18n-enabled flag OFF

Non-goals

• Translating client-portal views of clients/contacts/assets (those are in features/*.json)
• Translating the already-done dashboard onboarding section
• Translating server-side actions or API responses
• Refactoring component architecture

Users and Primary Flows

Primary user: MSP operators managing their client base and assets.

Flows:

• Clients: list clients, create/edit, manage locations, billing configuration, tax settings, contract assignment
• Contacts: list contacts, create/edit, phone numbers, portal access, import
• Assets: asset dashboard, create/edit, detail view, maintenance schedules, RMM integration, software inventory
• Onboarding: multi-step wizard for new tenant setup (client info → contacts → team members → ticketing → billing)

UX / UI Notes

• Client and contact forms have many fields — German translations may overflow in side-by-side label/input layouts
• Asset dashboard has metric cards and status badges — verify badge text doesn't truncate
• Onboarding wizard TicketingConfigStep (3,040 LOC) is the single largest file — ~600 estimated strings, likely 300-400 after reading carefully. Now includes board-scoped status configuration.
• Import dialogs (ClientsImportDialog, ContactsImportDialog) have CSV column mapping labels — these should be translated

Requirements

Batch 2b-10: msp/clients (~1,000-2,100 strings, 31 files)

Largest components:

Component	LOC	Est. Strings	Key content
ClientDetails.tsx	1,805	~150-320	Detail view, all sections, action menus
Clients.tsx	1,503	~140-280	Client listing, filters, grid/list views
QuickAddClient.tsx	1,140	~100-210	Quick-add form, all fields
ClientLocations.tsx	1,038	~100-195	Location management, address fields
BillingConfiguration.tsx	701	~70-135	Billing setup, payment terms (updated: assignment-explicit semantics)
ClientsImportDialog.tsx	697	~75-150	CSV import, column mapping
ClientBillingSchedule.tsx	504	~50-100	Billing schedule (updated: grew from ~387 LOC, billing mode decoupling)
ClientContractAssignment.tsx	423	~45-85	Contract assignment UI (updated: refactored for explicit assignments)
ClientContractLineDashboard.tsx	426	~40-80	Contract line overview
ContractLines.tsx	203	~20-40	Contract lines display (updated: +55 LOC)
Remaining 21 files	~4,200	~250-505	Tax settings, service overlap, credit settings, grid cards, notes panel, etc.

Batch 2b-11: msp/contacts (~550-1,150 strings, 12 files)

Component	LOC	Est. Strings	Key content
ContactDetails.tsx	985	~120-245	Contact detail view, tabs
Contacts.tsx	917	~110-220	Contact listing, filters
ContactsImportDialog.tsx	824	~90-185	CSV import, column mapping
ContactPhoneNumbersEditor.tsx	755	~75-155	Phone number CRUD
ContactPortalTab.tsx	652	~80-160	Portal access configuration
QuickAddContact.tsx	621	~75-155	Quick-add form
Remaining 6 files	~1,400	~90-210	ContactDetailsEdit, ContactDetailsView, ClientContactsList, ContactsLayout, ContactAvatarUpload, ContactsSkeleton

Batch 2b-12: msp/assets (~1,200-2,400 strings, 41 files)

Component	LOC	Est. Strings	Key content
AssetForm.tsx	1,247	~170-340	Full asset form, all fields
AssetDashboardClient.tsx	1,170	~140-280	Asset dashboard, grid view
AssetDetailDrawerClient.tsx	685	~90-175	Drawer detail view
AssetDetails.tsx	653	~160-320	Full detail page
AssociatedAssets.tsx	647	~70-140	Related assets management
QuickAddAsset.tsx	587	~80-165	Quick-add form
CreateTicketFromAssetButton.tsx	285	~30-60	Create ticket from asset (updated: board-scoped statuses)
Remaining 34 files	~4,378	~360-720	Tabs (maintenance, software, service history, audit log, documents), panels (info, RMM, hardware, security, notes), status badges, metric banners, command palette

Batch 2b-16: msp/onboarding (~600-1,200 strings, 8 files)

Excludes already-translated dashboard components (DashboardOnboardingSection, OnboardingChecklist).

Component	LOC	Est. Strings	Key content
steps/TicketingConfigStep.tsx	3,040	~300-600	Ticketing setup: boards, statuses, priorities, categories, SLA (updated: +120 LOC for board-scoped status configuration)
steps/BillingSetupStep.tsx	610	~80-165	Billing configuration step (updated: +28 LOC, billing mode decoupled from service type)
OnboardingWizard.tsx	508	~45-85	Wizard shell, step navigation
steps/TeamMembersStep.tsx	429	~55-110	Team member invitation
steps/ClientInfoStep.tsx	286	~45-85	Client information form
steps/AddClientStep.tsx	213	~30-60	Add client step
steps/ClientContactStep.tsx	123	~20-40	Contact creation step
OnboardingProvider.tsx	75	~8-15	Provider context strings

ROUTE_NAMESPACES updates

'/msp/clients': ['common', 'msp/core', 'msp/clients'],
'/msp/contacts': ['common', 'msp/core', 'msp/contacts'],
'/msp/assets': ['common', 'msp/core', 'msp/assets'],
'/msp/onboarding': ['common', 'msp/core', 'msp/onboarding'],

Non-functional Requirements

• Follow naming convention from translation-guide.md
• All t() calls use { defaultValue: '...' } for English fallback
• Feature flag msp-i18n-enabled OFF = forced English
• Import dialog column labels should be translated (CSV headers stay in English, but the mapping UI labels are translated)

Rollout / Migration

• Behind msp-i18n-enabled feature flag
• No database changes
• Sub-batches can be merged independently

Open Questions

1. Client vs shared namespace: Some client/contact components may be rendered in the client portal too. Need to check if any strings should go in features/contacts.json (shared) rather than msp/contacts.json.
2. Asset EE components: Are there EE-only asset components that need separate handling?
3. TicketingConfigStep size: At 2,920 LOC, this is larger than most entire batches. May need to be its own sub-feature within the onboarding namespace.

Acceptance Criteria

Per batch

• English namespace JSON created with all keys
• All component files wired with useTranslation('<namespace>')
• All 7 production locale files created
• Pseudo-locale files created (xx, yy)
• Italian accent audit passes
• validate-translations.cjs passes

Cross-cutting

• ROUTE_NAMESPACES updated for all 4 routes
• msp-i18n-enabled OFF: English text, no regressions
• msp-i18n-enabled ON + locale xx: clients, contacts, assets, onboarding all show 11111
• German translations don't overflow in client/contact forms, asset dashboard metrics, onboarding wizard
• Billing terminology consistent with msp/contracts and msp/invoicing namespaces (post contract-simplification refactor)
• npm run build succeeds