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

# PRD — MSP i18n: Contract Lines Sub-batch

- Slug: `2026-04-09-msp-i18n-contract-lines`
- Date: `2026-04-09`
- Status: Pending

## Summary

Extract all hardcoded English strings from the 21 contract-line configuration components in `packages/billing/src/components/billing-dashboard/`, create the `msp/contract-lines` namespace, wire `useTranslation()` throughout, and generate translations for 7 languages + pseudo-locales.

**Total scope: ~350-400 new keys across 21 files.**

## Problem

The contract-line management UI -- preset creation dialog, type-specific configurations (Fixed/Hourly/Usage), service lists, tier editors, and routing components -- contains approximately 350-400 hardcoded English strings. These components are accessed by MSP operators via the billing section and are among the most form-heavy screens in the application. Users with non-English locale preferences see untranslated labels, validation messages, tooltips, section headings, helper text, and button labels throughout the contract-line management workflow.

## Goals

1. Create the `msp/contract-lines.json` namespace with all contract-line-related translation keys
2. Extract every user-visible hardcoded string from all 21 component files
3. Wire all components to consume translations via `useTranslation('msp/contract-lines')`
4. Use `useFormatters()` for any currency formatting where applicable
5. Generate accurate translations for all 7 production languages (en, fr, es, de, nl, it, pl)
6. Generate pseudo-locale files (xx, yy) covering all new keys
7. Validate all locale files pass `validate-translations.cjs`
8. Register `/msp/billing` route additions in `ROUTE_NAMESPACES` to load `msp/contract-lines`
9. Zero regressions -- everything works identically with `msp-i18n-enabled` flag OFF (forced English)

## Non-goals

- Translating billing constants (`BILLING_FREQUENCY_OPTIONS`, `PLAN_TYPE_OPTIONS`, `BILLING_FREQUENCY_DISPLAY`, `PLAN_TYPE_DISPLAY`, `CONTRACT_LINE_TYPE_DISPLAY`) -- those are shared constants used across billing; they belong in a `msp/billing` namespace
- Translating `ServiceCatalogPicker` or `BucketOverlayFields` -- those are shared components used by contracts too, covered separately
- Translating `ServiceConfigurationPanel` in `service-configurations/` -- separate sub-batch
- Translating `FixedContractLineServicesList` or `FixedContractLinePresetServicesList` (in parent `billing-dashboard/` directory, not in `contract-lines/`) -- separate scope
- Translating `DeleteEntityDialog` or `ConfirmationDialog` -- shared UI components
- Adding new languages beyond the existing 7
- Changing the component architecture or data flow

## File Inventory

| # | File | LOC | Strings (est.) | Features |
|---|------|-----|----------------|----------|
| 1 | `ContractLineDialog.tsx` | 1292 | ~80 | F001-F003 |
| 2 | `contract-lines/HourlyContractLineConfiguration.tsx` | 849 | ~55 | F004-F005 |
| 3 | `contract-lines/UsageContractLineConfiguration.tsx` | 738 | ~45 | F006-F007 |
| 4 | `contract-lines/UsageContractLinePresetConfiguration.tsx` | 731 | ~45 | F008-F009 |
| 5 | `contract-lines/HourlyContractLinePresetConfiguration.tsx` | 693 | ~45 | F010-F011 |
| 6 | `contract-lines/UsageContractLinePresetServicesList.tsx` | 537 | ~30 | F012-F013 |
| 7 | `contract-lines/HourlyContractLinePresetServicesList.tsx` | 514 | ~30 | F014-F015 |
| 8 | `contract-lines/GenericContractLineServicesList.tsx` | 513 | ~30 | F016-F017 |
| 9 | `ContractLines.tsx` | 485 | ~25 | F018-F019 |
| 10 | `contract-lines/FixedContractLineConfiguration.tsx` | 434 | ~30 | F020-F021 |
| 11 | `contract-lines/FixedContractLinePresetConfiguration.tsx` | 380 | ~25 | F022-F023 |
| 12 | `contract-lines/ServiceHourlyConfigForm.tsx` | 352 | ~25 | F024-F025 |
| 13 | `contract-lines/ContractLineServiceForm.tsx` | 308 | ~10 | F026 |
| 14 | `contract-lines/ContractLinesOverview.tsx` | 281 | ~20 | F027-F028 |
| 15 | `contract-lines/ServiceTierEditor.tsx` | 206 | ~15 | F029 |
| 16 | `contract-lines/ServiceUsageConfigForm.tsx` | 197 | ~15 | F030 |
| 17 | `contract-lines/ServiceBucketConfigForm.tsx` | 164 | ~12 | F031 |
| 18 | `contract-lines/EditContractLineServiceQuantityDialog.tsx` | 154 | ~12 | F032 |
| 19 | `contract-lines/ContractLineTypeSelector.tsx` | 129 | ~10 | F033 |
| 20 | `contract-lines/ContractLineTypeRouter.tsx` | 79 | ~4 | F034 |
| 21 | `contract-lines/ContractLinePresetTypeRouter.tsx` | 79 | ~4 | F035 |

