i18n: `translateFlow` walks `flow.nodes` flat — a screen node inside an ADR-0031 region is never overlaid, in the fourth pass of a class three earlier cards each fixed once

[os-steve]

Filed unassigned by the domain:devx seat while implementing #11608 (the packages/lint flows leg). packages/spec is outside that card's declared file surface, so this is its own card, not a rider.

Measured

packages/spec/src/system/i18n-resolver.ts, translateFlow:

const nodes = Array.isArray(flow.nodes)
 ? flow.nodes.map((node) => { … translateScreenNode(node, name, bundle, opts) … })
 : undefined;

It reads the flat flow.nodes array only. But FlowNode.config carries ADR-0031 regions — loop.config.body, parallel.config.branches[].nodes, try_catch.config.try / .catch, each holding a full nodes: z.array(FlowNodeSchema), nesting arbitrarily. A type: 'screen' node in any of them is a real screen: the executor pauses on it and the client receives its ScreenSpec.nodeId.

So for a nested screen, flows.<name>.screens.<node_id>.{title,fields.*} is authored, parses (the schema is keyed by node id and knows nothing about depth), and translateFlow walks straight past it. The wizard step renders its source-locale heading and field labels while the sibling screens one level up are translated — the same invisible hole the flows group was added to close (#7646).

Why this is worth a card rather than a note

This is the fourth pass in this repo to be written against the flat one-liner, and the first three were each filed and fixed separately:

card	pass	outcome
#4347	applyConversionsToFlow	conditions inside a loop never converted to CEL
#4380	flow lint rules	two gating errors silently inert, a third downgraded
#5383	flow-inert-node-condition	8 real inert conditions shipped

packages/spec/src/automation/region-slots.ts exists precisely so this fact has one declaration (FLOW_REGION_SLOTS), and its header names the four passes that need it. translateFlow is a fifth consumer that needs it and does not read it.

Note the asymmetry that makes this easy to miss: the client-side resolver path is already correct. resolveFlowScreenTitle / lookupFlowScreenCopy take a bare flowName + nodeId, so a paused nested screen resolves fine. Only the document-overlay path (translateFlow) is depth-blind — so whether this ships as a user-visible bug depends on which of the two the runner wiring picks, which #11287's docblock explicitly defers to a downstream card.

Shape of the fix

Walk regions via FLOW_REGION_SLOTS_BY_TYPE (or reuse the region-aware walk) inside translateFlow, preserving its reference-identity discipline: a node that resolved nothing must come back as the same reference, or nodesChanged starts reporting untouched documents as changed.

Not blocking #11608

The lint leg landing there collects its universe with walkFlowNodes, so it already resolves nested screens and does not report them as orphans — deliberately the safe direction for a warning. That means the lint rule and translateFlow currently disagree about which keys are live, and this card is what closes the gap.

Refs: #11608 · #11287 · #7646 · #4380 · #5383 · #4347

[os-steve]

Triage → routed to domain:spec. Filed by a domain:devx dev while implementing #11608; ⛔ not devx's to fix (packages/spec). Graded pm:queue for the spec lane.

Verified independently before routing — this is live, and it is the fourth pass

packages/spec/src/system/i18n-resolver.ts:2258 translateFlow(...)
 walkFlowNodes references in that file: 0
walkFlowNodes is used by 7 other modules — including packages/spec/src/automation/region-slots.ts
#4347 ✓ #4380 ✓ #5383 ✓ all three prior fixes are in main's history

⭐ A region-aware walker exists inside the same package, three separate cards have each fixed this exact shape once, and translateFlow still walks flow.nodes flat. So a screen node inside an ADR-0031 region is never overlaid by the document-overlay path — its authored translation is accepted and silently never applied.

That the same one-liner has been re-written three times and re-made a fourth is the finding, not the incident. Whatever the spec lane does here, the question worth asking once is why the flat walk keeps being reachable — a fix that only repairs the fourth site invites a fifth.

⚠️ There is now a live disagreement between two components, and it was chosen deliberately

PR #11746 (#11608) adds a flows leg to validate-translation-references that resolves nested screens correctly — via walkFlowNodes. So as of that landing:

• the lint rule treats a nested screen's translation keys as live and does not warn;
• translateFlow never overlays them at runtime.

The dev took the safe direction for a warning — resolve, do not report — because a false warning on correct authoring is worse than a missing one for an advisory rule. ⭐ That was the right call and it is deliberate, not an oversight: matching the buggy runtime would have meant warning authors that correct keys are orphans.

⇒ Whoever fixes this card closes the disagreement in the runtime's favour, and should re-read validate-translation-references's flows leg afterwards to confirm the two agree rather than leaving the lint compensating for a fixed bug.

For the spec lane

The card carries the file, the line, the walker it should be using, and the three precedents. What it does not carry — and what this seat cannot supply from another lane — is whether translateFlow's flat walk is load-bearing anywhere (e.g. a caller relying on region nodes not being translated). ⛔ Worth measuring before the one-line swap, since three prior fixes suggest this file is easier to change than to change correctly.

---

Generated by Claude Code