@sun-asterisk/sungen 2.6.12 → 2.6.15

package/src/dashboard/types.ts

@@ -39,11 +39,47 @@ export interface AggregateSummary {
 }
 
 export interface ScreenSnapshot {
-  name: string;                        // "kudos" or "flow/checkout"
+  name: string;                        // "kudos" or "flow/checkout" — the screen DIRECTORY name
   isFlow: boolean;
-  featureName: string;
-  featurePath?: string;
+  featureName: string;                 // name of the primary (first) feature; kept for backwards compat
+  featurePath?: string;                // entry-point path of the primary feature
   specLink?: string;                   // relative path to requirements/spec.md
+  summary: ScreenSummaryStats;         // rollup across all features
+  scenarios: ScenarioSnapshot[];       // flat list across all features (each carries its `featureBaseName`)
+  features?: FeatureSnapshot[];        // present when a screen has 1+ .feature files; UI groups by this
+}
+
+/**
+ * One `.feature` file inside a screen/flow. A screen can host multiple
+ * features (e.g. `home.feature` + `home-modal.feature`), which the dashboard
+ * surfaces as sub-groups under the screen entry.
+ *
+ * When a feature has been i18n-bootstrapped (locale overlay test-data file +
+ * matching `<feature>-test-result.<locale>.json` exists), the snapshot
+ * builder packs each locale variant into the `locales` array. UI consumers
+ * can render a locale switcher; legacy consumers fall back to `scenarios`
+ * (which always reflects the base locale).
+ */
+export interface FeatureSnapshot {
+  featureBaseName: string;             // file basename without extension — "home" or "home-modal"
+  featureName: string;                 // human title from the .feature file ("Home Notifications Panel")
+  featurePath?: string;                // entry-point path declared in the .feature
+  specLink?: string;                   // relative path to requirements/spec.md, when present
+  summary: ScreenSummaryStats;         // BASE locale rollup — back-compat for non-locale consumers
+  scenarios: ScenarioSnapshot[];       // BASE locale scenarios
+  locales?: LocaleSnapshot[];          // present when 2+ locales detected (base + at least one overlay)
+}
+
+/**
+ * One locale variant of a feature's scenarios. The structure (categories,
+ * viewpoints, TC IDs) matches the base locale — only test-data values,
+ * results, and `testEnvironment` differ. `locale === ''` denotes the base
+ * locale; non-empty values come from `test-data/<feature>.<locale>.yaml`
+ * overlays plus matching `<feature>-test-result.<locale>.json` reports.
+ */
+export interface LocaleSnapshot {
+  locale: string;                      // '' for base, 'en' / 'ja' / 'staging-ja' otherwise
+  displayCode: string;                 // 'VI' / 'EN' / 'JA' — used in sheet names + UI tabs
   summary: ScreenSummaryStats;
   scenarios: ScenarioSnapshot[];
 }
