PSA/ee/docs/plans/2026-04-18-msp-i18n-workflows/PRD.md

# PRD — MSP Workflows i18n (Batch 2b-9)

> **Status:** Draft
> **Owner:** i18n working group
> **Started:** 2026-04-18
> **Plan reference:** `.ai/translation/MSP_i18n_plan.md` → Batch 2b-9
> **Predecessors:** Batches 2b-1 through 2b-8, 2b-10 through 2b-21 already shipped. Workflows is the last large MSP surface with zero `useTranslation` wiring.

---

## Problem statement

The MSP Workflows UI (workflow definitions list, run studio, designer, task inbox) has **zero i18n wiring**. All user-visible strings are hardcoded English in components under:

- `ee/server/src/components/workflow-designer/` (34 non-test `.tsx` files + helpers)
- `ee/server/src/components/workflow-graph/` (1 `.tsx`)
- `ee/server/src/components/workflow-run-studio/` (1 `.tsx`)
- `ee/packages/workflows/src/components/workflow/` (12 `.tsx`, task + form UI)

No `msp/workflows.json` namespace exists in `server/public/locales/*/`. The MSP feature flag `msp-i18n-enabled` is shipped to all non-English users; on any workflow route they see mixed English/translated UI because the shell is translated but the workflow surface is not.

Beyond string extraction, the designer and run list contain **~13 distinct inline option arrays with English labels** (workflow run status, step status, log level, AI schema type, reference mode, wait mode, etc.). These are the `enum-labels-pattern.md` anti-pattern: they never reach `t()`, so validation passes with 0 missing keys while the UI renders English in every locale.

## User value

- Non-English MSP operators can build, run, and debug workflows in their preferred language (fr, es, de, nl, it, pl).
- Pseudo-locale QA can actually catch regressions in the workflow surface (currently every string shows as English, masking real gaps).
- Removes the single largest remaining hole in MSP coverage, unlocking Phase 7 rollout / flag removal.

## Goals

1. Create `msp/workflows` namespace with translations in en/fr/es/de/nl/it/pl + pseudo-locales xx/yy.
2. Extract every user-visible string in the 48 in-scope components to `t()` calls.
3. Migrate every inline `{ value, label }` option array and any `*_DISPLAY` / `*_OPTIONS` constants to the [enum-labels option-hook pattern](../../../../.ai/translation/enum-labels-pattern.md): `VALUES` + `LABEL_DEFAULTS` in a constants file, `useXOptions()` / `useFormatX()` hooks colocated in `ee/packages/workflows/src/hooks/`.
4. Register `/msp/workflows`, `/msp/workflows/runs`, `/msp/workflows/runs/[runId]`, `/msp/workflow-editor`, `/msp/workflow-editor/[workflowId]`, `/msp/workflow-editor/new`, and `/msp/workflow-control` in `ROUTE_NAMESPACES`.
5. Migrate hardcoded date/number/duration formatting to `useFormatters()` (the designer renders timestamps in the run list, event list, and step history; all are `toLocaleString`-flavored today).
6. Pass `node scripts/validate-translations.cjs` with zero missing/extra keys across 9 locales.
7. Visual QA on `xx`: every user-visible string in the workflow surface shows `11111`. No English bleed-through.
8. CI workflow validation passes on PR.

## Non-goals

- **Registry metadata translation.** Action display names, descriptions, and schema field labels come from `/api/workflow/registry/*` endpoints, which return whatever the action definition module declared. Those labels are *data*, not UI chrome, and belong in a separate "workflow action catalog i18n" initiative (not scoped here).
- **User-authored workflow content.** Workflow names, step names, comments, etc. are tenant data and never translated.
- **Temporal / worker / engine logs.** Server-side log lines, audit payloads, and engine error messages below the UI layer are out of scope. Only strings rendered to the operator in the run studio / dead-letter view are in scope.
- **Workflow API error responses.** Server actions keep returning English `{ success, error }` payloads; components map them to translation keys via the standard error-map pattern (see `translation-guide.md#error-and-validation-translation-pattern`).
- **`FormExample.tsx`, `TaskInboxExample.tsx`, `ConditionalFormExample.tsx`.** These are demo/example components not mounted in production routes. Extract only if trivially colocated; otherwise defer with a comment.
- **Monaco editor chrome (JSONata expression editor).** The Monaco toolbar/status messages are vendor UI; only the surrounding wrapper (hints, validation badges, placeholder text) is in scope.
- **Workflow graph React Flow node internals.** Node headers/badges that come from registry metadata are data; only static chrome (empty state, toolbar buttons) is in scope.

## Target users and primary flows

