PSA/ee/docs/plans/2026-04-09-msp-i18n-credits/PRD.md

PRD — MSP i18n: Credits Sub-batch

• Slug: 2026-04-09-msp-i18n-credits
• Date: 2026-04-09
• Status: Implemented on branch i18n/billing_credits (22/22 features, 31/31 tests) — pending merge to main. See SCRATCHPAD "Status Recheck (2026-04-17)".
• Parent plan: /.ai/translation/MSP_i18n_plan.md

Summary

Create a new msp/credits i18n namespace and wire useTranslation('msp/credits') into 10 credit management components across packages/billing/src/components/credits/ and packages/billing/src/components/billing-dashboard/Credit*.tsx. None of these components currently use useTranslation. This is a greenfield namespace (no existing JSON to extend) covering ~150 user-visible strings across credit management, reconciliation, application, and expiration flows.

Problem

MSP users navigating to billing > credits see fully English UI while the surrounding navigation, sidebar, and dashboard chrome are already translated. The credits module spans 10 components with ~150 hardcoded English strings across credit listing, management dashboards, reconciliation reports, credit application, and expiration modification dialogs. No msp/credits.json namespace exists, and no ROUTE_NAMESPACES entry loads credit-specific translations for /msp/billing/credits.

Goals

1. Create server/public/locales/en/msp/credits.json with all keys needed by the 10 components
2. Wire useTranslation('msp/credits') into all 8 client components (2 files are server-side or have zero visible strings)
3. Generate translations for 7 non-English locales (fr, es, de, nl, it, pl) + 2 pseudo-locales (xx, yy)
4. Add /msp/billing/credits route to ROUTE_NAMESPACES in packages/core/src/lib/i18n/config.ts loading msp/credits
5. Pass node scripts/generate-pseudo-locales.cjs && node scripts/validate-translations.cjs
6. Measurable: 0% -> 100% of credit components wired for i18n

Non-goals

• Translating credit amounts, dates, or tenant data (those are formatted via useFormatters or formatCurrency/formatDateOnly utilities already in use)
• Translating server-side error strings in actions.ts that only appear in console logs (e.g., 'Unknown error occurred' in catch blocks) -- these do not surface to the user
• Moving credit components to a different package or restructuring the billing package
• Adding new UI features to credit management
• Translating Recharts axis tick formatters or tooltip formatters (they use formatCurrency which is locale-aware separately)

File Inventory

#	File	LOC	Type	Est. Strings	Notes
1	credits/CreditsPage.tsx	275	Server component	~30	Column titles, statuses, tab labels, card titles, settings labels. Server component -- will need a client wrapper or inline t() via server-side i18n
2	credits/CreditsTabs.tsx	53	Client	0	Pure tab-switching logic; labels passed in via props from CreditsPage. No visible strings to translate. Skip.
3	credits/AddCreditButton.tsx	53	Client	~6	Button label, dialog title, placeholder text, cancel/submit buttons
4	credits/BackButton.tsx	20	Client	~1	"Back to Credits" button text
5	credits/actions.ts	109	Server action	~5	Error messages in catch blocks. Only 'Authentication required' and 'Transfer amount must be greater than zero' surface to callers. Others are console-only.
6	billing-dashboard/CreditManagement.tsx	642	Client	~45	Page title, chart labels/legends, stat card labels, column titles, tab labels, button text, dialog text
7	billing-dashboard/CreditReconciliation.tsx	604	Client	~50	Dashboard title, filter labels, stat cards, chart titles/legends, column titles, tab labels, status badges, button text, toast messages
8	billing-dashboard/CreditApplicationUI.tsx	273	Client	~20	Card title/description, column titles, labels, button text, error/empty states
9	billing-dashboard/CreditExpirationInfo.tsx	129	Client	~10	Card title/description, field labels, help text, empty/error states
10	billing-dashboard/CreditExpirationModificationDialog.tsx	172	Client	~15	Dialog title/description, field labels, switch label, button text, validation errors

