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

# Scratchpad — MSP i18n: Credits Sub-batch

- Plan slug: `2026-04-09-msp-i18n-credits`
- Created: `2026-04-09`
- Last synced to codebase: `2026-04-17`

## Status Recheck (2026-04-17)

**Correction (2026-04-17 re-read):** an earlier version of this section said "Still 0% implemented" — that was based on stale `ls` output against `origin/main`. The **actual** state on branch `i18n/billing_credits` (32 commits ahead of origin/main) is:

- `features.json`: **22/22** features implemented.
- `tests.json`: **31/31** tests implemented.
- `server/public/locales/en/msp/credits.json` **exists** (plus de/es/fr/it/nl/pl/xx/yy — 9 locale files total, 185 lines each).
- All 8 client components wired with `useTranslation('msp/credits')` (except `CreditsPage.tsx` which delegates to the new `CreditsPageClient.tsx` wrapper per the server-component decision).
- New file: `packages/billing/src/components/credits/CreditsPageClient.tsx` (350 LOC) implementing the recommended server→client split.
- `/msp/billing/credits` added to `ROUTE_NAMESPACES` in `packages/core/src/lib/i18n/config.ts`.
- Seven new Vitest suites under `packages/billing/tests/` (`CreditsPage`, `CreditControls`, `CreditManagement`, `CreditReconciliation`, `CreditApplicationExpiration`, `CreditsLocaleSmoke`, `creditsNamespaceAndRoute`).

Status on this branch: **implementation complete, pending merge to `main`**. On `origin/main` the plan is still 0%.

### Adjacent work (context)

| Change | Impact |
|---|---|
| Billing-settings plan (`2026-04-09-msp-i18n-billing-settings`) shipped — `CreditExpirationSettings` lives in `msp/billing-settings`, not `msp/credits`. | No file overlap; the dashboard-side `CreditExpirationInfo.tsx` + `CreditExpirationModificationDialog.tsx` are covered here. Terminology mirrored across namespaces. |
| Enum-labels pattern adopted 2026-04-14 (`.ai/translation/enum-labels-pattern.md`). | No shared billing-frequency enum rendering in the 10 credit components — no migration needed. |

---

## What This Is

Greenfield i18n namespace creation + wiring for 10 credit management components. Unlike the
tickets migration (which extended an existing 147-key namespace), this batch creates
`msp/credits.json` from scratch and wires all components for the first time.

## Decisions

- **(2026-04-09)** Create a dedicated `msp/credits` namespace rather than adding to
  `features/billing.json`. Rationale: credit management is MSP-only (no client-portal
  equivalent), and the billing namespace already covers invoicing/plans. ~80 keys warrants
  its own file.
- **(2026-04-09)** `CreditsPage.tsx` is a server component. Strategy: create a thin
  `CreditsPageClient.tsx` wrapper that calls `useTranslation('msp/credits')` and passes
  translated strings down. The server component fetches data; the client component handles
  i18n. This matches the pattern used elsewhere in the codebase.
- **(2026-04-09)** `CreditsTabs.tsx` has zero user-visible strings (tab labels come from
  props). Skip it entirely.
- **(2026-04-09)** `actions.ts` is a server action file. The error strings like
  `'Authentication required'` and `'Transfer amount must be greater than zero'` do surface
  to callers via the `{ success: false, error: '...' }` return shape. However, these are
  consumed by client components that can translate them at the display layer. Leave
  `actions.ts` untouched; translate error display in consuming components.
- **(2026-04-09)** Use `t('key', { defaultValue: 'English fallback' })` pattern per project
  convention. This ensures English renders if translations are missing.
- **(2026-04-09)** Currency amounts stay formatted via `formatCurrency()` (which already
  handles locale). Dates stay formatted via `toLocaleDateString()` or `formatDateOnly()`.
  Do NOT wrap these in `t()`.