- **MSP workflow author** — opens `/msp/workflow-editor/new` or `[workflowId]`, drags actions from the palette, configures inputs, sets triggers, saves.
- **MSP workflow operator** — visits `/msp/workflows/runs`, filters by status/date, opens a run to inspect steps and logs, retries or cancels.
- **MSP admin** — inspects dead-letter queue, views audit log, manages schedules.
- **Internal task assignee** — receives a workflow-generated task, opens it from the inbox, completes the form.

Every flow must render fully localized in fr/es/de/nl/it/pl. German/Dutch layout risk is highest in the run list table (long status labels) — verify no truncation regressions.

## Enum migration — explicit scope

All the following must move from inline arrays in components to the option-hook pattern. Each lives in `ee/packages/workflows/src/constants/workflowEnums.ts` (values + label defaults) with hooks in `ee/packages/workflows/src/hooks/useWorkflowEnumOptions.ts`. Translation keys go under `enums.<enumName>.*` in `msp/workflows.json`.

| Enum | Values | Source files today | Target key root |
|------|--------|---------------------|-----------------|
| `workflowRunStatus` | RUNNING, WAITING, SUCCEEDED, FAILED, CANCELED | `WorkflowRunList.tsx:87-91` | `enums.workflowRunStatus.*` |
| `workflowRunSort` | started_at:desc/asc, updated_at:desc/asc | `WorkflowRunList.tsx:95-98` | `enums.workflowRunSort.*` |
| `workflowEventStatus` | matched, unmatched, error | `WorkflowEventList.tsx:74-76` | `enums.workflowEventStatus.*` |
| `workflowStepStatus` | STARTED, SUCCEEDED, FAILED, RETRY_SCHEDULED, CANCELED | `WorkflowRunDetails.tsx:176-180` | `enums.workflowStepStatus.*` |
| `workflowLogLevel` | DEBUG, INFO, WARN, ERROR | `WorkflowRunDetails.tsx:185-188` | `enums.workflowLogLevel.*` |
| `workflowAiSchemaType` | string, number, integer, boolean, object, array | `WorkflowAiSchemaSection.tsx:51-64` (x2 copies) | `enums.workflowAiSchemaType.*` |
| `workflowInputSourceMode` | reference, fixed | `WorkflowActionInputSourceMode.tsx:27-28` | `enums.workflowInputSourceMode.*` |
| `workflowReferenceSection` | payload, vars, meta, error, forEach | `workflowReferenceSelector.tsx:399-403` | `enums.workflowReferenceSection.*` |
| `workflowTriggerMode` | manual, event | `WorkflowDesigner.tsx:3713-3714` | `enums.workflowTriggerMode.*` |
| `workflowCanvasView` | list, graph | `WorkflowDesigner.tsx:4724-4725` | `enums.workflowCanvasView.*` |
| `workflowOnError` | continue, fail | `WorkflowDesigner.tsx:6249-6250` | `enums.workflowOnError.*` |
| `workflowWaitMode` | duration, until | `WorkflowDesigner.tsx:6550-6551` | `enums.workflowWaitMode.*` |
| `workflowWaitTiming` | fixed, expression | `WorkflowDesigner.tsx:6614-6615` | `enums.workflowWaitTiming.*` |

**Filter sentinels** (e.g. `{ value: 'all', label: 'All statuses' }`) are not enum values — they stay as plain `t('filters.allStatuses')` / `t('filters.allLevels')` / `t('filters.allTypes')` calls at each call site. Hooks return the real enum options only; the "All X" row is prepended in the component.

**Activity / task status** (`getActivityStatusOptions` in `ee/packages/workflows/src/actions/activity-actions/activityStatusActions.ts`) is a server action that returns `{ value, label }` pairs from DB rows. Those labels are data, not UI chrome — flag in `enum-labels-pattern.md`'s backlog but do **not** migrate here. If any consumer in scope renders those labels, add a TODO and keep existing behavior.

**Reviewer enforcement:** No PR in this batch adds a new `*_DISPLAY` / `*_LABELS` / `*_OPTIONS` map. No PR leaves an inline `{ value, label: 'CapitalizedEnglish' }` array in a touched component. The enum-labels grep in `enum-labels-pattern.md#finding-latent-gaps` must return zero new matches in the workflow directories after each sub-batch merges.

## Namespace + route config

- **Namespace:** `msp/workflows` — single namespace for the entire workflow surface (designer, runs, dead-letter, schedules, task inbox, audit, graph, run-studio shell).
- **Rationale for single namespace:** blast radius is one MSP feature area; no shared consumers in client portal; key count estimate (~1,000–1,500 after all sub-batches) stays well under the `msp/clients` precedent of 953.
- **`ROUTE_NAMESPACES` additions** (in `packages/core/src/lib/i18n/config.ts`):
  - `/msp/workflows`: `['common', 'msp/core', 'msp/workflows']`
  - `/msp/workflows/runs`: same
  - `/msp/workflow-editor`: same
  - `/msp/workflow-control`: same