Total estimated: ~150 unique strings across ~80 translation keys (some strings repeat across components).

Namespace Structure

File: server/public/locales/en/msp/credits.json

{
  "page": {
    "title": "Credit Management",
    "creditsOverview": "Credits Overview",
    "overviewDescription": "Manage your client credits...",
    ...
  },
  "columns": {
    "creditId": "Credit ID",
    "created": "Created",
    "description": "Description",
    "originalAmount": "Original Amount",
    "remaining": "Remaining",
    "expires": "Expires",
    "status": "Status",
    "actions": "Actions",
    "context": "Context",
    ...
  },
  "status": {
    "active": "Active",
    "expired": "Expired",
    "expiringSoon": "Expiring Soon ({{days}} days)",
    "never": "Never",
    "na": "N/A",
    ...
  },
  "actions": {
    "view": "View",
    "edit": "Edit",
    "expire": "Expire",
    "addCredit": "Add Credit",
    "cancel": "Cancel",
    "viewAllCredits": "View All Credits",
    "backToCredits": "Back to Credits",
    ...
  },
  "tabs": {
    "activeCredits": "Active Credits",
    "allCredits": "All Credits",
    "expiredCredits": "Expired Credits"
  },
  "settings": {
    "title": "Credit Expiration Settings",
    "creditExpiration": "Credit Expiration:",
    "enabled": "Enabled",
    "disabled": "Disabled",
    "expirationPeriod": "Expiration Period:",
    "daysUnit": "{{count}} days",
    "notificationDays": "Notification Days:",
    "none": "None"
  },
  "charts": {
    "expirationSummary": "Credit Expiration Summary",
    "expirationSummaryDescription": "Overview of credits expiring soon",
    "usageTrends": "Credit Usage Trends",
    "usageTrendsDescription": "Historical credit usage patterns",
    "creditsIssued": "Credits Issued",
    "creditsApplied": "Credits Applied",
    "creditsExpired": "Credits Expired",
    ...
  },
  "stats": {
    "totalActiveCredits": "Total Active Credits",
    "expiringIn30Days": "Expiring in 30 Days",
    "totalCreditsApplied": "Total Credits Applied",
    "totalCreditsExpired": "Total Credits Expired",
    ...
  },
  "management": {
    "title": "Credit Management",
    "recentCredits": "Recent Credits",
    "recentCreditsDescription": "View and manage your client credits...",
    "addCreditPlaceholder": "Credit amount and details form would be implemented here."
  },
  "reconciliation": {
    "title": "Credit Reconciliation Dashboard",
    "selectClient": "Select Client",
    "runReconciliation": "Run Reconciliation",
    "running": "Running...",
    "status": "Status",
    "allStatuses": "All Statuses",
    "open": "Open",
    "inReview": "In Review",
    "resolved": "Resolved",
    "fromDate": "From Date",
    "toDate": "To Date",
    "reset": "Reset",
    "totalDiscrepancies": "Total Discrepancies",
    "totalDiscrepancyAmount": "Total Discrepancy Amount",
    "openIssues": "Open Issues",
    "statusDistribution": "Status Distribution",
    "statusDistributionDescription": "Overview of reconciliation report statuses",
    "discrepancyTrends": "Discrepancy Trends",
    "discrepancyTrendsDescription": "Monthly trends in credit discrepancies",
    "numberOfDiscrepancies": "Number of Discrepancies",
    "totalAmount": "Total Amount",
    "reconciliationReports": "Reconciliation Reports",
    "reconciliationReportsDescription": "View and manage credit balance discrepancies",
    "resolve": "Resolve",
    "validationResult": "Validation completed: Found {{balanceCount}} balance discrepancies and {{trackingCount}} tracking issues.",
    ...
  },
  "application": {
    "title": "Apply Credit",
    "applyToInvoice": "Apply available credits to this invoice",
    "applyToBalance": "Apply credits to reduce customer balance",
    "totalAvailableCredit": "Total Available Credit:",
    "invoiceAmount": "Invoice Amount:",
    "selectCreditToApply": "Select Credit to Apply",
    "amountToApply": "Amount to Apply",
    "creditOrderNote": "Credits are applied in order of expiration date (oldest first)",
    "noCreditsAvailable": "No credits available for this client",
    "failedToLoadCredits": "Failed to load available credits",
    "selectCreditError": "Please select a credit and enter a valid amount",
    "failedToApply": "Failed to apply credit",
    "applying": "Applying...",
    "applyCredit": "Apply Credit",
    "selected": "Selected",
    "select": "Select",
    ...
  },
  "expiration": {
    "appliedCredits": "Applied Credits",
    "creditsAppliedToInvoice": "Credits applied to this invoice: {{amount}}",
    "creditAmount": "Credit Amount:",
    "noDetails": "No credit details available",
    "failedToLoad": "Failed to load credit details",
    ...
  },
  "expirationDialog": {
    "title": "Modify Credit Expiration",
    "description": "Update the expiration date for this credit.",
    "creditAmount": "Credit Amount:",
    "remainingAmount": "Remaining Amount:",
    "created": "Created:",
    "currentExpiration": "Current Expiration:",
    "noExpiration": "No expiration",
    "removeExpiration": "Remove expiration date",
    "newExpirationDate": "New Expiration Date",
    "pastDateError": "Expiration date cannot be in the past",
    "updateError": "An error occurred while updating the expiration date",
    "saving": "Saving...",
    "saveChanges": "Save Changes"
  },
  "context": {
    "lineageMissing": "Lineage Missing",
    "lineageMissingDescription": "Source invoice metadata could not be recovered...",
    "transferredRecurringCredit": "Transferred Recurring Credit",
    "recurringSource": "Recurring Source",
    "servicePeriod": "Service Period: {{period}}",
    "recurringLineagePreserved": "Recurring source lineage preserved",
    "financialOnly": "Financial Only",
    "noRecurringServicePeriod": "No recurring service period"
  }
}

