PSA/ee/docs/plans/2026-03-19-msp-i18n-batch-2b1-core/PRD.md

PRD — MSP i18n Batches 2b-1 + 2b-2: Core Namespace + Dashboard

• Slug: 2026-03-19-msp-i18n-batch-2b1-core
• Date: 2026-03-19
• Status: Complete

Summary

Extract all hardcoded English strings from two areas:

1. MSP portal shell (msp/core) — navigation sidebar, header bar, quick-create menu, job indicator, trial/payment banners, AI chat sidebar, and confirmation dialogs (~80 new keys, added to existing 72 keys)
2. MSP dashboard (msp/dashboard) — welcome banners, feature cards, onboarding checklist, step definitions, progress indicators (~110 keys, new namespace)

Wire up all components with useTranslation(), generate translations for all 7 languages + 2 pseudo-locales, and validate with visual QA.

Total scope: ~190 new keys across 17 files.

Problem

The MSP portal shell (sidebar, header, breadcrumbs, banners, quick-create) and dashboard display ~190 hardcoded English strings that are not yet translatable. The shell is visible on every MSP page; the dashboard is the first page users see after login. Together they are the highest-impact untranslated surfaces. Users with non-English locale preferences see a mix of translated page content and English chrome.

Goals

1. Extract all user-visible hardcoded strings from MSP shell components into msp/core.json
2. Create msp/dashboard.json namespace with all dashboard strings
3. Wire all components to consume translations via useTranslation()
4. Make menuConfig.ts translation-aware so sidebar nav items and section titles use translated labels
5. Generate accurate translations for all 7 production languages (en, fr, es, de, nl, it, pl)
6. Update pseudo-locale files (xx, yy) to cover new keys
7. Register /msp and /msp/dashboard routes in ROUTE_NAMESPACES to load msp/dashboard
8. Zero regressions — everything works identically with msp-i18n-enabled flag OFF (forced English)

Non-goals

• Translating strings inside child components rendered by QuickCreateDialog (QuickAddTicket, QuickAddClient, etc.) — those belong to their respective feature namespaces
• Translating the Enterprise Edition RightSidebar chat UI — that's in @enterprise/components
• Adding new languages beyond the existing 7
• Changing the namespace structure or route mappings (beyond adding dashboard)
• Translating the GitHub star button (external widget, not our text)
• Refactoring menuConfig.ts to a different data structure

Users and Primary Flows

Primary user: MSP portal operators who have set a non-English locale preference.

Flow: User logs in → sees sidebar, header, breadcrumbs, banners, quick-create menu all in their preferred language instead of hardcoded English.

UX / UI Notes

• No visual changes — all strings appear in the same locations, just translated
• German/Dutch translations are typically 30-50% longer than English — verify no layout overflow in sidebar (collapsed tooltip), header breadcrumbs, banner badges, dropdown menus, and dashboard feature cards
• The sidebar collapsed state shows tooltips — these must also be translated
• Tab labels in settings sidebar sections are already covered by existing settings.sections.* and settings.tabs.* keys — verify they're consumed, not hardcoded
• Dashboard onboarding cards have progress rings with text like "3 of 5 Steps" — verify interpolation works in all languages
• Dashboard feature card descriptions are long sentences — verify no truncation in German/Dutch

Requirements

Functional Requirements

FR1: menuConfig.ts — Translation-aware menu data

The menu config currently exports hardcoded English name and title strings. Two approaches (choose one):

Option A (Recommended): Add translation keys to MenuItem, translate in Sidebar

• Add a translationKey field to MenuItem and NavigationSection
• Keep name as the English fallback / stable identifier
• In Sidebar.tsx, use t(item.translationKey) || item.name for display
• Avoids making menuConfig.ts depend on React hooks

Option B: Translate at config level

• Create a useTranslatedMenuConfig() hook that returns translated copies
• More encapsulated but requires all consumers to be React components

FR2: Sidebar.tsx — Translated labels

String	Key
"Go to dashboard" (aria-label)	sidebar.goToDashboard
"AlgaPSA" (logo text)	Keep hardcoded (brand name)
"AlgaPSA Logo" (alt text)	sidebar.logoAlt
"Back to Main" (button + tooltip, 2 occurrences)	Already exists: sidebar.backToMain
"Expand sidebar"	sidebar.expandSidebar
"Collapse sidebar"	sidebar.collapseSidebar

Sidebar already renders item.name from menuConfig — once FR1 is done, these will be translated.

