# Scratchpad — MSP i18n Batches 2b-1 + 2b-2: Core + Dashboard

- Plan slug: `2026-03-19-msp-i18n-batch-2b1-core`
- Created: `2026-03-19`

## Decisions

- (2026-03-19) **menuConfig.ts approach**: Option A — add `translationKey` field to `MenuItem` and `NavigationSection`. Keep `name` as stable identifier / English fallback. Sidebar.tsx uses `t(item.translationKey) || item.name` for display. This avoids making menuConfig depend on React hooks and keeps it as a plain data export.
- (2026-03-19) **GitHubStarButton**: Skip translation — "Star" text and aria-label are injected by the external GitHub buttons widget script, not our code.
- (2026-03-19) **"AlgaPSA" brand name**: Keep hardcoded — brand names are not translated. Only the alt text ("AlgaPSA Logo") gets a key.
- (2026-03-19) **Breadcrumb translation**: `getMenuItemNameByPath()` returns `item.name` (English). Once Sidebar translates via `translationKey`, breadcrumbs should also translate. Two options: (a) move translation lookup into `getMenuItemNameByPath` by passing `t` function, or (b) return the translationKey and let breadcrumb component call `t()`. Decision: option (a) — pass `t` to the function or move it into Header component where `t` is available.
- (2026-03-19) **TIER_LABELS**: TrialBanner uses `TIER_LABELS[tier]` from `@alga-psa/types` for tier display names ("Pro", "Premium"). These are product tier names and should likely stay in English. Only the surrounding text ("Trial:", "days left", "confirm to keep") gets translated.
- (2026-03-19) **Billing key collision**: `nav.billing` could not remain a plain string once the billing sidebar section and item keys moved under `nav.billing.*`. The top-level billing nav label now uses `nav.billing.label`, while section/item keys stay under `nav.billing.sections.*` and `nav.billing.<item>`.

## Discoveries / Constraints

### Core (msp/core)
- (2026-03-19) `msp/core.json` already has 72 keys covering: nav.* (27), sidebar.* (4), settings.sections.* (6), settings.tabs.* (17+), header.* (5). Many sidebar/header strings are NOT yet wired up — the keys exist but components still use hardcoded English.
- (2026-03-19) Sidebar.tsx does NOT use `useTranslation` currently. It reads `item.name` directly from menuConfig. The `sidebar.backToMain` key exists in core.json but is not consumed.
- (2026-03-19) Header.tsx does NOT use `useTranslation` currently. The `header.*` keys exist in core.json but are not consumed.
- (2026-03-19) `settingsNavigationSections` has a "Language" item that's conditionally filtered out when `msp-i18n-enabled` is OFF. This filter uses `item.name !== 'Language'` — if we change how names work, this filter needs to use `translationKey` or a stable id instead.
- (2026-03-19) `billingNavigationSections` has 4 section titles + 12 items = 16 new strings. These are NOT in the current core.json.
- (2026-03-19) `QuickCreateDialog.tsx` delegates to child components (QuickAddTicket, QuickAddClient, etc.) which have their own internal strings — those are OUT OF SCOPE for this batch. Only the wrapper's toast messages, dialog titles, and error messages are in scope.
- (2026-03-19) `RightSidebar.tsx` CE fallback has only 2 strings. The enterprise version (`@enterprise/components/layout/RightSidebar`) is separate and out of scope.
- (2026-03-19) `PlatformNotificationBanner.tsx` renders `banner_content` via `dangerouslySetInnerHTML` — this content comes from the database and is NOT translatable via i18n keys. Only the "Learn More" and "Dismiss" buttons are in scope.