- **(2026-04-09)** Recharts `name` props in Bar/Pie components (e.g., "Credits Issued",
  "Credits Applied") need translation since they appear in chart legends. The `formatter`
  callbacks that use `formatCurrency()` do NOT need translation.

## Discoveries / Constraints

- **(2026-04-09)** `CreditManagement.tsx` (642 LOC) and `CreditReconciliation.tsx` (604 LOC)
  are the largest components. CreditManagement has duplicate column definitions with
  `CreditsPage.tsx` -- both define columns for the credits table with identical titles.
  Consider extracting shared column title keys to avoid duplication.
- **(2026-04-09)** `CreditManagement.tsx` contains a `renderCreditContext()` helper function
  with several context-specific labels (Lineage Missing, Transferred Recurring Credit,
  Recurring Source, Financial Only). These are credit-specific domain terms that need
  careful translation.
- **(2026-04-09)** `CreditReconciliation.tsx` uses `toast.success()` for the validation
  result message. This needs interpolation:
  `t('reconciliation.validationResult', { balanceCount: result.balanceDiscrepancyCount, trackingCount: result.missingTrackingCount + result.inconsistentTrackingCount })`.
- **(2026-04-09)** The chart time-range labels in `generateExpirationChartData` (< 7 days,
  < 30 days, < 90 days, > 90 days) should be translated. These are passed as `name` to
  Recharts data arrays and appear in tooltips/legends.
- **(2026-04-09)** The `/msp/billing/credits` route does not currently exist in
  `ROUTE_NAMESPACES`. The existing `/msp/billing` entry loads
  `['common', 'msp/core', 'features/billing', 'msp/reports']`. The new entry must be placed
  so that longest-prefix matching resolves it before `/msp/billing`. Since object key order
  matters for iteration, insert it immediately above the `/msp/billing` line.
- **(2026-04-09)** `CreditReconciliation.tsx` uses `useSession` from `next-auth/react` to
  get the current user ID for the validation action. This is unrelated to i18n but notable
  -- it does not use `withAuth`.

## Key Groups in msp/credits.json

| Group | Est. Keys | Source Components |
|-------|----------|-------------------|
| page | 6 | CreditsPage |
| columns | 10 | CreditsPage, CreditManagement |
| status | 5 | CreditsPage, CreditManagement |
| actions | 8 | CreditsPage, CreditManagement, AddCreditButton, BackButton |
| tabs | 3 | CreditsPage, CreditManagement |
| settings | 8 | CreditsPage |
| charts | 10 | CreditManagement, CreditsPage |
| stats | 4 | CreditManagement |
| management | 4 | CreditManagement |
| reconciliation | 25 | CreditReconciliation |
| application | 15 | CreditApplicationUI |
| expiration | 6 | CreditExpirationInfo |
| expirationDialog | 13 | CreditExpirationModificationDialog |
| context | 8 | CreditManagement |
| **Total** | **~125** | |

## Gotchas

1. **Server component**: `CreditsPage.tsx` is async and does not have `'use client'`. Cannot
   call `useTranslation()` directly. Must wrap in a client component.
2. **Duplicate column definitions**: `CreditsPage.tsx` and `CreditManagement.tsx` both define
   nearly identical column arrays with the same title strings. Use the same translation keys
   for both to avoid drift.
3. **Recharts `name` prop**: Bar and Pie chart `name` strings appear in legends and tooltips.
   These must be translated, but `name` is set at render time so `t()` works normally.
4. **Chart data labels**: The expiration chart data (`< 7 days`, `< 30 days`, etc.) is
   generated in a function and stored in state. The `t()` call must happen at generation time
   or the data must be regenerated when locale changes.
5. **Status badge HTML**: Status strings like "Expiring Soon (X days)" use JSX with
   interpolation. Use `t('status.expiringSoon', { days: daysUntilExpiration })`.