@@ -64,6 +100,7 @@ export interface ScenarioSnapshot {
   category2: string;                   // Accessing | GUI | Function
   category3: string;                   // feature name
   category4: string;                   // screen name
+  featureBaseName?: string;            // .feature file basename — lets flat consumers group by feature
   vpId?: string;                       // VP-UI-001 if present
   priority: 'High' | 'Normal' | 'Low';
   type: 'Auto' | 'Manual' | 'Not compiled';

package/src/exporters/csv-exporter.ts

@@ -23,6 +23,7 @@ import {
   statusToTestResult,
 } from './playwright-report-parser';
 import { EnvironmentInfo, PlaywrightResult, ScreenSummary, TestCaseRow } from './types';
+import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
 
 export interface BuildCsvInput {
   screen: string;
@@ -35,6 +36,13 @@ export interface BuildCsvInput {
   testData: Record<string, string>;
   results: Map<string, PlaywrightResult> | null;
   env: EnvironmentInfo;
+  /**
+   * Optional selector-key → var-name map. When supplied, step / expected
+   * cells get `[selectorKey]` references swapped for the locale-specific
+   * `[testData[var]]` value — so EN sheets read "Click [ABOUT KUDOS] link"
+   * instead of the VI selector key "Click [VỀ KUDOS] link".
+   */
+  selectorKeyMap?: SelectorKeyMap;
 }
 
 /**
@@ -57,8 +65,12 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
     // Pre-condition is auth-only. Steps section = Background + @extend base
     // (entire) + own pre-Then. Expected = own's Then-onwards only.
     const precondition = formatPrecondition(authRole);
+    const localize = (text: string): string =>
+      input.selectorKeyMap
+        ? substituteSelectorKeysInStep(text, input.selectorKeyMap, input.testData)
+        : text;
     const formatStep = (s: { text: string; bucket: 'given' | 'when' | 'then' }) =>
-      s.bucket === 'given' ? keepActor(s.text) : stripActor(s.text);
+      localize(s.bucket === 'given' ? keepActor(s.text) : stripActor(s.text));
     const stepLines    = m.resolvedSteps.map(formatStep).filter(Boolean);
     const expectedLines = m.resolvedExpected.map(formatStep).filter(Boolean);
     const steps =
@@ -101,13 +113,13 @@ export function buildTestCaseRows(input: BuildCsvInput): TestCaseRow[] {
       testResult = statusToTestResult(result.status);
       executedDate = formatExecutedDate(result.startTime);
       note = formatNote(result);
-      environment = formatEnv(input.env.baseURL, input.featurePath, input.env.projectName);
+      environment = formatEnv(input.env.baseURL, input.featurePath, result.projectName || input.env.projectName);
       executor = input.env.executor;
     }
 
     // If we have environment info and the test actually ran, populate env + executor
     if (testResult !== 'Pending' && testResult !== 'N/A') {
-      if (!environment) environment = formatEnv(input.env.baseURL, input.featurePath, input.env.projectName);
+      if (!environment) environment = formatEnv(input.env.baseURL, input.featurePath, result?.projectName || input.env.projectName);
       if (!executor) executor = input.env.executor;
     }
 
@@ -306,16 +318,33 @@ export function renderCsv(summary: ScreenSummary, rows: TestCaseRow[], specLink:
 }
 
 /**
- * Write the CSV to disk at qa/deliverables/<screen>-testcases.csv.
- * Creates directory if needed.
+ * Write the CSV to disk at `qa/deliverables/<screen>-testcases[.env].csv`.
+ * When `SUNGEN_ENV` is set, the env name is appended so locale exports
+ * don't overwrite each other. Creates directory if needed.
  */
-export function writeCsv(cwd: string, screen: string, csvContent: string): string {
+/**
+ * Optional `locale` overrides `process.env.SUNGEN_ENV` — used by the
+ * multi-locale delivery aggregator. Pass an empty string to force the
+ * base (no suffix) variant.
+ */
+export function writeCsv(cwd: string, screen: string, csvContent: string, locale?: string | null): string {
   const outDir = path.join(cwd, 'qa', 'deliverables');
   if (!fs.existsSync(outDir)) {
     fs.mkdirSync(outDir, { recursive: true });
   }
-  const outPath = path.join(outDir, `${screen}-testcases.csv`);
+  const outPath = path.join(outDir, `${deliverableBasename(screen, locale)}.csv`);
   fs.writeFileSync(outPath, csvContent, 'utf-8');
   return outPath;
 }
 
+/**
+ * Build the env-aware basename used by both CSV and XLSX writers.
+ * `<screen>-testcases` becomes `<screen>-testcases.<env>` when a non-empty
+ * locale is given (or `SUNGEN_ENV` is set and no explicit override). Pass
+ * `null` / empty string to force the base variant.
+ */
+export function deliverableBasename(screen: string, locale?: string | null): string {
+  const effective = locale !== undefined ? locale : process.env.SUNGEN_ENV;
+  return effective ? `${screen}-testcases.${effective}` : `${screen}-testcases`;
+}
+

package/src/exporters/json-exporter.ts

@@ -21,6 +21,7 @@ import {
   statusToTestResult,
 } from './playwright-report-parser';
 import { EnvironmentInfo, PlaywrightResult } from './types';
+import { SelectorKeyMap, substituteSelectorKeysInStep } from './selector-key-resolver';
 import {
   ScenarioSnapshot,
   ScreenSnapshot,
@@ -37,6 +38,20 @@ export interface BuildScreenSnapshotInput {
   testData: Record<string, string>;
   results: Map<string, PlaywrightResult> | null;
   env: EnvironmentInfo;
+  /**
+   * The `.feature` file basename (without extension). Stamped onto each
+   * generated ScenarioSnapshot so flat consumers (dashboard Suites view) can
+   * group scenarios by their originating feature within a screen.
+   * Defaults to `screen` when omitted (legacy single-feature path).
+   */
+  featureBaseName?: string;
+  /**
+   * Optional selector-key → var-name map. When supplied, `steps` and
+   * `expectedResults` get `[selectorKey]` references swapped for the
+   * locale-specific value so dashboard EN tabs read "Click [ABOUT KUDOS]
+   * link" instead of the VI key "Click [VỀ KUDOS] link".
+   */
+  selectorKeyMap?: SelectorKeyMap;
 }
 
 /**
@@ -60,8 +75,12 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
     // (all of it, including its Then) + own pre-Then. Expected = own's
     // Then-onwards only. Given → keepActor (state), When/Then → stripActor.
     const precondition = formatPrecondition(authRole);
+    const localize = (text: string): string =>
+      input.selectorKeyMap
+        ? substituteSelectorKeysInStep(text, input.selectorKeyMap, input.testData)
+        : text;
     const formatStep = (s: { text: string; bucket: 'given' | 'when' | 'then' }) =>
-      s.bucket === 'given' ? keepActor(s.text) : stripActor(s.text);
+      localize(s.bucket === 'given' ? keepActor(s.text) : stripActor(s.text));
     const steps = m.resolvedSteps.map(formatStep).filter(Boolean);
     const expectedResults = m.resolvedExpected.map(formatStep).filter(Boolean);
     // Dashboard modal uses whitespace-pre-wrap — pass '\n' to render one
@@ -97,7 +116,7 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
           errorMessage = String(result.error).split('\n')[0].trim().replace(/^Error:\s*/i, '');
         }
         if (result.tracePath) tracePath = result.tracePath;
-        testEnvironment = formatTestEnvironment(input.env.baseURL, input.featurePath, input.env.projectName);
+        testEnvironment = formatTestEnvironment(input.env.baseURL, input.featurePath, result.projectName || input.env.projectName);
         testExecutor = input.env.executor;
       }
     }
