create-procode 0.0.0-stage → 1.1.0

package/src/deps.mjs

@@ -0,0 +1,208 @@
+/**
+ * Dependency set for a generated ProCode app.
+ *
+ * By default the CLI resolves it at scaffold time with resolveDependencySet():
+ * the newest published version of each ProCode package, plus the peers and
+ * bundled packages THOSE versions declare — so an app scaffolded after a
+ * library release gets that release and the peers it was built against, with
+ * no generator update. The constants below are the fallback (--no-latest, or
+ * the registry is unreachable): the set verified against a running ProCode
+ * host app (vsbackoffice / WorksLogicERP, 2026-10-28) at core 2.5.2 /
+ * kendo-widget 3.0.0 / vs-template 2.14.1 / vs-theme 2.6.1 — KendoReact 16.2.0
+ * with kendo-theme-default 14.7.0, and react-router-dom 7.
+ *
+ * Three rules encoded here, each of which is a hard failure if broken:
+ *
+ *  1. React stays on 18. All three runtime libraries declare `react ^18.2.0`
+ *     as a peer; React 19 installs cleanly and then fails at runtime.
+ *  2. `react-redux` stays on 8.x. On 9.x you get two Provider contexts, the
+ *     core's store becomes invisible to your components, and every screen
+ *     renders blank with nothing in the console.
+ *  3. `@progress/kendo-theme-default` is a MISSING peer declaration, not an
+ *     optional extra — the widget library's SCSS imports it by name, so
+ *     leaving it out is a hard build failure on the first `npm run dev`.
+ */
+
+/** The four ProCode packages. */
+export const PROCODE = {
+  "procode-lowcode-core": "^2.7.0",
+  "procode-lowcode-kendo-widget": "^3.2.0",
+  "procode-vs-template": "^2.15.1",
+  "procode-vs-theme": "^2.7.1",
+};
+
+/** Every peer the four packages declare. peerDependenciesMeta is empty on all
+ *  four — nothing here is optional. */
+export const DECLARED_PEERS = {
+  react: "^18.2.0",
+  "react-dom": "^18.2.0",
+  "react-router-dom": "^6.22.3 || ^7.18.0",
+  axios: "^1.6.7",
+  "@progress/kendo-data-query": "^1.7.2",
+  "@progress/kendo-svg-icons": "^4.9.0 || ^5.0.0",
+  "@progress/kendo-react-buttons": "^16.2.0",
+  "@progress/kendo-react-charts": "^16.2.0",
+  "@progress/kendo-react-common": "^16.2.0",
+  "@progress/kendo-react-conversational-ui": "^16.2.0",
+  "@progress/kendo-react-data-tools": "^16.2.0",
+  "@progress/kendo-react-dateinputs": "^16.2.0",
+  "@progress/kendo-react-dialogs": "^16.2.0",
+  "@progress/kendo-react-dropdowns": "^16.2.0",
+  "@progress/kendo-react-editor": "^16.2.0",
+  "@progress/kendo-react-gauges": "^16.2.0",
+  "@progress/kendo-react-grid": "^16.2.0",
+  "@progress/kendo-react-inputs": "^16.2.0",
+  "@progress/kendo-react-intl": "^16.2.0",
+  "@progress/kendo-react-layout": "^16.2.0",
+  "@progress/kendo-react-listview": "^16.2.0",
+  "@progress/kendo-react-popup": "^16.2.0",
+  "@progress/kendo-react-upload": "^16.2.0",
+};
+
+/** Required at runtime or build time, but NOT declared as a peer by anything. */
+export const UNDECLARED_BUT_REQUIRED = {
+  // NOT the KendoReact major: from KendoReact 13 the theme versions apart
+  // (KendoReact 16.2 ships against theme 14.7, and no theme 16 exists).
+  "@progress/kendo-theme-default": "^14.7.0",
+  // A peer of kendo-react-grid 16 that nothing in ProCode declares.
+  "@progress/kendo-csv": "^1.0.0",
+  "@progress/kendo-licensing": "^1.11.3",
+  "@progress/kendo-react-labels": "^16.2.0",
+  "@progress/kendo-intl": "^3.2.1",
+  "react-toastify": "^11.0.5",
+  sass: "^1.38.0",
+};
+
+export const DEV_DEPS = {
+  // vite.config.ts imports node:url.
+  "@types/node": "^24.9.2",
+  "@types/react": "^18.2.43",
+  "@types/react-dom": "^18.2.17",
+  "@vitejs/plugin-react": "^4.2.1",
+  typescript: "^5.2.2",
+  vite: "^5.2.0",
+};
+
+/** `npm test`. vitest 1.x is the line that runs on Vite 5 (DEV_DEPS.vite). */
+export const TEST_DEV_DEPS = {
+  vitest: "^1.6.0",
+};
+
+export const LINT_DEV_DEPS = {
+  eslint: "^8.57.0",
+  "@typescript-eslint/eslint-plugin": "^7.2.0",
+  "@typescript-eslint/parser": "^7.2.0",
+  "eslint-plugin-react-hooks": "^4.6.0",
+  "eslint-plugin-react-refresh": "^0.4.6",
+};
+
+/** Bundled INSIDE the libraries. Listed for documentation only — do not add
+ *  them to a generated package.json, and never bump them independently. */
+export const BUNDLED_DO_NOT_ADD = {
+  "procode-lowcode-core": {
+    "@reduxjs/toolkit": "^1.9.1",
+    "react-redux": "^8.0.5",
+    "redux-saga": "^1.2.3",
+    uuid: "^11.1.1",
+  },
+  "procode-lowcode-kendo-widget": { lodash: "^4.17.21", uuid: "^11.1.1" },
+  "procode-vs-template": {
+    lodash: "^4.17.21",
+    "react-beautiful-dnd": "^13.1.1",
+    uuid: "^11.1.1",
+  },
+  "procode-vs-theme": {},
+};
+
+const sortKeys = (obj) =>
+  Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+
+/** The tested set, used with --no-latest or when the registry is unreachable. */
+export const PINNED_SET = {
+  procode: PROCODE,
+  peers: DECLARED_PEERS,
+  extras: UNDECLARED_BUT_REQUIRED,
+  bundled: BUNDLED_DO_NOT_ADD,
+  source: "pinned",
+};
+
+/** Lowest version a range admits, as [major, minor, patch]; [0,0,0] if none. */
+const floorOf = (range) => (String(range).match(/(\d+)\.(\d+)\.(\d+)/) ?? [0, 0, 0, 0]).slice(1).map(Number);
+const newer = (a, b) => {
+  const [x, y] = [floorOf(a), floorOf(b)];
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i] ? a : b;
+  return a;
+};
+
+/**
+ * Ask the registry for the newest published version of each ProCode package,
+ * and derive everything else from those manifests:
+ *
+ *   peers   every peerDependency the four declare; where two declare the same
+ *           peer, the range with the higher floor wins (vs-template wants
+ *           react-router-dom ^6.22.3 where core wants ^6.6.1).
+ *   extras  required but undeclared. kendo-react-labels follows the
+ *           kendo-react range the widget library declares (KendoReact 16 wants
+ *           exact siblings). kendo-theme-default does NOT: its major stopped
+ *           tracking KendoReact's at 13, so it stays on its tested pin and is
+ *           bumped by hand with the widget library. The rest stay pinned too.
+ *   bundled each package's own dependencies, for the _procodeBundled note.
+ *
+ * Uses the registry npm/npx was invoked with (npm_config_registry), so a
+ * mirror or proxy registry is honoured. Throws on any failure; the caller
+ * falls back to PINNED_SET.
+ */
+export async function resolveDependencySet({ registry, timeoutMs = 10000 } = {}) {
+  const base = String(registry || process.env.npm_config_registry || "https://registry.npmjs.org/").replace(/\/?$/, "/");
+
+  const manifests = await Promise.all(
+    Object.keys(PROCODE).map(async (name) => {
+      const res = await fetch(base + name.replace("/", "%2f") + "/latest", {
+        headers: { accept: "application/json" },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!res.ok) throw new Error(name + ": HTTP " + res.status + " from " + base);
+      const manifest = await res.json();
+      if (typeof manifest?.version !== "string") throw new Error(name + ": no version in the registry response");
+      return manifest;
+    }),
+  );
+
+  const procode = {};
+  const peers = {};
+  const bundled = {};
+  for (const m of manifests) {
+    procode[m.name] = "^" + m.version;
+    bundled[m.name] = m.dependencies ?? {};
+    for (const [peer, range] of Object.entries(m.peerDependencies ?? {})) {
+      peers[peer] = peers[peer] ? newer(peers[peer], range) : range;
+    }
+  }
+
+  const extras = { ...UNDECLARED_BUT_REQUIRED };
+  const kendoReact = Object.entries(peers).find(([n]) => n.startsWith("@progress/kendo-react-"))?.[1];
+  if (kendoReact) {
+    extras["@progress/kendo-react-labels"] = kendoReact;
+  }
+
+  return { procode, peers, extras, bundled, source: "latest" };
+}
+
+/** `set` is PINNED_SET or what resolveDependencySet() returned. */
+export function buildDependencies(set = PINNED_SET) {
+  return sortKeys({ ...set.procode, ...set.peers, ...set.extras });
+}
+
+/**
+ * The React type packages follow the React major the libraries declare, so a
+ * future move off React 18 does not leave @types/react behind.
+ */
+export function buildDevDependencies({ lint = true, tests = true, set = PINNED_SET } = {}) {
+  const devDeps = { ...DEV_DEPS, ...(lint ? LINT_DEV_DEPS : {}), ...(tests ? TEST_DEV_DEPS : {}) };
+  const reactMajor = floorOf(set.peers.react ?? "")[0];
+  if (reactMajor && reactMajor !== floorOf(DEV_DEPS["@types/react"])[0]) {
+    devDeps["@types/react"] = "^" + reactMajor + ".0.0";
+    devDeps["@types/react-dom"] = "^" + reactMajor + ".0.0";
+  }
+  return sortKeys(devDeps);
+}

package/src/log.mjs

@@ -0,0 +1,23 @@
+const useColor =
+  process.env.NO_COLOR === undefined &&
+  process.env.TERM !== "dumb" &&
+  process.stdout.isTTY !== false;
+
+const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+
+export const c = {
+  bold: wrap("1"),
+  dim: wrap("2"),
+  red: wrap("31"),
+  green: wrap("32"),
+  yellow: wrap("33"),
+  blue: wrap("34"),
+  magenta: wrap("35"),
+  cyan: wrap("36"),
+};
+
+export const log = (msg = "") => console.log(msg);
+export const step = (msg) => console.log(`${c.cyan("›")} ${msg}`);
+export const ok = (msg) => console.log(`${c.green("✔")} ${msg}`);
+export const warn = (msg) => console.log(`${c.yellow("!")} ${msg}`);
+export const info = (msg) => console.log(`  ${c.dim(msg)}`);

package/src/multiLanguage.mjs

@@ -0,0 +1,409 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeJson } from "./scaffold.mjs";
+
+/**
+ * Multi-language scaffolding (`--multi-language`, or "yes" to the prompt).
+ *
+ * ProCode multi-language (procode-lowcode-core >= 2.6.0) is switched on by
+ * METADATA: the root screen — the schema `VITE_HEADER_SLUG` names, loaded before
+ * any page — carries `"multiLanguage": { "enabled": true, … }`. Translations are
+ * files fetched at run time from `public/locales/<code>/<namespace>.json`, so a
+ * new language never needs a build. This module writes the smallest app that
+ * uses all of it:
+ *
+ *   src/Module/Header.json          the root screen: the multiLanguage block and
+ *                                   a LANGUAGESELECTOR
+ *   src/multiLanguage/index.ts      the start language (custom logic, Core prop)
+ *   public/locales/<code>/*.json    one folder per language — the four library
+ *                                   namespaces and the app's own `header`
+ *   main.tsx / Module/index.ts /    wired: the Core prop, the `header` slug,
+ *   CustomWidgetFactory.tsx         custom widgets wrapped with the translator
+ *
+ * The libraries ship only their English default text. Hindi and French
+ * translations of that text are bundled here (taken from vsbackoffice); any
+ * other language gets empty library files and shows English until translated.
+ */
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LIBRARY_LOCALES_DIR = path.resolve(__dirname, "..", "templates", "multi-language", "locales");
+
+/** The four library namespaces — translations of the packages' own text. */
+export const LIBRARY_NAMESPACES = ["core", "widget", "kendo", "template"];
+
+/** Names the generator knows; an unknown code is still accepted. */
+const KNOWN = {
+  en: { english: "English", native: "English", short: "EN" },
+  fr: { english: "French", native: "Français", short: "FR" },
+  hi: { english: "Hindi", native: "हिन्दी", short: "हि" },
+  es: { english: "Spanish", native: "Español", short: "ES" },
+  de: { english: "German", native: "Deutsch", short: "DE" },
+  si: { english: "Sinhala", native: "සිංහල", short: "සිං" },
+  ta: { english: "Tamil", native: "தமிழ்", short: "த" },
+  ar: { english: "Arabic", native: "العربية", short: "ع", dir: "rtl" },
+};
+
+/** Each language's name, written in the UI languages the generator has text for. */
+const NAME_IN = {
+  fr: { en: "Anglais", fr: "Français", hi: "Hindi", es: "Espagnol", de: "Allemand", si: "Cingalais", ta: "Tamoul", ar: "Arabe" },
+  hi: { en: "अंग्रेज़ी", fr: "फ़्रेंच", hi: "हिन्दी", es: "स्पेनिश", de: "जर्मन", si: "सिंहली", ta: "तमिल", ar: "अरबी" },
+};
+
+const CODE_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;
+
+/**
+ * "en, fr ,hi" -> ["en", "fr", "hi"]. English always comes first: the libraries'
+ * default text is English, so it is the `defaultLocale` (the language of the
+ * default text) whatever else is offered.
+ */
+export function parseLanguages(input) {
+  const codes = String(input ?? "")
+    .split(/[\s,;]+/)
+    .map((c) => c.trim())
+    .filter(Boolean);
+  const bad = codes.filter((c) => !CODE_RE.test(c));
+  if (bad.length) {
+    throw new Error(
+      `--languages: "${bad.join(", ")}" is not a language code. Use codes like en, fr, hi or pt-BR, separated by commas.`,
+    );
+  }
+  const unique = [...new Set(["en", ...codes])];
+  return unique;
+}
+
+/** Validator for the interactive question. */
+export const languagesProblem = (value) => {
+  try {
+    parseLanguages(value);
+    return null;
+  } catch (err) {
+    return err.message.replace(/^--languages: /, "");
+  }
+};
+
+const englishName = (code) => KNOWN[code]?.english ?? code;
+/** `header.languageFrench` — the extractor's key convention. */
+const labelKey = (code) => "language" + englishName(code).replace(/[^A-Za-z0-9]/g, "").replace(/^./, (ch) => ch.toUpperCase());
+
+/** The root screen. */
+function headerSchema(languages, withSample) {
+  const namespaces = [...LIBRARY_NAMESPACES, "header", ...(withSample ? ["sample"] : [])];
+  return {
+    _readme: [
+      "ROOT SCREEN — the schema VITE_HEADER_SLUG (.env) names. The core loads it before any page,",
+      "so its `multiLanguage` block applies app-wide and no screen renders in the wrong language.",
+      "A screen shows this header when it sets \"enableHeader\": true.",
+      "",
+      "Adding a language: add public/locales/<code>/ (copy en/ and translate) and an entry to",
+      "`locales` below. No build is needed. Moving a screen's text into the files:",
+      "  npx procode-extract-text <namespace> src/Module/<Folder>/<Screen>.json",
+      "then add <namespace> to `resources.namespaces`. README.md, section Multi-language, has the rest.",
+      "Keys beginning with an underscore are comments; the core ignores them.",
+    ],
+    screenName: "",
+    screenId: "header",
+    slug: "header",
+    multiLanguage: {
+      enabled: true,
+      defaultLocale: "en",
+      locales: languages.map((code) => ({
+        code,
+        label: `@t:header.${labelKey(code)}`,
+        nativeLabel: KNOWN[code]?.native ?? code,
+        shortLabel: KNOWN[code]?.short ?? code.toUpperCase(),
+        ...(KNOWN[code]?.dir ? { dir: KNOWN[code].dir } : {}),
+      })),
+      resources: {
+        url: "{base}locales/{locale}/{namespace}.json",
+        namespaces,
+      },
+    },
+    rootScreenElement: {
+      uiElementType: "CONTAINER",
+      role: "prc-container",
+      widgetStyle: { className: "app-header" },
+      children: [
+        {
+          id: "header-language",
+          uiElementType: "WIDGET",
+          widgetType: "LANGUAGESELECTOR",
+          _comment:
+            "The language switch. Its languages are multiLanguage.locales above. segmented = one pill per language (up to 4); menu = a globe button with a panel.",
+          variant: languages.length <= 4 ? "segmented" : "menu",
+          size: "sm",
+        },
+      ],
+    },
+  };
+}
+
+/** `header.json` for one UI language: every offered language's name in it. */
+function headerBundle(uiLanguage, languages) {
+  const bundle = {};
+  for (const code of languages) {
+    bundle[labelKey(code)] =
+      uiLanguage === "en" ? englishName(code) : NAME_IN[uiLanguage]?.[code] ?? KNOWN[code]?.native ?? englishName(code);
+  }
+  return Object.fromEntries(Object.entries(bundle).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+const APP_MULTI_LANGUAGE_TS = `/**
+ * Multi-language in this app is METADATA, not code (procode-lowcode-core 2.6.0+):
+ *
+ *   - src/Module/Header.json (the root screen) switches it on — "multiLanguage.enabled" —
+ *     and lists the languages and where the translation files are;
+ *   - the files are public/locales/<code>/<namespace>.json, fetched at run time. A
+ *     file's keys sit under its name (header.json -> "header.*"); core.json,
+ *     widget.json, kendo.json and template.json translate the libraries' own text,
+ *     which they ship only in English;
+ *   - LANGUAGESELECTOR in Header.json is the switch, and remembers the choice.
+ *
+ * In a schema, any text field may hold a reference: "title": "@t:sample.contacts".
+ * In code: useTranslation().t("ns.key", params) in a component, translate() or
+ * toMessageRef() (a reference to store and show later) elsewhere — all from
+ * "procode-lowcode-core". Never translate a value that is sent to an API or compared.
+ *
+ * Adding a language: add public/locales/<code>/ and the code to Header.json's
+ * "multiLanguage.locales". No build is needed.
+ * Moving a screen's text into the files:
+ *   npx procode-extract-text <namespace> src/Module/<Folder>/<Screen>.json
+ */
+
+/** Where core remembers the chosen language (its default). */
+export const LOCALE_STORAGE_KEY = "procode.locale";
+
+/**
+ * The language to start in when the user has not chosen one — custom logic, run
+ * once at boot (the Core prop \`multiLanguage.initialLocale\` in main.tsx). A choice
+ * made with the LANGUAGESELECTOR is remembered and always wins over this.
+ *
+ * Reads a \`?lang=fr\` link. Extend it with a company or profile setting your
+ * backend returns (session storage, a cookie). Answer undefined to fall through
+ * to the browser's languages, then English.
+ */
+export const initialLocale = (): string | undefined =>
+  new URLSearchParams(window.location.search).get("lang") ?? undefined;
+`;
+
+const README_SECTION = (languages) => `
+## Multi-language
+
+Switched on at scaffold time (\`--multi-language\`), offering **${languages.join(", ")}**.
+
+| What | Where |
+|---|---|
+| Turn it on / off, the languages, the translation files' location | \`src/Module/Header.json\` — the root screen's \`multiLanguage\` block |
+| The language switch | \`LANGUAGESELECTOR\` in \`src/Module/Header.json\` (a screen shows the header with \`"enableHeader": true\`) |
+| Start language (a \`?lang=fr\` link; add a company/profile setting) | \`src/multiLanguage/index.ts\` → \`initialLocale\`, passed to \`<Core>\` in \`main.tsx\` |
+| Translations | \`public/locales/<code>/<namespace>.json\` — fetched at run time, no build |
+| The libraries' own text | \`core\`, \`widget\`, \`kendo\`, \`template\` namespaces — English is built in; Hindi and French are included |
+
+- **In a schema**, any text field may hold a reference: \`"title": "@t:sample.contacts"\`.
+- **Move a screen's text** into the files: \`npx procode-extract-text <namespace> src/Module/<Folder>/<Screen>.json\`,
+  then add \`<namespace>\` to \`resources.namespaces\` and translate \`public/locales/<code>/<namespace>.json\`.
+  Check every language has every key: \`npx procode-extract-text <namespace> --check\`.
+- **In code**: \`useTranslation().t("ns.key", params)\` in a component; \`toMessageRef("ns.key", params)\`
+  for text you store and show later (a validation message, a toast, a value in state); \`translate()\` only
+  at a boundary. All from \`procode-lowcode-core\`. Never translate a value that is sent to an API or compared.
+- **Add a language**: create \`public/locales/<code>/\` (copy \`en/\`, translate) and add it to
+  \`multiLanguage.locales\` in \`Header.json\`.
+`;
+
+/**
+ * Edit a generated file as LF text and write it back with the line endings it
+ * had (the templates may be checked out CRLF). Every edit fails loudly when its
+ * anchor is missing — a silent no-op would ship a half-wired app.
+ */
+function editFile(file, edit) {
+  const raw = fs.readFileSync(file, "utf8");
+  const crlf = raw.includes("\r\n");
+  const next = edit(raw.replace(/\r\n/g, "\n"));
+  fs.writeFileSync(file, crlf ? next.replace(/\n/g, "\r\n") : next, "utf8");
+}
+
+const missing = (file, anchor) =>
+  new Error(`multi-language: could not find "${anchor}" in ${file} — the template changed.`);
+
+/** Insert `addition` after the line that contains `anchor`. */
+function insertAfter(file, anchor, addition) {
+  editFile(file, (text) => {
+    const at = text.indexOf(anchor);
+    if (at === -1) throw missing(file, anchor);
+    const lineEnd = text.indexOf("\n", at);
+    const cut = lineEnd === -1 ? text.length : lineEnd + 1;
+    return text.slice(0, cut) + addition + text.slice(cut);
+  });
+}
+
+function replaceOnce(file, from, to) {
+  editFile(file, (text) => {
+    if (!text.includes(from)) throw missing(file, from);
+    return text.replace(from, to);
+  });
+}
+
+/**
+ * Write and wire everything. `root` is the scaffolded project. Returns the
+ * project-relative files written, and which languages got library translations.
+ */
+export function applyMultiLanguage(root, { languages, withSample }) {
+  const written = [];
+  const rel = (p) => path.relative(root, p).split(path.sep).join("/");
+
+  // ---- the root screen ----------------------------------------------------
+  const headerFile = path.join(root, "src", "Module", "Header.json");
+  writeJson(headerFile, headerSchema(languages, withSample));
+  written.push(rel(headerFile));
+
+  // ---- translation files --------------------------------------------------
+  const translatedLibraries = [];
+  for (const code of languages) {
+    const dir = path.join(root, "public", "locales", code);
+    fs.mkdirSync(dir, { recursive: true });
+    for (const ns of LIBRARY_NAMESPACES) {
+      const bundled = path.join(LIBRARY_LOCALES_DIR, code, `${ns}.json`);
+      const target = path.join(dir, `${ns}.json`);
+      // English: empty — the libraries' English is built in; a key put here
+      // re-words it. Other languages: the bundled translation, or empty.
+      if (code !== "en" && fs.existsSync(bundled)) fs.copyFileSync(bundled, target);
+      else writeJson(target, {});
+      written.push(rel(target));
+    }
+    if (code !== "en" && fs.existsSync(path.join(LIBRARY_LOCALES_DIR, code))) translatedLibraries.push(code);
+    const header = path.join(dir, "header.json");
+    writeJson(header, headerBundle(code, languages));
+    written.push(rel(header));
+  }
+
+  // ---- the app's multi-language module -----------------------------------
+  const mlDir = path.join(root, "src", "multiLanguage");
+  fs.mkdirSync(mlDir, { recursive: true });
+  fs.writeFileSync(path.join(mlDir, "index.ts"), APP_MULTI_LANGUAGE_TS, "utf8");
+  written.push("src/multiLanguage/index.ts");
+
+  // ---- main.tsx: the Core prop -------------------------------------------
+  const main = path.join(root, "src", "main.tsx");
+  insertAfter(main, 'import { APPLICATION_CODE, AuthToken } from "./constant";', 'import { initialLocale } from "./multiLanguage";\n');
+  insertAfter(
+    main,
+    "  NotificationElement: Notification,",
+    [
+      "",
+      "  // Multi-language is switched on by src/Module/Header.json (the root screen's",
+      "  // `multiLanguage` block). This prop holds what metadata cannot: custom logic",
+      "  // for the start language, run once at boot (src/multiLanguage/index.ts).",
+      "  // `resolveInitialLocale` / `onLocaleChange` belong here too, for a language",
+      "  // kept in a user profile.",
+      "  multiLanguage: { initialLocale },",
+      "",
+    ].join("\n"),
+  );
+
+  // ---- the root screen's slug --------------------------------------------
+  const moduleIndex = path.join(root, "src", "Module", "index.ts");
+  const SLUG_FN = /export const getSchemaBySlugService = \((\w+): string, (\w+): string\): any => \{\n/;
+  editFile(moduleIndex, (text) => {
+    if (!SLUG_FN.test(text)) throw missing(moduleIndex, "export const getSchemaBySlugService = (slug: string, …): any => {");
+    return (
+      'import Header from "./Header.json";\n' +
+      text.replace(
+        SLUG_FN,
+        (head, slug) =>
+          head +
+          "  // The root screen (VITE_HEADER_SLUG): loaded before every page, it switches\n" +
+          "  // multi-language on and draws the language selector.\n" +
+          `  if (${slug} === "header") return Header;\n`,
+      )
+    );
+  });
+
+  // ---- custom widgets follow the language --------------------------------
+  const factory = path.join(root, "src", "Factory", "CustomWidgetFactory.tsx");
+  insertAfter(factory, 'import { WidgetTypes } from "../constant";', 'import { withWidgetMultiLanguage } from "procode-lowcode-kendo-widget";\n');
+  replaceOnce(
+    factory,
+    "  private constructor() {\n    this.createWidgetMap();\n  }",
+    [
+      "  private constructor() {",
+      "    this.createWidgetMap();",
+      "    // Each custom widget gets the translator core hands it on kendo-widget's",
+      "    // context, plus Kendo's LocalizationProvider — so a Dropdown or DatePicker",
+      '    // a widget draws itself (from "procode-lowcode-kendo-widget/widgets") shows',
+      "    // its own text and Kendo's in the active language (kendo-widget 3.2.0+).",
+      "    this.widgetMap.forEach((widget, type) =>",
+      "      this.widgetMap.set(type, withWidgetMultiLanguage(widget as any) as React.FC<any>),",
+      "    );",
+      "  }",
+    ].join("\n"),
+  );
+
+  // ---- the sample screen shows the header (and so the switch) ------------
+  if (withSample) {
+    // Its text moves to en/sample.json when procode-extract-text runs (after
+    // install); the other languages start with an empty file to translate.
+    seedSampleBundles(root, languages);
+    replaceOnce(path.join(root, "src", "Module", "Sample", "Contacts.json"), '"enableHeader": false,', '"enableHeader": true,');
+  }
+
+  // ---- header styling -----------------------------------------------------
+  const append = (file, addition) => editFile(file, (text) => text.replace(/\n*$/, "\n") + addition);
+  append(
+    path.join(root, "src", "assets", "styles", "index.scss"),
+    [
+      "",
+      "// The root screen's bar (src/Module/Header.json): the language switch at the right.",
+      ".app-header {",
+      "  display: flex;",
+      "  justify-content: flex-end;",
+      "  align-items: center;",
+      "  padding: 8px 16px;",
+      "}",
+      "",
+    ].join("\n"),
+  );
+
+  // ---- README -------------------------------------------------------------
+  append(path.join(root, "README.md"), README_SECTION(languages));
+
+  return { written, translatedLibraries };
+}
+
+const SAMPLE_TRANSLATIONS_DIR = path.resolve(__dirname, "..", "templates", "multi-language", "sample");
+
+/**
+ * After procode-extract-text has written en/sample.json: give each language the
+ * generator has a translation of the sample screen for (fr, hi) that text,
+ * limited to the keys the extractor produced — a key the screen no longer has
+ * is dropped, and one with no translation shows its English until translated.
+ * Returns the languages filled.
+ */
+export function applySampleTranslations(root, languages) {
+  const enFile = path.join(root, "public", "locales", "en", "sample.json");
+  if (!fs.existsSync(enFile)) return [];
+  const english = JSON.parse(fs.readFileSync(enFile, "utf8"));
+  const keys = Object.keys(english);
+  const filled = [];
+  for (const code of languages) {
+    if (code === "en") continue;
+    const bundled = path.join(SAMPLE_TRANSLATIONS_DIR, `${code}.json`);
+    // A language the generator has no sample translation for starts with the
+    // English text — what the screen would show anyway — so every language has
+    // every key (the translation test checks that) and a translator replaces it.
+    const text = fs.existsSync(bundled) ? JSON.parse(fs.readFileSync(bundled, "utf8")) : {};
+    const out = Object.fromEntries(keys.map((k) => [k, typeof text[k] === "string" ? text[k] : english[k]]));
+    writeJson(path.join(root, "public", "locales", code, "sample.json"), out);
+    if (fs.existsSync(bundled)) filled.push(code);
+  }
+  return filled;
+}
+
+/** A "sample" bundle for each non-English language, so every language folder has every namespace. */
+export function seedSampleBundles(root, languages) {
+  for (const code of languages) {
+    if (code === "en") continue;
+    const file = path.join(root, "public", "locales", code, "sample.json");
+    if (!fs.existsSync(file)) writeJson(file, {});
+  }
+}
+