## Namespace Structure

Namespace: `msp/contract-lines`

```
{
  "dialog": {                          // ContractLineDialog.tsx
    "title": { "add": "...", "edit": "..." },
    "basics": { ... },
    "billingModel": { ... },
    "fixed": { ... },
    "hourly": { ... },
    "usage": { ... },
    "validation": { ... },
    "actions": { ... }
  },
  "overview": { ... },                 // ContractLinesOverview.tsx
  "list": { ... },                     // ContractLines.tsx
  "configuration": {                   // Shared config patterns
    "basics": { ... },
    "fixed": { ... },
    "hourly": { ... },
    "usage": { ... }
  },
  "preset": {                          // Preset-specific variants
    "basics": { ... },
    "fixed": { ... },
    "hourly": { ... },
    "usage": { ... }
  },
  "services": {                        // Service list components
    "generic": { ... },
    "hourlyPreset": { ... },
    "usagePreset": { ... }
  },
  "forms": {                           // Form sub-components
    "hourlyConfig": { ... },
    "usageConfig": { ... },
    "bucketConfig": { ... },
    "tierEditor": { ... },
    "serviceForm": { ... },
    "editQuantity": { ... }
  },
  "typeSelector": { ... },             // ContractLineTypeSelector.tsx
  "router": { ... },                   // Router loading/error states
  "common": {                          // Shared across multiple files
    "validation": { ... },
    "actions": { ... },
    "labels": { ... },
    "errors": { ... }
  }
}
```

## Acceptance Criteria

1. **All 21 files** import `useTranslation` from `@alga-psa/ui/lib/i18n/client` and call `t()` for every user-visible string
2. **Every `t()` call** includes a `defaultValue` with the original English text as fallback
3. **`msp/contract-lines.json`** exists in `server/public/locales/en/` and contains all extracted keys
4. **7 language files** exist in their respective locale directories with accurate translations
5. **Pseudo-locale files** (xx, yy) exist and cover all keys
6. **`validate-translations.cjs`** passes with zero errors for the new namespace
7. **No visual regressions** with `msp-i18n-enabled` OFF -- all components render identically with English defaults
8. **Interpolation** works correctly for dynamic values (e.g., service names, tier numbers, currency amounts)
9. **Validation messages** with interpolated values (e.g., "Service {{index}}: Please select a service") render correctly in all languages
10. **Long translations** (German/Dutch ~30-50% longer) do not cause layout overflow in form labels, buttons, card descriptions, or accordion headers
11. **Tooltip content** is translated (overtime/after-hours info tooltips, rate tooltips)
12. **Table column headers** are translated (Service Name, Billing Frequency, etc.)
13. **Empty state messages** are translated ("No services currently associated...", "Select a contract line to manage its services")
14. **ROUTE_NAMESPACES** updated to load `msp/contract-lines` for billing routes