FR3: Header.tsx — Quick Create menu

String	Key
"Open quick create" (aria-label)	header.quickCreate.ariaLabel
"Quick Create" (button text)	header.quickCreate.title
"Create" (dropdown header)	header.quickCreate.heading
7x option labels (Ticket, Client, Contact, Project, Asset, Service, Product)	header.quickCreate.options.<type>.label
7x option descriptions	header.quickCreate.options.<type>.description

FR4: Header.tsx — Job Activity Indicator

String	Key
"View background job activity" (aria-label)	header.jobs.ariaLabel
"Background Jobs"	header.jobs.title
"Track imports, automation runs, and scheduled work."	header.jobs.description
"Active jobs"	header.jobs.active
"Queued jobs"	header.jobs.queued
"Failed last 24h"	header.jobs.failedLast24h
"Open Job Center"	header.jobs.openJobCenter

FR5: Header.tsx — Breadcrumb and User Menu

String	Key
"Home" (breadcrumb root)	header.breadcrumb.home
"Dashboard" (breadcrumb fallback)	header.breadcrumb.dashboard
Active tenant ${tenant} (aria-label)	header.tenantBadge.ariaLabel
"Open user menu" (aria-label)	Already covered by existing header keys
"User" (fallback name)	Already exists: header.userFallback
"Quick access to profile & account."	Already exists: header.quickAccess
"Profile"	Already exists: header.profile
"Account"	Already exists: header.account
"Sign out"	Already exists: header.signOut

FR6: DefaultLayout.tsx — AI Chat Confirmation Dialogs

String	Key
"Leave page and cancel AI response?"	dialogs.aiInterrupt.navigate.title
"An AI response or tool action is still in progress. Leaving this page now will cancel it."	dialogs.aiInterrupt.navigate.message
"Leave page"	dialogs.aiInterrupt.navigate.confirm
"Stay on page"	dialogs.aiInterrupt.navigate.cancel
"Close chat and cancel AI response?"	dialogs.aiInterrupt.closeChat.title
"An AI response or tool action is still in progress. Closing the chat now will cancel it."	dialogs.aiInterrupt.closeChat.message
"Close chat"	dialogs.aiInterrupt.closeChat.confirm
"Keep chat open"	dialogs.aiInterrupt.closeChat.cancel

FR7: TrialBanner.tsx — Trial status messages

String	Key
"Premium confirmed — starts next billing cycle"	banners.trial.premiumConfirmed
"1 day left"	banners.trial.dayLeft
"{{count}} days left"	banners.trial.daysLeft
"Premium Trial: {{daysLabel}} — confirm to keep"	banners.trial.premiumTrial
"{{tier}} Trial: {{daysLabel}}"	banners.trial.stripeTrial

FR8: PaymentFailedBanner.tsx

String	Key
"Payment failed — Update payment method"	banners.paymentFailed.message
"Failed to open billing portal"	banners.paymentFailed.portalError

FR9: QuickCreateDialog.tsx — Success messages and dialog titles

String	Key
"Asset created successfully"	quickCreate.success.asset
Ticket #{{number}} created successfully	quickCreate.success.ticket
Client "{{name}}" created successfully	quickCreate.success.client
{{name}} added successfully	quickCreate.success.contact
Project "{{name}}" created successfully	quickCreate.success.project
"Service created successfully"	quickCreate.success.service
"Product created successfully"	quickCreate.success.product
"Failed to load clients"	quickCreate.errors.loadClients
"Failed to load service types"	quickCreate.errors.loadServiceTypes
"Add New Contact" (dialog title)	quickCreate.dialogTitles.contact
"Add New Project" (dialog title)	quickCreate.dialogTitles.project
"Add New Service" (dialog title)	quickCreate.dialogTitles.service

FR10: RightSidebar.tsx — CE fallback text

String	Key
"Chat"	rightSidebar.title
"The chat feature is only available in the Enterprise Edition."	rightSidebar.enterpriseOnly

FR11: PlatformNotificationBanner.tsx

String	Key
"Learn More"	banners.platformNotification.learnMore
"Dismiss notification" (aria-label)	banners.platformNotification.dismiss

FR12: Billing sidebar navigation

The billing navigation sections in menuConfig.ts have section titles and item names that need translation keys:

String	Key
Section: "Contracts"	nav.billing.sections.contracts
Section: "Invoicing"	nav.billing.sections.invoicing
Section: "Pricing"	nav.billing.sections.pricing
Section: "Tracking & Reports"	nav.billing.sections.trackingReports
Items: "Contract Templates", "Client Contracts", "Contract Line Presets", "Invoicing", "Invoice Templates", "Billing Cycles", "Service Catalog", "Products", "Tax Rates", "Usage Tracking", "Reports", "Accounting Exports"	nav.billing.<camelCase>

FR13: Settings/Extensions sidebar items

String	Key
"Language" (settings nav, only shown when i18n flag is on)	settings.tabs.language
"SLA" (settings nav)	settings.tabs.sla
"Settings" (extensions sidebar label)	Already exists: sidebar.settings

FR14: DashboardContainer.tsx — Welcome banners and feature cards

Welcome banners (namespace: msp/dashboard):

String	Key
"Welcome to Your MSP Command Center"	welcome.title
"Track onboarding progress, configure critical services..."	welcome.description
"Welcome back"	welcome.titleCommunity
"Jump into tickets, scheduling, projects, and reporting..."	welcome.descriptionCommunity

Feature cards:

String	Key
"Platform Features"	features.heading
"Ticket Management"	features.tickets.title
"Streamline support with routing, SLA tracking..."	features.tickets.description
"System Monitoring"	features.monitoring.title
"Watch critical signals across clients..."	features.monitoring.description
"Security Management"	features.security.title
"Manage policies, approvals, and audit responses..."	features.security.description
"Project Management"	features.projects.title
"Organize delivery plans, tasks, and milestones..."	features.projects.description
"Reporting & Analytics"	features.reports.title
"Build rollups on utilization, SLA attainment..."	features.reports.description
"Schedule Management"	features.schedule.title
"Coordinate onsite visits and remote sessions..."	features.schedule.description
"Coming soon!"	features.comingSoon

Knowledge base section:

String	Key
"Need a deeper dive?"	knowledgeBase.title
"Explore deployment runbooks and best practices..."	knowledgeBase.description
"Visit resources"	knowledgeBase.cta

FR15: DashboardOnboardingSection.tsx — Onboarding progress UI

String	Key
"Onboarding complete"	onboarding.completeTitle
"Complete your setup"	onboarding.incompleteTitle
"Complete" (badge)	onboarding.badges.complete
"You're ready to use the full MSP dashboard experience."	onboarding.completeDescription
"Work through each step to unlock the full MSP dashboard experience."	onboarding.incompleteDescription
"PROGRESS"	onboarding.progress.label
"{{completed}} of {{total}} Steps"	onboarding.progress.steps
"Just getting started!"	onboarding.progress.messageStart
"All set - great job!"	onboarding.progress.messageComplete
"Keep going - you've got this!"	onboarding.progress.messageInProgress
"STEP {{index}}"	onboarding.stepLabel
"NOT STARTED" (badge)	onboarding.badges.notStarted
"IN PROGRESS" (badge)	onboarding.badges.inProgress
"BLOCKED" (badge)	onboarding.badges.blocked
"Complete your first import OR create 5 contacts"	onboarding.substeps.dataImport
"Completed" (CTA when done)	onboarding.cta.completed
"Hiding..."	onboarding.cta.hiding
"Hide"	onboarding.cta.hide
"Dismiss {{title}}" (aria-label)	onboarding.cta.dismiss
"Hidden setup cards ({{count}})"	onboarding.hidden.title
"Restore any card if you need it later."	onboarding.hidden.subtitle
"Restoring..."	onboarding.cta.restoring

FR16: OnboardingChecklist.tsx — Alternative checklist view

String	Key
"Onboarding checklist"	onboarding.checklist.title
"{{completed}} of {{total}} tasks complete"	onboarding.checklist.progress
"Configuration complete"	onboarding.checklist.completeTitle
"Invite clients to experience your branded portal."	onboarding.checklist.completeDescription
"Invite clients"	onboarding.checklist.inviteCta
"View onboarding checklist"	onboarding.checklist.viewButton
"Complete" (status)	Reuse: onboarding.badges.complete
"In Progress" (status)	Reuse: onboarding.badges.inProgress
"Not Started" (status)	Reuse: onboarding.badges.notStarted
"Blocked" (status)	Reuse: onboarding.badges.blocked
"Create your first 5 contacts"	onboarding.substeps.createContacts

FR17: stepDefinitions.ts — Onboarding step content