@@ -108,6 +127,7 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
       category2,
       category3: input.featureName,
       category4: input.screen,
+      featureBaseName: input.featureBaseName ?? input.screen,
       vpId,
       priority,
       type,

package/src/exporters/playwright-report-parser.ts

@@ -23,6 +23,8 @@ interface PlaywrightSuite {
 interface PlaywrightSpec {
   title?: string;                // scenario title
   tests?: Array<{
+    projectName?: string;        // which project ran this test (e.g. 'chromium', 'firefox')
+    projectId?: string;
     results?: Array<{
       status?: string;           // 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted'
       startTime?: string;
@@ -94,11 +96,29 @@ export function loadPlaywrightReport(reportPath: string): Map<string, Playwright
       startTime: res?.startTime,
       error: errorMsg,
       tracePath: trace,
+      projectName: test?.projectName,
     });
   }
   return result;
 }
 
+/**
+ * Read the default project name from a Playwright JSON report.
+ * Used as a fallback when a per-test `projectName` isn't available
+ * (e.g. for `Pending` rows where no Playwright result exists yet).
+ * Returns null if the file is missing/invalid or no projects are listed.
+ */
+export function loadReportProjectName(reportPath: string): string | null {
+  if (!fs.existsSync(reportPath)) return null;
+  try {
+    const raw: PlaywrightJsonReport = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+    const name = raw.config?.projects?.[0]?.name;
+    return typeof name === 'string' && name ? name : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Strip ANSI escape sequences (terminal color/style codes) that Playwright
  * embeds in error messages. The dashboard and CSV render plain text, so

package/src/exporters/selector-key-resolver.ts

@@ -0,0 +1,190 @@
+/**
+ * Map selector keys (Gherkin `[Reference]` names) to the display text they
+ * resolve to. Used by row renderers to swap `[selectorKey]` in step text
+ * with the actual user-visible label so QA can read the step like a human
+ * reader: `Click [VỀ KUDOS]` (VI) / `Click [ABOUT KUDOS]` (EN) instead of
+ * the opaque key `Click [cta_to_kudos]`.
+ *
+ * Resolution rules (first match wins per selector entry):
+ *   1. `name` field present → use it. If it embeds exactly one `{{var}}`,
+ *      look up the locale-specific value at substitution time. Otherwise
+ *      use the literal `name` (brand names like "Sun* Kudos").
+ *   2. `value` field present AND `type` is `text` or `locator` → same logic.
+ *      For `locator` we extract the var from inside `:has-text("{{x}}")`
+ *      and similar composite templates because that var is the displayed text.
+ *
+ * Skipped entirely:
+ *   • `type: 'page'` (URL paths, not display text)
+ *   • `value` for `type: 'role'` (role name like 'button', not display)
+ *   • Entries with no `name` and no usable `value`
+ *   • Composite templates with 2+ vars (ambiguous which to use)
+ */
+
+import * as fs from 'fs';
+import { parse as parseYaml } from 'yaml';
+
+/**
+ * How to derive the display string for a selector key:
+ *   - `varName` set → look up at substitution time in the locale-specific test-data
+ *   - `literal` set → use the YAML value as-is (hardcoded text, brand names)
+ */
+export interface SelectorResolution {
+  varName?: string;
+  literal?: string;
+}
+
+export type SelectorKeyMap = Map<string, SelectorResolution>;
+
+/**
+ * Build a fresh `/g` regex each call to avoid `lastIndex` state pollution
+ * across selectors / features when matchAll / test are used on a module-
+ * scoped instance. The cost is negligible (regex compile is fast); the
+ * payoff is that processing N features sequentially can't leak state from
+ * one feature's substitution into another's selector audit.
+ */
+function varPattern(): RegExp {
+  return /\{\{\s*([a-zA-Z_][\w.]*)\s*\}\}/g;
+}
+
+function hasAnyVar(s: string): boolean {
+  return varPattern().test(s);
+}
+
+/**
+ * Extract every `{{var}}` reference from a string. Returns the list of var
+ * names (unique, in appearance order).
+ */
+function extractVars(s: string): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const m of s.matchAll(varPattern())) {
+    const v = m[1];
+    if (!seen.has(v)) {
+      seen.add(v);
+      out.push(v);
+    }
+  }
+  return out;
+}
+
+/**
+ * Decide how to resolve a field. Returns null when the field can't drive a
+ * useful display string for QA.
+ *
+ * `isLocator` true means the value is a Playwright locator selector string
+ * (CSS / XPath / attribute query). For these, hardcoded values without an
+ * embedded `{{var}}` are skipped because the literal `a[href="/x"]` is
+ * opaque garbage for QA — the original `[selectorKey]` is more informative.
+ * Composite locators that embed `{{var}}` (e.g. `:has-text("{{x}}")`) still
+ * resolve via the embedded var.
+ *
+ * For non-locator fields (`name`, or `value` with type=text), hardcoded
+ * literals ARE substituted so brand names and fixed copy ("Sun* Kudos",
+ * "Notifications") show in step text instead of opaque keys ("nav kudos").
+ */
+function resolveField(value: string, isLocator: boolean): SelectorResolution | null {
+  if (!value) return null;
+  const vars = extractVars(value);
+  if (vars.length === 0) {
+    return isLocator ? null : { literal: value };
+  }
+  if (vars.length === 1) {
+    // Sole `{{var}}` or composite like `has-text("{{var}}")`. Both resolve
+    // to the same var's locale-specific display text.
+    return { varName: vars[0] };
+  }
+  // 2+ vars in one template — ambiguous which to use; skip rather than guess.
+  return null;
+}
+
+/**
+ * Build the SelectorKey → resolution map from a selectors YAML file.
+ * Returns an empty map when the file is missing or malformed.
+ */
+export function loadSelectorKeyMap(selectorsFilePath: string): SelectorKeyMap {
+  const out: SelectorKeyMap = new Map();
+  if (!fs.existsSync(selectorsFilePath)) return out;
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(fs.readFileSync(selectorsFilePath, 'utf-8'));
+  } catch {
+    return out;
+  }
+  if (!parsed || typeof parsed !== 'object') return out;
+
+  for (const [key, raw] of Object.entries(parsed as Record<string, unknown>)) {
+    if (!raw || typeof raw !== 'object') continue;
+    const entry = raw as Record<string, unknown>;
+    const type = typeof entry.type === 'string' ? entry.type : '';
+
+    // Prefer `name` first — it's the canonical display text for role-based
+    // selectors. Skip when type is 'page' (URL paths) since pages never
+    // appear as bracket refs in step text in a display-meaningful way.
+    if (type === 'page') continue;
+
+    const nameField = entry.name;
+    if (typeof nameField === 'string') {
+      // `name` is always display text — never a locator string.
+      const resolution = resolveField(nameField, false);
+      if (resolution) {
+        out.set(key, resolution);
+        continue;
+      }
+    }
+
+    // For `text` and `locator` types the `value` field is the display text
+    // (text) or embeds it (locator with `:has-text("{{x}}")`). For role,
+    // `value` is the role name ('button', 'link') — not useful here.
+    if (type === 'text' || type === 'locator') {
+      const valueField = entry.value;
+      if (typeof valueField === 'string') {
+        const resolution = resolveField(valueField, type === 'locator');
+        if (resolution) {
+          out.set(key, resolution);
+          continue;
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Replace every `[selectorKey]` reference in a step (or expected) line with
+ * its resolved display text. Falls back to the original `[key]` when the
+ * key isn't in the map or its resolution doesn't yield a non-empty value.
+ *
+ * Sungen convention puts selector refs in square brackets, so any `[…]`
+ * substring is a candidate. Non-selector brackets (literal `[1]` etc.)
+ * safely fall through because they're never in the selector map.
+ *
+ * IMPORTANT: when the step already contains a `{{var}}` template, the
+ * substitution is SKIPPED for the whole step. Steps of the shape
+ * `See [X] header with {{x}}` already convey the locale-specific value
+ * via the `{{x}}` placeholder; replacing `[X]` with the same value would
+ * produce noisy duplication like `See [Au Co Arts Centre, Hanoi] header
+ * with {{event_location}}`. Keeping the selector key matches the source
+ * `.feature` shape and stays readable for QA reviewers.
+ */
+export function substituteSelectorKeysInStep(
+  stepText: string,
+  selectorKeyMap: SelectorKeyMap,
+  testData: Record<string, string>,
+): string {
+  // Fresh regex per call — no state pollution across step / feature boundaries.
+  if (hasAnyVar(stepText)) return stepText;
+
+  return stepText.replace(/\[([^\]]+)\]/g, (match, key: string) => {
+    // Sungen convention lowercases the bracketed Reference when computing
+    // the YAML key (`sungen-selector-keys` skill), so the step might say
+    // `[Kudos:Quick Action]` while the selector entry is `kudos:quick action`.
+    // Normalize before lookup to match both styles.
+    const trimmedKey = key.trim();
+    const res = selectorKeyMap.get(trimmedKey) ?? selectorKeyMap.get(trimmedKey.toLowerCase());
+    if (!res) return match;
+    const value = res.varName ? testData[res.varName] : res.literal;
+    if (value === undefined || value === null || value === '') return match;
+    return `[${value}]`;
+  });
+}

package/src/exporters/test-data-resolver.ts

@@ -12,19 +12,77 @@ import { parse as parseYaml } from 'yaml';
  *   kudos:
  *     recipient: "An"
  * become { "kudos.recipient": "An" }, matching {{kudos.recipient}} refs.
- * Arrays are JSON-stringified. Returns empty map if file missing.
+ * Arrays are JSON-stringified. Returns empty map if both files are missing.
+ *
+ * When `SUNGEN_ENV` is set, also merges the matching overlay file alongside
+ * the base (e.g. `login.yaml` + `login.vi.yaml`). Shallow root-level merge —
+ * keys present in the overlay replace base. Matches the compile-time runtime
+ * resolver behaviour in src/generators/test-generator/utils/data-resolver.ts
+ * so delivery CSV/XLSX values line up with what tests actually ran with.
+ */
+/**
+ * Optional `locale` overrides `process.env.SUNGEN_ENV` — used by the
+ * multi-locale delivery aggregator so each iteration of the loop can load a
+ * specific overlay without mutating the global env. Pass `null` to force
+ * base-only (no overlay merge); leave `undefined` to keep the env-driven
+ * behaviour (default).
  */
-export function loadTestData(testDataFilePath: string): Record<string, string> {
-  if (!fs.existsSync(testDataFilePath)) return {};
-  const content = fs.readFileSync(testDataFilePath, 'utf-8');
-  const parsed = parseYaml(content);
-  if (!parsed || typeof parsed !== 'object') return {};
+export function loadTestData(testDataFilePath: string, locale?: string | null): Record<string, string> {
+  const base = readYamlObject(testDataFilePath);
+  const effectiveLocale = locale !== undefined ? locale : process.env.SUNGEN_ENV;
+  const overlay = effectiveLocale ? readYamlObject(envOverlayPath(testDataFilePath, effectiveLocale)) : null;
+  if (!base && !overlay) return {};
+  // Deep merge so nested namespaces (flow conventions like `kudos.recipient`
+  // / `profile.sent_tab_label`) don't get wiped when the overlay touches the
+  // top-level `kudos:` key. Shallow spread previously replaced the whole
+  // sub-tree, dropping every base key the overlay didn't redeclare.
+  const merged = deepMerge(base ?? {}, overlay ?? {});
 
   const result: Record<string, string> = {};
-  flatten(parsed as Record<string, unknown>, '', result);
+  flatten(merged, '', result);
   return result;
 }
 
+/**
+ * Two-input plain-object deep merge. Overlay wins at every level:
+ *   - Scalar / array / mismatched type → overlay replaces base.
+ *   - Both plain objects → recursive merge.
+ * Pure (no input mutation) so callers can reuse the inputs.
+ */
+function deepMerge(
+  base: Record<string, unknown>,
+  overlay: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, overlayValue] of Object.entries(overlay)) {
+    const baseValue = result[key];
+    if (isPlainObject(baseValue) && isPlainObject(overlayValue)) {
+      result[key] = deepMerge(baseValue as Record<string, unknown>, overlayValue as Record<string, unknown>);
+    } else {
+      result[key] = overlayValue;
+    }
+  }
+  return result;
+}
+
+function isPlainObject(value: unknown): boolean {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readYamlObject(filePath: string): Record<string, unknown> | null {
+  if (!fs.existsSync(filePath)) return null;
+  const parsed = parseYaml(fs.readFileSync(filePath, 'utf-8'));
+  if (!parsed || typeof parsed !== 'object') return null;
+  return parsed as Record<string, unknown>;
+}
+
+function envOverlayPath(basePath: string, env: string): string {
+  const ext = path.extname(basePath);
+  const dir = path.dirname(basePath);
+  const stem = path.basename(basePath, ext);
+  return path.join(dir, `${stem}.${env}${ext}`);
+}
+
 function flatten(obj: Record<string, unknown>, prefix: string, out: Record<string, string>): void {
   for (const [key, value] of Object.entries(obj)) {
     if (value === null || value === undefined) continue;

package/src/exporters/types.ts

@@ -117,6 +117,7 @@ export interface PlaywrightResult {
   startTime?: string;
   error?: string;
   tracePath?: string;
+  projectName?: string;
 }
 
 /**

package/src/exporters/xlsx-exporter.ts

@@ -16,6 +16,7 @@ import JSZip from 'jszip';
 import { ScreenSummary, TestCaseRow } from './types';
 import { getPackageVersion } from './package-info';
 import { SUN_LOGO_PNG_BASE64 } from './sun-logo';
+import { deliverableBasename } from './csv-exporter';
 
 const COL_COUNT = 16;
 const HEADER_FILL = 'FFD9D2E9'; // lavender — matches the summary-header band on row 6
@@ -44,7 +45,55 @@ export function renderXlsx(
   const wb = new ExcelJS.Workbook();
   wb.creator = 'sungen delivery';
   wb.created = new Date();
-  const ws = wb.addWorksheet('Testcases', {
+  addTestcaseSheet(wb, 'Testcases', summary, rows, specLink);
+  return wb;
+}
+
+/**
+ * Render multiple locales into a single workbook with one sheet per locale.
+ *
+ * Triggered automatically by `sungen delivery <screen>` when SUNGEN_ENV is
+ * unset and 2+ `*-test-result.<locale>.json` files are detected for the same
+ * feature basename. Each sheet uses the canonical BM-2-901-13 layout; sheet
+ * names follow `<feature>-<LOCALE>` (uppercased).
+ *
+ * Pass-through: `renderXlsx(summary, rows, specLink)` remains the single-sheet
+ * shortcut used when only one locale exists or when `SUNGEN_ENV` filters to
+ * one.
+ */
+export interface LocaleSheet {
+  sheetName: string;            // e.g. "home-VI" or "home-EN"
+  summary: ScreenSummary;
+  rows: TestCaseRow[];
+  specLink: string;
+}
+
+export function renderXlsxMultiSheet(sheets: LocaleSheet[]): ExcelJS.Workbook {
+  if (sheets.length === 0) {
+    throw new Error('renderXlsxMultiSheet requires at least one locale sheet');
+  }
+  const wb = new ExcelJS.Workbook();
+  wb.creator = 'sungen delivery';
+  wb.created = new Date();
+  for (const s of sheets) {
+    addTestcaseSheet(wb, s.sheetName, s.summary, s.rows, s.specLink);
+  }
+  return wb;
+}
+
+/**
+ * Append one BM-2-901-13 testcase sheet to the given workbook. Sheet content
+ * (layout, summary band, data rows, auto-filter, protection) is identical to
+ * the single-sheet `renderXlsx` output — only the sheet name differs.
+ */
+function addTestcaseSheet(
+  wb: ExcelJS.Workbook,
+  sheetName: string,
+  summary: ScreenSummary,
+  rows: TestCaseRow[],
+  specLink: string,
+): void {
+  const ws = wb.addWorksheet(sheetName, {
     views: [{ state: 'frozen', ySplit: 0, xSplit: 0 }],
   });
 
@@ -359,22 +408,27 @@ export function renderXlsx(
     objects: false,
     scenarios: false,
   };
-
-  return wb;
 }
 
 /**
- * Write the workbook to `qa/deliverables/<screen>-testcases.xlsx`.
- * Directory is created on demand. Returns the absolute output path.
+ * Write the workbook to `qa/deliverables/<screen>-testcases[.env].xlsx`.
+ * When `SUNGEN_ENV` is set, the env name is appended so locale exports don't
+ * overwrite each other. Directory is created on demand.
+ */
+/**
+ * Optional `locale` overrides `process.env.SUNGEN_ENV` for filename suffix —
+ * used by the multi-locale delivery aggregator. Pass `null` / empty string
+ * to force the base (no suffix) variant.
  */
 export async function writeXlsx(
   cwd: string,
   screen: string,
-  wb: ExcelJS.Workbook
+  wb: ExcelJS.Workbook,
+  locale?: string | null,
 ): Promise<string> {
   const outDir = path.join(cwd, 'qa', 'deliverables');
   if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
-  const outPath = path.join(outDir, `${screen}-testcases.xlsx`);
+  const outPath = path.join(outDir, `${deliverableBasename(screen, locale)}.xlsx`);
   const buffer = await wb.xlsx.writeBuffer();
   const locked = await lockEmbeddedImages(Buffer.from(buffer as ArrayBuffer));
   fs.writeFileSync(outPath, locked);

package/src/generators/test-generator/code-generator.ts

@@ -305,6 +305,20 @@ export class CodeGenerator {
       }
     }
 
+    // base.ts now depends on locale-fixture.ts — keep them paired.
+    const localeFixturePath = path.join(outputDir, 'locale-fixture.ts');
+    if (!fs.existsSync(localeFixturePath)) {
+      const templatePath = path.join(templatesRoot, 'specs-locale-fixture.ts');
+      if (fs.existsSync(templatePath)) {
+        const baseDir = path.dirname(localeFixturePath);
+        if (!fs.existsSync(baseDir)) {
+          fs.mkdirSync(baseDir, { recursive: true });
+        }
+        fs.copyFileSync(templatePath, localeFixturePath);
+        console.log('✓ Created: specs/locale-fixture.ts');
+      }
+    }
+
     if (this.options.runtimeData) {
       const testDataPath = path.join(outputDir, 'test-data.ts');
       if (!fs.existsSync(testDataPath)) {