### Dashboard (msp/dashboard)
- (2026-03-19) Dashboard has NO existing translations — `msp/dashboard.json` doesn't exist yet. This is a new namespace.
- (2026-03-19) Onboarding components live in `packages/onboarding/src/components/dashboard/`, NOT in `server/src/`. They import from `@alga-psa/onboarding`. Need to verify `useTranslation` works from package context (it should — `@alga-psa/ui/lib/i18n/client` is the shared import path).
- (2026-03-19) `stepDefinitions.ts` is a plain data file (not a React component) — same pattern as menuConfig. Should export `translationKey` fields, rendering component calls `t()`.
- (2026-03-19) `DashboardContainer.tsx` shows different welcome banners for Enterprise vs Community editions — both need translation.
- (2026-03-19) Onboarding progress ring has interpolated text: "3 of 5 Steps" — needs `{{completed}}` and `{{total}}` variables.
- (2026-03-19) Feature cards have a "Coming soon!" toast — this fires on click for cards without an href. Simple string, one key.
- (2026-03-19) `ROUTE_NAMESPACES` currently maps `/msp` to `['common', 'msp/core']`. Need to add `'msp/dashboard'` to both `/msp` and `/msp/dashboard` routes.
- (2026-03-19) `DashboardOnboardingSlot.tsx` and `DashboardOnboardingSkeleton.tsx` have no user-visible text — just layout/loading components. No translation needed.
- (2026-03-19) `DashboardOnboardingSection.tsx` had a hidden rerender-loop bug: its `initialDismissedStepIds = []` default created a fresh array every render, retriggering the `useEffect` dependency and causing an infinite update loop when the prop was omitted. Fixed by hoisting a stable empty constant (`F071` / `T101`).
- (2026-03-19) `DashboardOnboardingSection.tsx` had two additional user-visible hardcoded error fallbacks (`Failed to dismiss onboarding step.`, `Failed to restore onboarding step.`) not enumerated in the PRD tables. Added them to `msp/dashboard.json` under `onboarding.errors.*` because they are user-facing dashboard strings.
- (2026-03-19) `DashboardContainer.tsx` needed an explicit `FeatureCardDefinition` type; otherwise the translated feature-card array widened into a union where `href` was not guaranteed and `next build` failed during TypeScript.

## Progress Log

- (2026-03-19) Completed `F001-F006` and `T001-T009` together in the shared menu config layer. Added optional `translationKey` metadata to `MenuItem` and `NavigationSection`, populated every main/bottom/settings/billing/extensions nav item with stable i18n keys, and added `server/src/test/unit/layout/menuConfig.i18n.test.ts` to lock the mapping in place before Sidebar/Header consume it.
- (2026-03-19) New core keys implied by the menu config and still pending locale-file work: `nav.documentsAll`, `nav.knowledgeBase`, `nav.controlPanel`, `nav.workflowEditor`, `nav.systemMonitoring`, `nav.jobMonitoring`, `settings.tabs.language`, `settings.tabs.sla`, and all `nav.billing.*` entries.
- (2026-03-19) Completed `F007-F012` and `T010-T018` in `Sidebar.tsx`. Sidebar now translates menu item labels by cloning config items with `t(item.translationKey)`, translates the dashboard link/logo/toggle/back-to-main chrome, and filters the hidden Language settings entry by `translationKey` instead of English text so locale changes do not break the feature-flag behavior.
- (2026-03-19) Added `server/src/test/unit/layout/Sidebar.i18n.test.tsx` with a lightweight tooltip/collapse mock to verify translated open-state labels, collapsed tooltip labels, section titles in settings and billing modes, and the English fallback path when translations are unavailable.
- (2026-03-19) Completed `F013-F019` and `T019-T029` in `Header.tsx`. Quick Create, Job Activity, breadcrumb root/current label lookup, tenant badge interpolation, and existing user-menu fallback strings now all read through `useTranslation('msp/core')` with English defaults so the pre-i18n flag-off path stays stable.
- (2026-03-19) Added `server/src/test/unit/layout/Header.i18n.test.tsx` and updated `server/vitest.config.ts` aliases to cover `@alga-psa/jobs`. The header tests verify translated quick-create labels/descriptions, job activity strings, breadcrumb translation from menu translation keys, and the tenant badge `{{tenant}}` interpolation path.
- (2026-03-19) Completed `F020` and `T030-T032` in `DefaultLayout.tsx` by translating both AI interruption dialog variants through `msp/core` keys with English defaults. Reused `server/src/test/unit/layout/DefaultLayout.chatInterruptGuard.test.tsx` for translated title/confirm/cancel assertions instead of creating a duplicate harness.
- (2026-03-19) Extended the DefaultLayout test harness with a direct mock for `@alga-psa/msp-composition/scheduling/MspSchedulingCrossFeatureProvider` so the unit test stays isolated from deeper ticket/document cross-feature imports while still exercising the interrupt guard behavior.
- (2026-03-19) Completed `F021-F024` and `T033-T037` in `TrialBanner.tsx`. Trial copy now uses `msp/core` keys with explicit English defaults, and the singular/plural day label is built once and interpolated into both premium and Stripe trial wrapper strings while keeping `TIER_LABELS` product names untranslated.
- (2026-03-19) Added `server/src/test/unit/layout/TrialBanner.i18n.test.tsx` to cover premium-confirmed, premium singular-day, Stripe plural-day, and tier-name interpolation branches. This gives direct verification that `{{count}}`, `{{daysLabel}}`, and `{{tier}}` survive the component wiring.