String	Key
"Secure Identity & SSO"	onboarding.steps.identity.title
"Connect Google Workspace or Microsoft 365 so admins sign in with managed identities."	onboarding.steps.identity.description
"Connect SSO"	onboarding.steps.identity.cta
"Set Up Customer Portal"	onboarding.steps.portal.title
"Configure your portal so customers can sign in on your domain with your branding."	onboarding.steps.portal.description
"Open Portal Settings"	onboarding.steps.portal.cta
"Import Core Data"	onboarding.steps.dataImport.title
"Add contacts so you can start working for clients and keep workflows moving."	onboarding.steps.dataImport.description
"Create Contacts"	onboarding.steps.dataImport.cta
"Calendar Sync"	onboarding.steps.calendar.title
"Connect Google or Outlook calendars to keep dispatch and client appointments aligned."	onboarding.steps.calendar.description
"Configure Calendar"	onboarding.steps.calendar.cta
"Configure Email"	onboarding.steps.email.title
"Set up inbound ticket email and verify an outbound sending domain for reliable delivery."	onboarding.steps.email.description
"Configure Email"	onboarding.steps.email.cta

FR18: ROUTE_NAMESPACES update

Add msp/dashboard to the route namespace configuration so it loads on dashboard routes:

'/msp': ['common', 'msp/core', 'msp/dashboard'],
'/msp/dashboard': ['common', 'msp/core', 'msp/dashboard'],

Non-functional Requirements

• All new keys follow the established naming convention (see translation-guide.md)
• No performance regression — msp/core already loads on every MSP route; msp/dashboard loads only on dashboard route
• Feature flag msp-i18n-enabled OFF = forced English (no change in behavior)

Data / API / Integrations

• No database changes
• No API changes
• Translation files: server/public/locales/{lang}/msp/core.json and server/public/locales/{lang}/msp/dashboard.json for all 9 locales

Security / Permissions

No changes — translations are static JSON files served from /public/locales/.

Rollout / Migration

• Behind existing msp-i18n-enabled feature flag
• Flag OFF: I18nWrapper forces English locale → t() returns English values → identical to current hardcoded strings
• Flag ON: User sees their preferred language
• No migration needed — purely additive change to translation files + component wiring

Open Questions

1. menuConfig.ts approach: Option A (translationKey field) vs Option B (hook)? Recommendation: Option A for simplicity — menuConfig stays a plain data file.
2. Breadcrumb translation: getMenuItemNameByPath() currently returns item.name (English). Should it return the translation key instead, letting the breadcrumb component translate? Or should breadcrumbs show the translated nav label?
3. GitHubStarButton: The "Star" text and aria-label are part of the GitHub buttons widget — not our text. Skip translation? (Recommendation: yes, skip.)
4. Onboarding components location: Dashboard onboarding components live in packages/onboarding/, not server/src/. They'll need to import useTranslation from @alga-psa/ui/lib/i18n/client — verify this works from the package context.
5. stepDefinitions.ts: This file exports plain data (not a React component). Should it export translation keys (like menuConfig Option A) and let the rendering component call t()? (Recommendation: yes, same pattern as menuConfig.)

Acceptance Criteria (Definition of Done)

msp/core (shell)

• All ~80 new keys added to en/msp/core.json
• All 9 shell component files + menuConfig.ts wired to use useTranslation('msp/core')
• With msp-i18n-enabled ON + locale set to xx: sidebar, header, breadcrumbs, banners, quick-create all show 11111

msp/dashboard

• New msp/dashboard.json namespace created with ~110 keys
• All 4 dashboard component files + stepDefinitions.ts wired to use useTranslation('msp/dashboard')
• ROUTE_NAMESPACES updated for /msp and /msp/dashboard to include msp/dashboard
• With msp-i18n-enabled ON + locale set to xx: welcome banner, feature cards, onboarding checklist all show 11111

Cross-cutting

• All 7 production locale files updated with translations for both namespaces (fr, es, de, nl, it, pl)
• Both pseudo-locale files updated for both namespaces (xx, yy)
• With msp-i18n-enabled OFF: all text displays in English (no regressions)
• With msp-i18n-enabled ON + locale set to pl: shell and dashboard show Polish text
• German translations don't overflow sidebar tooltips, header dropdowns, banner badges, or dashboard cards
• Italian translations pass accent audit (no missing à, è, ù, ò)
• Cross-check: nav item names in msp/core.json match across all languages
• No TypeScript errors, build passes