6. **Toast message in CreditReconciliation**: The `toast.success()` call uses a template
   literal. Replace with `t()` + interpolation.
7. **Month abbreviations in placeholder chart data**: The `placeholderCreditUsageData` array
   uses English month names (Jan, Feb, etc.). These are placeholder data and will eventually
   come from an analytics endpoint. For now, translate them as keys or leave as-is since
   they are placeholder/demo data. Decision: translate them since they are user-visible.

## Implementation Log

- **(2026-04-17, F001)** Added the greenfield English namespace at
  `server/public/locales/en/msp/credits.json`. The file now defines the 14 planned top-level
  groups (`page`, `columns`, `status`, `actions`, `tabs`, `settings`, `charts`, `stats`,
  `management`, `reconciliation`, `application`, `expiration`, `expirationDialog`,
  `context`) and includes the shared table/status/chart/tab vocabulary needed by all 8 client
  components plus the server `CreditsPage` wrapper. Included a few pragmatic extras inside the
  planned groups rather than adding new top-level groups:
  management load/empty states, reconciliation tab labels, short month labels for placeholder
  charts, and generic application/expiration failure strings. This keeps later wiring stable
  and avoids repeated locale-file churn.
- **(2026-04-17, F002)** Added `server/public/locales/fr/msp/credits.json` with full key parity
  against English. Kept the same structure and interpolation tokens, translated the domain-
  specific copy directly (credit reconciliation, recurring-lineage context, expiration flows),
  and preserved the placeholder chart month subgroup so later pseudo-generation remains
  mechanical.
- **(2026-04-17, F003)** Added `server/public/locales/es/msp/credits.json` with matching key
  structure and preserved interpolation variables. Kept the recurring-credit context labels,
  expiration flow copy, and reconciliation phrasing idiomatic enough for MSP billing rather
  than literal English carry-over.
- **(2026-04-17, F004)** Added `server/public/locales/de/msp/credits.json`. Paid extra
  attention to the reconciliation/dashboard nouns and the “financial artifact / recurring
  service period” explanatory copy so the German file remains readable instead of over-literal.
- **(2026-04-17, F005)** Added `server/public/locales/nl/msp/credits.json` with the same key
  shape. Kept the recurring-context explanation and reconciliation wording explicit, since
  those are the easiest places for machine-like Dutch to leak in.
- **(2026-04-17, F006)** Added `server/public/locales/it/msp/credits.json` and deliberately
  used accented/contracted Italian forms where they naturally occur (`più`, `Si è`, `Tutti gli`)
  so the later accent audit is testing a real localized file rather than English-looking copy.
- **(2026-04-17, F007)** Added `server/public/locales/pl/msp/credits.json` with preserved
  placeholders and the same month subgroup used by the chart placeholders. The recurring-
  lineage copy needed a light polish to stay understandable in Polish while keeping the billing
  domain meaning intact.
- **(2026-04-17, F008)** Ran `node scripts/generate-pseudo-locales.cjs` after the new English
  namespace landed. The generator rebuilt `62` pseudo-locale files from `31` English sources
  and created `server/public/locales/xx/msp/credits.json` plus
  `server/public/locales/yy/msp/credits.json`. No hand-edits to pseudo-locales were made.
- **(2026-04-17, F009)** Ran `node scripts/validate-translations.cjs` immediately after pseudo-
  locale generation. Result: `Errors: 0`, `Warnings: 0`, `PASSED` across `de/es/fr/it/nl/pl`
  plus `xx/yy`. This confirmed key parity, interpolation preservation, pseudo fill patterns,
  and the Italian file surviving the validator’s accent checks.
- **(2026-04-17, F010)** Added `'/msp/billing/credits'` to
  `packages/core/src/lib/i18n/config.ts` immediately above the broader `/msp/billing` entry.
  This preserves exact-match handling and longest-prefix fallback so the new page loads
  `msp/credits` instead of inheriting only the general billing namespaces.