- Prefix-match in `getNamespacesForRoute()` covers `/msp/workflows/runs/[runId]`, `/msp/workflow-editor/[workflowId]`, `/msp/workflow-editor/new` without explicit entries.

## Acceptance criteria (definition of done)

- [ ] `server/public/locales/{en,fr,es,de,nl,it,pl,xx,yy}/msp/workflows.json` all exist; key counts match exactly across all 9 locales.
- [ ] `node scripts/validate-translations.cjs` passes with zero missing or extra keys.
- [ ] No `useTranslation()` call in any in-scope component targets a namespace other than `msp/workflows`, `common`, or `msp/core`.
- [ ] The following greps (run against `ee/server/src/components/workflow-designer`, `ee/server/src/components/workflow-graph`, `ee/server/src/components/workflow-run-studio`, `ee/packages/workflows/src/components/workflow`) return zero matches:
  - `\{\s*value:\s*['"][^'"]+['"]\s*,\s*label:\s*['"][A-Z][^'"]*['"]` (inline English option arrays)
  - `^export const [A-Z_]+(_DISPLAY|_LABELS|_OPTIONS|_MAP)\s*[:=]` (label-map exports)
  - `toLocaleDateString\(['"]en` / `toLocaleString\(['"]en` (hardcoded locale formatting)
- [ ] Visual QA on `xx` locale: every user-visible string in `/msp/workflows`, `/msp/workflows/runs`, `/msp/workflows/runs/<runId>`, `/msp/workflow-editor/new`, `/msp/workflow-editor/<workflowId>`, `/msp/workflow-control`, and the task inbox renders `11111` — zero English leakage.
- [ ] Italian accent audit grep clean on `locales/it/msp/workflows.json` (see `translation-guide.md#common-pitfalls` rule 12).
- [ ] Translated section / tab names in `msp/workflows.json` match canonical names in `msp/core.json` for every language (e.g. German "Workflows" or "Arbeitsabläufe" must match whichever core.json uses).
- [ ] `ContractLinesSubbatch.i18n.test.ts`-style audit test added for the workflows surface (optional but recommended — covers regressions when new strings are added).
- [ ] CI `.github/workflows/validate-translations.yml` green.
- [ ] No component regressions in existing workflow Vitest suites (34 test files in `ee/server/src/components/workflow-designer/__tests__/`) — tests may need small updates if they assert English strings directly; prefer asserting on structural semantics (buttons by role, option values not labels).

## Risks

1. **`WorkflowDesigner.tsx` is ~7,000 lines.** Extracting strings in one pass is high-risk. Mitigation: sub-batch WF-C treats this file as its own unit; rely on the enum hooks landing in WF-A so most inline arrays are already gone.
2. **Backend status codes.** Step/run/event status enum values come from the server (Temporal activity names, DB status columns). Hook translation keys use the raw enum value (e.g. `SUCCEEDED`) as the key segment — do not normalize to lowercase. A server-side status rename becomes a missing-key defect, not a mis-translation; the default-value fallback keeps the UI functional.
3. **React Flow node labels.** `WorkflowGraph.tsx` renders nodes whose labels are computed from the workflow definition. Distinguish: static node chrome (empty state, mini-map labels, zoom controls) is in scope; node body text driven by workflow data is out of scope.
4. **Vitest snapshot / text-match breakage.** Several `__tests__/*.test.tsx` suites assert on English labels (e.g. `getByText('Running')`). When migrating a status from inline array to `useFormatWorkflowRunStatus`, the test must switch to `getByRole` or a data-testid, not rely on the English label. Budget extra time in each sub-batch for test updates.
5. **Expression editor / Monaco.** Custom hover/completion messages may have embedded English. Confirm before WF-D starts whether these are user-facing or dev-only; defer if vendor-owned.
6. **Dead-letter toast copy.** Several server actions under `workflowScheduleServerActions.ts` and dead-letter reroute flows produce toasts with English text. The pattern for server-action error strings is to map them in the component (already established in `translation-guide.md#error-and-validation-translation-pattern`) — do not translate server strings.
7. **German layout.** Run list table columns may get wider; spot-check in WF-B QA.
8. **Feature flag interaction.** `msp-i18n-enabled` is currently rolled out widely. When the flag is off, `I18nWrapper` forces locale=`en` and the component renders the `defaultValue` from each `t()` call. Every `t()` must supply `defaultValue` to match the English copy today, otherwise flag-off users see the key string.

## Rollout

- No data migrations; pure UI batch.
- No feature flag changes. `msp-i18n-enabled` already gates MSP i18n broadly; this batch simply widens coverage under the existing flag.
- Ship each sub-batch as its own PR against `main` (or intermediate branch per Alga convention). After WF-F ships, close batch 2b-9 in `MSP_i18n_plan.md`.

## Sub-batch plan

