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

# PRD — MSP i18n: Billing & Tax Settings

- Slug: `2026-04-09-msp-i18n-billing-settings`
- Date: `2026-04-09`
- Status: Draft
- Parent plan: `/.ai/translation/MSP_i18n_plan.md`

## Summary

Create a new `msp/billing-settings` i18n namespace and wire `useTranslation` into 17
billing and tax settings components that currently have zero i18n coverage. These
components live under `packages/billing/src/components/settings/billing/`,
`packages/billing/src/components/settings/tax/`, and
`packages/billing/src/components/tax/`. None of them currently import `useTranslation`.

## Problem

MSP users navigating to `/msp/settings?tab=billing` see the surrounding settings chrome
translated (sidebar, tabs) but the billing/tax settings content is hardcoded English.
This includes card titles, field labels, toast messages, validation errors, dialog
titles, confirmation messages, and import wizard copy across 17 components totalling
approximately 6,000 lines of code. Non-English MSP users experience a jarring switch
from translated navigation into an English-only settings surface.

This is a new-namespace project: unlike the tickets migration (which reused an existing
JSON), here we must create `msp/billing-settings.json` from scratch, add it to
`ROUTE_NAMESPACES`, populate translations for 7 languages, and generate pseudo-locales.

## Goals

1. Create `en/msp/billing-settings.json` with all keys needed by the 17 components
2. Wire `useTranslation('msp/billing-settings')` into all 17 components
3. Add `msp/billing-settings` to `ROUTE_NAMESPACES['/msp/settings']`
4. Generate translations for 6 non-English locales (fr, es, de, nl, it, pl)
5. Regenerate pseudo-locales (xx, yy) from updated English source
6. Pass `node scripts/generate-pseudo-locales.cjs && node scripts/validate-translations.cjs`
7. Measurable: 0/17 components wired -> 17/17 components wired

## Non-goals

- Translating dynamic data values (currency names, category names, board names) -- those
  are tenant data, not UI chrome
- Translating `handleError()` internal error strings that only appear in console logs
- Moving billing settings components to a different package structure
- Translating the `NumberingSettings` component from `@alga-psa/reference-data` -- that
  belongs to a separate namespace and sub-batch
- Translating the dynamically-imported `PaymentSettingsConfig` (EE-only) -- it has its
  own component boundary and should be handled in an EE i18n pass
- Creating new UI components or changing component architecture

## Users and Primary Flows

**Primary user:** MSP administrators configuring billing and tax settings in non-English
UI languages (any of fr, es, de, nl, it, pl).

**Primary flows affected:**
1. `/msp/settings?tab=billing` -- General tab (currency, invoice numbering, zero-dollar,
   credit expiration, renewal automation)
2. `/msp/settings?tab=billing&section=quoting` -- Quote numbering (when feature-flagged)
3. `/msp/settings?tab=billing&section=tax` -- Tax source selection, tax regions manager
4. `/msp/settings?tab=billing&section=payments` -- Payment settings card
5. Service Catalog and Products management embedded in settings
6. Client-level tax settings form (`TaxSettingsForm`)

## UX / UI Notes

- No visual changes. Text replaced inline via `t('key', { defaultValue: 'English fallback' })`.
- Tab `id` attributes remain ASCII kebab-case (`general`, `quoting`, `tax`, `payments`);
  only `label` values are translated via `t()`.
- Toast messages (`toast.success` / `toast.error`) also translated.
- Confirmation dialog `message` strings with interpolated names use i18next interpolation:
  `t('confirmDelete', { name: categoryName, defaultValue: '...' })`.
- `handleError(error, 'message')` second-arg strings are user-visible and should be translated.
- `throw new Error('...')` and `setError('...')` strings that surface to the user via
  inline error display are translated; those that only appear in `console.error` stay English.
- Form validation strings set via `setValidationErrors([])` or `setError()` are translated.
- Zod schema `.message()` strings in `TaxRegionsManager`, `TaxThresholdEditor`,
  `TaxComponentEditor`, and `TaxHolidayManager` are NOT translated (they are developer-
  facing validation constraints); only the rendered error paragraph text is translated.
- Loading state strings (`"Loading settings..."`, `"Loading boards..."`, etc.) are translated.
- Select option labels (`{ value: 'normal', label: 'Create as Draft' }`) are translated.

## Requirements

### File Inventory