- **(2026-04-17, F011)** Replaced the old mixed server/client `CreditsPage.tsx` with a thin
  server loader plus new client wrapper `packages/billing/src/components/credits/CreditsPageClient.tsx`.
  The wrapper now owns `useTranslation('msp/credits')`, translated page/card headings, tab
  labels, table column titles, status labels, and action-button copy while keeping currency and
  date formatting intact. Also normalized the expired tab to derive its rows from the fetched
  “all credits” dataset while preserving upstream fetch error states.
- **(2026-04-17, F012)** Finished the `CreditsPageClient` settings-summary translation pass.
  The inline expiration settings panel now resolves `settings.title`, `settings.creditExpiration`,
  `settings.enabled`, `settings.disabled`, `settings.expirationPeriod`, `settings.daysUnit`,
  `settings.notificationDays`, and `settings.none`, leaving no page-local settings labels in
  raw English.
- **(2026-04-17, F013)** Wired `packages/billing/src/components/credits/AddCreditButton.tsx`
  to `useTranslation('msp/credits')`. The trigger label, dialog title, placeholder paragraph,
  cancel action, and submit action all now resolve from `actions.*` / `management.addCreditPlaceholder`.
- **(2026-04-17, F014)** Wired `packages/billing/src/components/credits/BackButton.tsx` to
  `useTranslation('msp/credits')` and moved the visible label to `actions.backToCredits`.
- **(2026-04-17, F015)** Started the `CreditManagement.tsx` translation pass by wiring
  `useTranslation('msp/credits')` for the dashboard shell. Translated the page title, chart
  card titles/descriptions, stat tiles, legend labels, and placeholder month labels; moved the
  expiration bucket labels into a `generateExpirationChartData(..., t)` helper and derived the
  pie-chart labels in a locale-aware effect so pseudo/de locale changes update chart copy too.
- **(2026-04-17, F016)** Finished the `CreditManagement` table/dialog shell wiring. Refactored
  the credits table columns into `createColumns(t)` so column titles, `N/A`/`Never` fallbacks,
  status badges, row action buttons, the “Recent Credits” section copy, tab labels, “View All
  Credits” CTA, and the local add-credit dialog all now resolve from `msp/credits`.
- **(2026-04-17, F017)** Threaded `t` through `renderCreditContext()` in `CreditManagement.tsx`
  so the lineage/status explanation blocks now resolve `context.*` keys instead of rendering
  raw English helper text.
- **(2026-04-17, F018)** Began `CreditReconciliation.tsx` wiring by translating the dashboard
  heading, client selector placeholder, run button state, filter labels/options, reset action,
  and the validation toast message with `balanceCount` / `trackingCount` interpolation.
- **(2026-04-17, F019)** Completed the reporting surface in `CreditReconciliation.tsx`. The
  stat tiles, chart titles/descriptions, chart legend labels, month placeholders, table card
  copy, report-table columns, status badges, row action buttons, and tab labels with counts now
  all resolve from `msp/credits`.
- **(2026-04-17, F020)** Wired `CreditApplicationUI.tsx` to `useTranslation('msp/credits')`.
  All card copy, table columns, selection buttons, labels, helper text, empty states, and the
  generic load/apply validation errors now resolve from the credits namespace instead of raw
  English strings.
- **(2026-04-17, F021)** Wired `CreditExpirationInfo.tsx` to `useTranslation('msp/credits')`.
  The card title, applied-amount description, field labels, “Never” fallback, empty/error
  states, and ordering note now all resolve through `expiration.*`, with the applied amount
  kept as an interpolation value rather than a translated currency string.
- **(2026-04-17, F022)** Wired `CreditExpirationModificationDialog.tsx` to
  `useTranslation('msp/credits')`. The dialog title/description, field labels, switch copy,
  input label, cancel/save button states, past-date validation message, and generic update
  failure all now resolve from `expirationDialog.*` / shared `actions.*`, and raw thrown errors
  are no longer surfaced to the user.