ROUTE_NAMESPACES Change

In packages/core/src/lib/i18n/config.ts, add a new entry:

'/msp/billing/credits': ['common', 'msp/core', 'features/billing', 'msp/credits'],

This must appear before the existing /msp/billing entry since getNamespacesForRoute uses longest-prefix matching.

Server Component Consideration

CreditsPage.tsx is an async server component (no 'use client' directive). Two approaches:

1. Extract a client wrapper that calls useTranslation('msp/credits') and passes translated strings as props to the server-rendered content. This is the recommended pattern for server components in Next.js with client-side i18n.
2. Convert to client component by adding 'use client' and restructuring data fetching. This is more invasive and not recommended.

The recommended approach is (1): create a thin CreditsPageClient.tsx wrapper that handles translation, and have the server component pass data to it.

Acceptance Criteria

• server/public/locales/en/msp/credits.json exists with all keys used by credit components
• All 8 client components with visible strings import useTranslation('msp/credits') and wrap all user-visible strings via t('key', { defaultValue: 'English fallback' })
• CreditsPage.tsx (server component) strings are translated via a client wrapper component
• CreditsTabs.tsx confirmed to have zero visible strings (skip)
• actions.ts server-side error strings assessed: user-facing ones translated, log-only ones left in English
• /msp/billing/credits added to ROUTE_NAMESPACES loading msp/credits
• Translations generated for fr, es, de, nl, it, pl (7 locales)
• node scripts/generate-pseudo-locales.cjs && node scripts/validate-translations.cjs exits 0
• Italian translations preserve accents (e.g., "Crediti scaduti" not "Crediti scaduti")
• {{variable}} interpolation tokens preserved across all 9 locale files
• Currency values still formatted via formatCurrency() (not translated as strings)
• Date values still formatted via toLocaleDateString() or formatDateOnly() (not translated)
• Visual smoke test: /msp/billing/credits and credit management tab render correctly in en and at least one non-English locale; xx pseudo-locale shows pseudo-text for every visible string