| # | Component | LOC | Est. Strings | Key Content |
|---|-----------|-----|-------------|-------------|
| 1 | BillingSettings.tsx | 264 | ~25 | Tab labels (General/Quoting/Tax/Payments), card titles (Default Currency, Invoice Numbering, Zero-Dollar Invoices, Credit Expiration, Renewal Automation, Quote Numbering, Tax Regions, Payment Settings), card descriptions, loading text |
| 2 | DefaultCurrencySettings.tsx | 62 | ~5 | Currency label, placeholder, toast success, error messages |
| 3 | ZeroDollarInvoiceSettings.tsx | 108 | ~10 | Handling option labels (Create as Draft / Create and Finalize), Suppress toggle label, help text, toast, error |
| 4 | CreditExpirationSettings.tsx | 153 | ~12 | Enable toggle label, expiration period label, notification days label, placeholder, help texts, save button, toast, error |
| 5 | RenewalAutomationSettings.tsx | 259 | ~18 | Policy option labels, board/status select labels, placeholders (Loading boards.../Select board/etc.), help text, save/saving button, toast, error |
| 6 | ServiceCategoriesSettings.tsx | 555 | ~35 | Page heading, table column titles (Name/Description/Order/Actions), action menu items (Edit/Delete), Add/Import buttons, add/edit dialog (title, field labels, placeholders, help text, validation), import dialog (title, empty state, select-all, column headers, conflict resolution radio labels), confirmation dialog, toast messages |
| 7 | ServiceTypeSettings.tsx | 730 | ~45 | Card title/description, table columns (Name/Billing Method/Description/Order/Actions), loading state, billing method labels (Fixed/Hourly/Usage), Add button, add/edit dialog (title, field labels, validation prompt, placeholders, help text), delete confirmation, import dialog (title, empty state, column headers, conflict resolution), toast messages |
| 8 | ServiceCatalogManager.tsx | 996 | ~50 | Page heading, table columns (Service Name/Service Type/Billing Method/Pricing/Unit/Tax Rate/Actions), filter placeholders, loading state, edit dialog (title, field labels, pricing section header, billing method rates, unit of measure label/help, tax rate label, SKU/Inventory/Seat Limit/License Term labels), save/cancel buttons, delete entity dialog labels, toast messages |
| 9 | ProductsManager.tsx | 544 | ~35 | Page heading, table columns (Product/SKU/Type/Category/Label/Pricing/Tax Rate/Active/Actions), action menu (Edit/Restore/Archive/Delete), filter options (All Statuses/Active/Inactive, All Categories, All Types), search placeholder, loading state, add button, archive confirmation, permanent delete dialog (checking/confirm/cannot-delete messages), toast messages |
| 10 | QuickAddService.tsx | 661 | ~40 | Dialog title, field labels (Service Name/Service Type/Billing Method/Description/Pricing/Unit of Measure/Tax Rate/SKU/Inventory Count/Seat Limit/License Term), pricing section (rate type labels, + Add Currency, Remove), validation errors, cancel/save buttons, toast |
| 11 | QuickAddProduct.tsx | 603 | ~40 | Dialog title (Add/Edit Product), field labels (Product Name/Type/SKU/Category/Label/Vendor/Manufacturer/Cost/Billing Method/Pricing/Tax Rate/Active/Unit of Measure/License?/License Term/Description), pricing section, validation errors, cancel/create/save buttons |
| 12 | TaxSourceSettings.tsx | 182 | ~20 | Card title, tooltip, description, radio labels (Internal/External) with descriptions, external workflow steps (numbered list), cancel/save buttons, saving state, toast |
| 13 | TaxRegionsManager.tsx | 356 | ~20 | Card title, Add button, table columns (Code/Name/Status/Actions), status badges (Active/Inactive), action menu (Edit/Activate/Deactivate), dialog title (Add/Edit), field labels (Region Code/Region Name/Active), cancel/save buttons, saving state, toast messages, loading state |
| 14 | TaxThresholdEditor.tsx | 567 | ~35 | Section heading, tooltip, Add Bracket button, table columns (Min Amount/Max Amount/Rate/Actions), action menu (Edit/Delete), bracket issues alert, loading/empty states, calculation preview labels, add/edit dialog (title, field labels, placeholders), delete dialog (confirmation message, last-bracket warning), cancel/save/delete buttons, toast messages |
| 15 | TaxComponentEditor.tsx | 541 | ~30 | Section heading, tooltip, Add Component button, table columns (Seq/Name/Rate/Compound/Date Range/Actions), badges (Yes/No), date range labels (Always/Any/Ongoing), loading/empty states, calculation preview, add/edit dialog (field labels, compound tax toggle description), delete dialog, toast messages |
| 16 | TaxHolidayManager.tsx | 470 | ~25 | Section heading, tooltip, Add Holiday button, table columns (Start Date/End Date/Description/Status/Actions), status badges (Active/Upcoming/Expired), status summary, loading/empty states, add/edit dialog (field labels, placeholder), delete dialog, toast messages |
| 17 | TaxSettingsForm.tsx | 521 | ~35 | Page title (Client Tax Settings), tax exempt card (title/description, toggle labels, certificate field, exempt alert), advanced tax options card (title/description, reverse charge toggle/tooltip, tax source override label/tooltip/options/description, override-not-available alert with link), reset/update buttons, loading state, error/success messages, no-settings-found state |