## Commands / Runbooks

- **Validate translations**: `node scripts/validate-translations.cjs`
- **Generate pseudo-locales**: `npx ts-node scripts/generate-pseudo-locale.ts --locale xx --fill "1111"`
- **Italian accent audit**: `grep -n ' e [a-z]\| puo \| gia \| verra \| funzionalita\| necessario' server/public/locales/it/msp/core.json`
- **Count keys**: `node -e "const o=JSON.parse(require('fs').readFileSync('server/public/locales/en/msp/core.json'));const c=(o,p='')=>{let n=0;for(const[k,v]of Object.entries(o)){if(typeof v==='object'&&v!==null)n+=c(v,p+k+'.');else n++}return n};console.log(c(o))"`
- **Visual QA**: Enable `msp-i18n-enabled` flag locally, switch to `xx` locale, navigate sidebar/header/settings/billing modes
- **Dashboard component suite**: `cd server && npx vitest run --config vitest.config.ts src/test/unit/i18n/mspDashboardBatch2b1.test.ts src/test/unit/dashboard/DashboardContainer.i18n.test.tsx src/test/unit/onboarding/DashboardOnboardingSection.i18n.test.tsx src/test/unit/onboarding/OnboardingChecklist.i18n.test.tsx`
- **Full build verification**: `npm run build`

## Progress Log

- (2026-03-19) Completed `F025-F030` and `T038-T051`.
  - `PaymentFailedBanner.tsx` now reads `banners.paymentFailed.message` and `banners.paymentFailed.portalError` from `msp/core`.
  - `QuickCreateDialog.tsx` now translates all success toasts, loading dialog titles, and client/service-type load errors through `msp/core`, preserving interpolation for ticket numbers and entity names.
  - `RightSidebar.tsx` now translates the CE fallback title/message via `rightSidebar.*`.
  - `PlatformNotificationBanner.tsx` now translates the Learn More CTA and dismiss aria-label via `banners.platformNotification.*`.
  - Validation: `cd server && npx vitest run --config vitest.config.ts src/test/unit/layout/PaymentFailedBanner.i18n.test.tsx src/test/unit/layout/RightSidebar.i18n.test.tsx src/test/unit/layout/PlatformNotificationBanner.i18n.test.tsx src/test/unit/layout/QuickCreateDialog.i18n.test.tsx`
  - Gotcha: the platform notification test emits a React warning because the local `next/link` mock forwards `prefetch={false}` to a DOM anchor; behavior is otherwise correct and assertions pass.
- (2026-03-19) Completed `F031-F043` and `T052-T062`, `T064-T066`.
  - Rebuilt `server/public/locales/*/msp/core.json` for all 7 production locales plus `xx` and `yy`, adding the new shell/sidebar/header/dialog/banner/quick-create/right-sidebar keys and the nested billing navigation structure.
  - Added `settings.tabs.language` and `settings.tabs.sla` across all locales and introduced `nav.billing.label` to avoid the string-vs-object collision with nested `nav.billing.sections.*` and `nav.billing.<item>` keys.
  - Added `server/src/test/unit/i18n/mspCoreBatch2b1.test.ts` to verify the English key inventory, production-locale alignment, pseudo-locale fills, variable preservation, Italian accents, representative `xx` QA coverage, and German overflow-sensitive label lengths.
  - Extended `Sidebar.i18n.test.tsx` with a feature-flag check that hides the Language item when `msp-i18n-enabled` is off.
  - Validation:
    - `node scripts/validate-translations.cjs`
    - `cd server && npx vitest run --config vitest.config.ts src/test/unit/i18n/mspCoreBatch2b1.test.ts src/test/unit/layout/Sidebar.i18n.test.tsx src/test/unit/layout/menuConfig.i18n.test.ts`
  - Gotcha: the old `npx ts-node scripts/validate-translations.ts` runbook in this plan is stale; the repository validator lives at `scripts/validate-translations.cjs`.