## Key Paths / Runbooks

- English source namespace: `server/public/locales/en/msp/credits.json`
- Pseudo-locale generator: `node scripts/generate-pseudo-locales.cjs`
- Translation validator: `node scripts/validate-translations.cjs`
- Route namespace config: `packages/core/src/lib/i18n/config.ts`
- Credits page client wrapper: `packages/billing/src/components/credits/CreditsPageClient.tsx`
- Credits page server loader: `packages/billing/src/components/credits/CreditsPage.tsx`
- Credits namespace/route tests: `packages/billing/tests/creditsNamespaceAndRoute.i18n.test.ts`
- Plan artifacts:
  `ee/docs/plans/2026-04-09-msp-i18n-credits/{PRD.md,SCRATCHPAD.md,features.json,tests.json}`

## Test Log

- **(2026-04-17, T001)** Added `packages/billing/tests/creditsNamespaceAndRoute.i18n.test.ts`
  with an executable validator contract that reruns pseudo-locale generation plus
  `validate-translations.cjs` and asserts the combined pipeline stays green (`PASSED`,
  `Errors: 0`, `Warnings: 0`).
- **(2026-04-17, T002)** Extended the same namespace/route contract file with a strict top-level
  shape assertion for `server/public/locales/en/msp/credits.json`. This guards against accidental
  group drift when future i18n edits touch the credits namespace.
- **(2026-04-17, T003/T004)** Added route invariants to
  `packages/billing/tests/creditsNamespaceAndRoute.i18n.test.ts` that assert both the literal
  `ROUTE_NAMESPACES['/msp/billing/credits']` value and the runtime result of
  `getNamespacesForRoute('/msp/billing/credits')` / nested credit paths. This protects the
  longest-prefix behavior called out in the PRD.
- **(2026-04-17, T005-T008)** Added `packages/billing/tests/CreditsPage.i18n.test.ts` as the
  wrapper/server-page contract. The file checks that `CreditsPage.tsx` delegates to
  `CreditsPageClient`, that the client wrapper wires translated columns/status/tabs/settings
  summary keys, and that representative credits-page keys resolve to pseudo-locale fill in
  `xx/msp/credits.json`.
- **(2026-04-17, T009-T012)** Added `packages/billing/tests/CreditControls.i18n.test.ts` for
  the small page-shell controls. It asserts `AddCreditButton` and `BackButton` both import
  `useTranslation('msp/credits')` and checks the representative `xx` pseudo-locale keys those
  controls depend on.
- **(2026-04-17, T013-T016)** Added `packages/billing/tests/CreditManagement.i18n.test.ts` to
  cover the translated dashboard shell, chart legend labels/month placeholders, recurring-
  lineage context helper copy, and representative pseudo-locale coverage for the management tab.
- **(2026-04-17, T017-T020)** Added `packages/billing/tests/CreditReconciliation.i18n.test.ts`
  covering the translated dashboard/filter shell, report charts/table/status badges, the
  interpolated validation toast copy, and representative `xx` pseudo-locale backing for the
  reconciliation surface.
- **(2026-04-17, T021-T026)** Added `packages/billing/tests/CreditApplicationExpiration.i18n.test.ts`
  to cover the remaining credit application and expiration components: application card/table
  copy, error/empty/help states, applied-credit interpolation, and the expiration dialog’s
  label/validation/error wiring.
- **(2026-04-17, T027-T031)** Added `packages/billing/tests/CreditsLocaleSmoke.i18n.test.ts`
  for the final locale smoke layer: Italian accent/contracted-form checks, interpolation-token
  parity across all translated locales, representative English route-shell coverage, German
  non-English coverage for the management/reconciliation dashboards, and representative `xx`
  pseudo-fill checks across page/management/reconciliation/application/expiration flows.