**Total: ~480 estimated translatable strings**

### Namespace Structure (`msp/billing-settings.json`)

Top-level key groups:

```
tabs.*                    — Tab labels (general, quoting, tax, payments)
general.*                 — General tab card titles and descriptions
  general.currency.*      — Default currency card
  general.invoiceNumbering.* — Invoice numbering card
  general.zeroDollar.*    — Zero-dollar invoice settings
  general.creditExpiration.* — Credit expiration settings
  general.renewal.*       — Renewal automation settings
quoting.*                 — Quoting tab
tax.*                     — Tax tab
  tax.source.*            — Tax calculation source settings
  tax.regions.*           — Tax regions manager
  tax.thresholds.*        — Tax threshold/bracket editor
  tax.components.*        — Tax component editor
  tax.holidays.*          — Tax holiday manager
payments.*                — Payments tab
serviceCategories.*       — Service categories settings
serviceTypes.*            — Service type settings
serviceCatalog.*          — Service catalog manager
products.*                — Products manager
quickAddService.*         — Quick add service dialog
quickAddProduct.*         — Quick add product dialog
clientTaxSettings.*       — Client-level tax settings form
common.*                  — Shared strings (Edit, Delete, Cancel, Save, etc.)
import.*                  — Shared import dialog strings
validation.*              — Shared validation messages
errors.*                  — Shared error messages
toast.*                   — Shared toast messages
```

### Naming Conventions

- camelCase keys, nested under semantic groups
- Follow existing patterns from `features/tickets.json` and `msp/settings.json`
- Reuse keys from `common.json` where they already exist (e.g., `common:actions.save`)
  -- but do NOT add cross-namespace `t()` calls; duplicate into `msp/billing-settings`
  for namespace isolation
- Interpolation uses `{{variable}}` syntax: `t('confirmDelete', { name: categoryName })`

## 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

- **ROUTE_NAMESPACES update:** Add `'msp/billing-settings'` to the `/msp/settings` entry
  in `packages/core/src/lib/i18n/config.ts`
- **Per-component rollout:** Can ship in 3-4 PRs grouped by sub-batch 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 `TaxSettingsForm.tsx` (client-level tax settings) use `msp/billing-settings`
   or get its own `msp/client-tax.json`? **Tentative answer:** keep in
   `msp/billing-settings` since it is accessed through the billing settings surface and
   shares significant vocabulary (tax source, reverse charge, exempt status). Revisit if
   the namespace grows past ~500 keys.
2. For `handleError(error, 'Failed to load settings')` -- translate the fallback string?
   **Answer:** Yes, use `t('errors.failedToLoadSettings', { defaultValue: '...' })` since
   `handleError` displays the string to the user via toast.
3. For select option arrays defined as constants (e.g., `POLICY_OPTIONS`, `LICENSE_TERM_OPTIONS`,
   `BILLING_METHOD_OPTIONS`) -- translate at render time or at definition time?
   **Answer:** Translate at render time inside the component using `useMemo` with `t()`,
   so the options react to locale changes. Move the `const` inside the component or wrap
   with a `useMemo` that depends on `t`.

## Acceptance Criteria (Definition of Done)

- [ ] All 17 components import `useTranslation('msp/billing-settings')` and wrap all
      user-visible strings with `t('key', { defaultValue: 'English fallback' })`
- [ ] `en/msp/billing-settings.json` exists with all referenced keys
- [ ] `ROUTE_NAMESPACES['/msp/settings']` includes `'msp/billing-settings'`
- [ ] Translations exist for all 7 real locales (en, fr, es, de, nl, it, pl)
- [ ] `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)
- [ ] Tab labels use `t()` with `id` remaining ASCII kebab-case
- [ ] Visual smoke test: `/msp/settings?tab=billing` renders 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)
- [ ] No regressions in existing billing/settings tests