## Links / References

- Translation plan: `.ai/translation/MSP_i18n_plan.md`
- Translation guide: `.ai/translation/translation-guide.md`
- File structure: `.ai/translation/translation_files_structure.md`
- Phase 1 plan: `docs/plans/2026-02-12-msp-i18n-phase1/`
- Infra sprint plan: `docs/plans/2026-02-19-msp-i18n-infrastructure-sprint/`

### Key file paths

| File | Role |
|------|------|
| `server/src/config/menuConfig.ts` | Menu data — needs translationKey fields |
| `server/src/components/layout/Sidebar.tsx` | Main sidebar — needs useTranslation |
| `server/src/components/layout/Header.tsx` | Top bar — needs useTranslation |
| `server/src/components/layout/DefaultLayout.tsx` | Layout wrapper — AI interrupt dialogs |
| `server/src/components/layout/TrialBanner.tsx` | Trial status badge |
| `server/src/components/layout/PaymentFailedBanner.tsx` | Payment failure badge |
| `server/src/components/layout/QuickCreateDialog.tsx` | Quick-create modal + toasts |
| `server/src/components/layout/RightSidebar.tsx` | CE chat fallback |
| `server/src/components/layout/PlatformNotificationBanner.tsx` | Platform notifications |
| `server/public/locales/en/msp/core.json` | English core translation file |
| `server/public/locales/en/msp/dashboard.json` | English dashboard translation file (TO CREATE) |
| `server/src/components/dashboard/DashboardContainer.tsx` | Main dashboard component |
| `packages/onboarding/src/components/dashboard/DashboardOnboardingSection.tsx` | Onboarding progress cards |
| `packages/onboarding/src/components/dashboard/OnboardingChecklist.tsx` | Alternative checklist view |
| `packages/onboarding/src/lib/stepDefinitions.ts` | Onboarding step data |
| `packages/core/src/lib/i18n/config.ts` | ROUTE_NAMESPACES config |

## Progress Log

- (2026-03-19) Completed dashboard namespace batch (`F050-F070`): created `msp/dashboard.json` for all production locales + pseudo-locales, translated `DashboardContainer.tsx`, `DashboardOnboardingSection.tsx`, `OnboardingChecklist.tsx`, and `stepDefinitions.ts`, and updated `ROUTE_NAMESPACES` to load `msp/dashboard` on `/msp` and `/msp/dashboard`.
- (2026-03-19) Added dashboard i18n verification coverage: `server/src/test/unit/i18n/mspDashboardBatch2b1.test.ts`, `server/src/test/unit/dashboard/DashboardContainer.i18n.test.tsx`, `server/src/test/unit/onboarding/DashboardOnboardingSection.i18n.test.tsx`, and `server/src/test/unit/onboarding/OnboardingChecklist.i18n.test.tsx`. These now cover `T070-T101`.
- (2026-03-19) Ran `node scripts/validate-translations.cjs` after adding dashboard locales — passed with 0 errors / 0 warnings.
- (2026-03-19) Ran the dashboard component and locale suite — all 19 dashboard tests passed.
- (2026-03-19) Ran `npm run build` successfully. Build still emits pre-existing webpack warnings (scheduling star-export conflict, handlebars `require.extensions`, knex/fluent-ffmpeg/Temporal dynamic dependency warnings), but the build completed and closed `T063`.

## Open Questions

- **Breadcrumb name source**: Currently `getMenuItemNameByPath()` returns English `item.name`. Need to decide how to pass `t()` function to it (it's called inside the Header component, so `t` is available — could change the function signature to accept a translator, or move the logic inline).
- **Language filter in Sidebar**: The `item.name !== 'Language'` check needs updating once translationKeys are used. Should use `item.translationKey !== 'settings.tabs.language'` or add a stable `id` field.
- **Onboarding package imports**: Verify that `useTranslation` from `@alga-psa/ui/lib/i18n/client` works correctly when called from components in `packages/onboarding/`. The i18n context is provided at the layout level, so it should work — but test early.
- **stepDefinitions.ts pattern**: Should it use the same `translationKey` pattern as menuConfig? Or should the rendering components just use hardcoded key paths like `t('onboarding.steps.identity.title')`? The latter is simpler since step IDs are stable.