| Sub-batch | Scope | Est. keys added | PR surface |
|-----------|-------|-----------------|------------|
| WF-A | Namespace bootstrap + enum foundation. Create `msp/workflows.json` (English), add `workflowEnums.ts` constants, publish `useWorkflowEnumOptions.ts` hooks, add `ROUTE_NAMESPACES` entries, generate empty/structural keys, regenerate pseudo-locales, run validation. **No component wiring yet** except replacing inline enum arrays with hook calls where they already exist. | ~100 (enum keys × 13 enums, approximate) | Infra only |
| WF-B | Run studio surface. Wire `WorkflowRunList`, `WorkflowRunDetails`, `WorkflowRunDialog`, `WorkflowEventList`, `WorkflowDeadLetterQueue`, `WorkflowSchedules`, `WorkflowDefinitionAudit`, `RunStudioShell`, `WorkflowGraph`, `workflowRunDialogUtils`, `workflowRunTriggerPresentation`, `workflowActionPresentation`. Migrate hardcoded timestamps to `useFormatters`. | ~250 | 12 files |
| WF-C | Designer shell — `WorkflowDesigner.tsx` + `WorkflowDesignerPalette.tsx` + `PaletteItemWithTooltip.tsx`. This is the biggest single file in the batch. Depends on WF-A enum hooks being merged. | ~400 | 3 files (but one is 7k lines) |
| WF-D | Designer editors + mapping. Wire `ActionSchemaReference`, `GroupedActionConfigSection`, `InputMappingEditor`, `MappingPanel`, `SourceDataTree`, `ValidationBadge`, `MappingEditorSkeleton`, `MappingConnectionsOverlay`, `ExpressionEditor`, `ExpressionEditorField`, `ExpressionTextArea`, `ExpressionAutocomplete`, `PipelineComponents`, `WorkflowActionInputFieldInfo`, `WorkflowActionInputFixedPicker`, `WorkflowActionInputSection`, `WorkflowActionInputSourceMode`, `WorkflowActionInputTypeHint`, `WorkflowAiSchemaSection`, `WorkflowComposeTextDocumentEditor`, `WorkflowComposeTextSection`, `WorkflowStepNameField`, `WorkflowStepSaveOutputSection`, `WorkflowWaitEditors`, `workflowReferenceSelector`. | ~300 | ~22 files |
| WF-E | Task + form components in `ee/packages/workflows/src/components/workflow/`: `TaskInbox`, `TaskList`, `TaskDetails`, `TaskForm`, `TaskHistory`, `EmbeddedTaskInbox`, `DynamicForm`, `ActionButton`, `ActionButtonGroup`. Example/demo components deferred. | ~150 | 9 files |
| WF-F | AI-generate translations for fr/es/de/nl/it/pl. Regenerate pseudo-locales. Italian accent audit. Cross-check against `msp/core.json`. Run `validate-translations.cjs`. Visual QA on `xx` across all workflow routes. Fix missed strings. Update `MSP_i18n_plan.md` marking 2b-9 complete. Add Workflows rows to the component-coverage tables. | 0 (translates existing keys) | Locale files only |

Target execution cadence: WF-A first (blocking), then WF-B + WF-E in parallel, then WF-C, then WF-D, then WF-F.

## Open questions

1. Do we want a separate `msp/workflow-tasks` namespace for the task inbox components, so the task UI can be reused in client portal later without loading the full workflow designer namespace? **Tentative answer:** No — keep single `msp/workflows` namespace; if client portal ever needs tasks, split then. Documented in SCRATCHPAD.
2. Should `RunStudioShell` live in its own namespace (it's a distinct route surface)? **Tentative answer:** No — the run studio is a mode of the workflow surface, single namespace is fine. Loaded on the same route family.
3. Are there existing workflow-related translation keys in `common.json` we should reuse (e.g. `status.*`, `actions.save`)? **Answer:** Yes — reuse `common.json` for generic verbs/nouns (Save, Cancel, Delete, Back) and for generic statuses like `active`, `inactive`. Use `msp/workflows` for workflow-specific statuses (RUNNING, WAITING, etc.). Never duplicate.
4. Do we need a `features/workflow-tasks` cross-portal namespace if the task form package is eventually consumed by MSP + client portal? **Deferred** — re-evaluate only if/when client portal ever renders a workflow task. Today it doesn't.

## Related

- Full batch plan: `.ai/translation/MSP_i18n_plan.md`
- Translation workflow guide: `.ai/translation/translation-guide.md`
- Enum migration pattern: `.ai/translation/enum-labels-pattern.md`
- Example hook style: `packages/billing/src/hooks/useBillingEnumOptions.ts`
- Precedent enum backlog entries (Assets, Quotes, Invoices, Add-ons, KB): `enum-labels-pattern.md#non-billing-backlog`