create-procode 1.0.0 → 1.1.0

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, {});
+  }
+}
+

package/templates/base/README.md.tmpl

@@ -35,7 +35,9 @@ the `KENDO_UI_LICENSE` environment variable in CI. Then run `npm install`, or
 1. Point `VITE_CENTRAL_SERVICE_BASE_URL` in `.env` at your environment.
 2. Copy `.env.local.example` to `.env.local` and put a dev token in
    `VITE_HARDCODED_TOKEN` — or sign in so the `AuthToken` cookie is set.
-   **`.env.local` is gitignored. Never commit a token to `.env`.**
+   **`.env.local` is gitignored. Never commit a token to `.env`.** `npm run build`
+   refuses to run while `VITE_HARDCODED_TOKEN` is set, so a personal token cannot
+   be compiled into `dist/` (a built app authenticates from the cookie).
 3. Follow the `_readme` at the top of `src/Module/Sample/Contacts.json`: add an
    `apiConfig`, bind `LOAD_SCREEN_DATA`, and swap the `CUS_SAMPLE_*` stand-ins for
    `DELETE_ASYNC` / `UPDATE_ASYNC` / `FORMSUBMIT_CREATE_ASYNC`.
@@ -45,9 +47,9 @@ the `KENDO_UI_LICENSE` environment variable in CI. Then run `npm install`, or
 | Script | What it does |
 |---|---|
 | `npm run dev` | Vite dev server on port 5173 |
-| `npm run build` | `tsc` then `vite build` |
+| `npm run build` | `tsc` then `vite build` — refused while `VITE_HARDCODED_TOKEN` is set |
 | `npm run preview` | Serve the built bundle |
-| `npm run lint` | ESLint over `src/` |
+| `npm run lint` | ESLint over `src/` |__TEST_SCRIPT_ROW__
 
 ## Layout