npm - @verbaly/compiler - Versions diffs - 0.9.0 → 0.10.0 - Mend

@verbaly/compiler 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -22,6 +22,8 @@ npx verbaly extract        # sync catalogs + types
 npx verbaly check          # exit 1 if anything is missing (CI)
 npx verbaly extract --prune  # drop orphaned keys
 npx verbaly translate      # fill missing translations via Claude (or your provider)
+npx verbaly pseudo         # generate a pseudo-locale catalog for i18n QA (en-XA)
+npx verbaly render         # pre-fill data-verbaly HTML per locale (SSG — kills the FOUC)
 ```
 Reads `verbaly.config.{js,mjs,ts,mts,json}` (TS configs need `esbuild` installed). Generates `locales/<locale>.json` (flat, portable — no proprietary format) and `verbaly.d.ts` with params typed per key.
@@ -34,6 +36,14 @@ Reads `verbaly.config.{js,mjs,ts,mts,json}` (TS configs need `esbuild` installed
 translate: { provider: async ({ sourceLocale, targetLocale, messages }) => ({ ...translated }) }
 ```
+## Static rendering (SSG)
+`verbaly render` walks your built site (`dist/` by default, `--site <path>` to change) and pre-fills every `data-verbaly` element **per locale** using the real runtime — plurals, `Intl` formatting, `data-verbaly-args`, attribute translation and `data-verbaly-rich` (same whitelist, XSS-safe). The source locale is filled in place; every other locale is mirrored to `dist/<locale>/…` with `<html lang>` set. Static HTML ships already translated — **no flash of untranslated content** — and the runtime attributes stay put, so client-side locale switching keeps working.
+## Pseudo-localization
+`verbaly pseudo` fills a QA catalog (`en-XA` by default, `--locale <id>` to change) from the source: accented letters, `⟦…⟧` markers and ~33% length padding reveal hardcoded strings, clipped layouts and concatenation bugs. Params, variant blocks and tags survive verbatim — the same structural validation as `translate`.
 📖 Docs: **https://verbaly-web.vercel.app/docs/cli**
 > ⚠️ Early development (`0.x`) — API not stable yet.

package/dist/cli.js CHANGED Viewed

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // src/cli.ts
-import { parseArgs } from "util";
+import { parseArgs as parseArgs2 } from "util";
 // src/catalog.ts
 import { mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -580,6 +580,339 @@ function pruneCatalogs(cfg, catalogs, registry) {
   return removed;
 }
+// src/pseudo.ts
+var PSEUDO_LOCALE = "en-XA";
+var ACCENTS = {
+  a: "\xE1",
+  b: "\u0180",
+  c: "\xE7",
+  d: "\u0111",
+  e: "\xE9",
+  f: "\u0192",
+  g: "\u011F",
+  h: "\u0125",
+  i: "\xED",
+  j: "\u0135",
+  k: "\u0137",
+  l: "\u013A",
+  m: "\u0271",
+  n: "\xF1",
+  o: "\xF3",
+  p: "\xFE",
+  q: "\u01EB",
+  r: "\u0155",
+  s: "\u0161",
+  t: "\u0163",
+  u: "\xFA",
+  v: "\u1E7D",
+  w: "\u0175",
+  x: "\u1E8B",
+  y: "\xFD",
+  z: "\u017E",
+  A: "\xC1",
+  B: "\u0181",
+  C: "\xC7",
+  D: "\u0110",
+  E: "\xC9",
+  F: "\u0191",
+  G: "\u011E",
+  H: "\u0124",
+  I: "\xCD",
+  J: "\u0134",
+  K: "\u0136",
+  L: "\u0139",
+  M: "\u1E3E",
+  N: "\xD1",
+  O: "\xD3",
+  P: "\xDE",
+  Q: "\u01EA",
+  R: "\u0154",
+  S: "\u0160",
+  T: "\u0162",
+  U: "\xDA",
+  V: "\u1E7C",
+  W: "\u0174",
+  X: "\u1E8C",
+  Y: "\xDD",
+  Z: "\u017D"
+};
+var TAG_AT = /<\/?[a-zA-Z][\w-]*\/?>/y;
+function pseudoLocalize(message) {
+  let out = "";
+  let letters = 0;
+  let i = 0;
+  while (i < message.length) {
+    const two = message.slice(i, i + 2);
+    if (two === "{{" || two === "}}" || two === "||" || two === "##") {
+      out += two;
+      i += 2;
+      continue;
+    }
+    const ch = message[i];
+    if (ch === "{") {
+      const end = matchBrace(message, i);
+      out += message.slice(i, end);
+      i = end;
+      continue;
+    }
+    if (ch === "<") {
+      TAG_AT.lastIndex = i;
+      const m = TAG_AT.exec(message);
+      if (m) {
+        out += m[0];
+        i += m[0].length;
+        continue;
+      }
+    }
+    const mapped = ACCENTS[ch];
+    if (mapped) {
+      out += mapped;
+      letters += 1;
+    } else {
+      out += ch;
+    }
+    i += 1;
+  }
+  const pad = "~".repeat(Math.ceil(letters / 3));
+  return `\u27E6${out}${pad ? " " + pad : ""}\u27E7`;
+}
+function matchBrace(message, start) {
+  let depth = 0;
+  for (let i = start; i < message.length; i++) {
+    const two = message.slice(i, i + 2);
+    if (two === "{{" || two === "}}") {
+      i += 1;
+      continue;
+    }
+    const ch = message[i];
+    if (ch === "{") depth += 1;
+    else if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) return i + 1;
+    }
+  }
+  return message.length;
+}
+function pseudoCatalogs(cfg, catalogs, locale = PSEUDO_LOCALE) {
+  const source = catalogs[cfg.sourceLocale] ?? {};
+  const target = {};
+  for (const [key, msg] of Object.entries(source)) {
+    target[key] = msg ? pseudoLocalize(msg) : "";
+  }
+  catalogs[locale] = target;
+  return Object.keys(target).filter((key) => target[key]);
+}
+// src/render.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { dirname, join as join4, relative } from "path";
+import MagicString from "magic-string";
+import { glob as glob2 } from "tinyglobby";
+import { createVerbaly, parseTags, RICH_TAGS } from "verbaly";
+var VOID_TAGS = /* @__PURE__ */ new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+var START_TAG = /<([a-zA-Z][a-zA-Z0-9-]*)((?:"[^"]*"|'[^']*'|[^"'>])*)>/g;
+var ATTR = /([^\s=/"'<>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+function renderHtml(html, options) {
+  const attr = options.attribute ?? "data-verbaly";
+  const argsAttr = `${attr}-args`;
+  const attrsAttr = `${attr}-attr`;
+  const richAttr = `${attr}-rich`;
+  const richTags = new Set(options.richTags ?? RICH_TAGS);
+  const sourceLocale = options.sourceLocale ?? "en";
+  const messages = {};
+  for (const [locale, catalog] of Object.entries(options.catalogs)) {
+    const clean = {};
+    for (const [key, msg] of Object.entries(catalog)) if (msg) clean[key] = msg;
+    messages[locale] = clean;
+  }
+  const v = createVerbaly({ locale: options.locale, fallback: sourceLocale, messages });
+  const t = v.t;
+  const ms = new MagicString(html);
+  const missing = /* @__PURE__ */ new Set();
+  const skip = protectedRanges(html);
+  const inSkip = (index) => skip.some(([from, to]) => index >= from && index < to);
+  START_TAG.lastIndex = 0;
+  let m;
+  while ((m = START_TAG.exec(html)) !== null) {
+    if (inSkip(m.index)) continue;
+    const [full, rawName, attrChunk] = m;
+    const tagName = rawName.toLowerCase();
+    const openEnd = m.index + full.length;
+    const chunkStart = m.index + 1 + rawName.length;
+    if (tagName === "html" && options.setLang !== false) {
+      setAttribute(ms, html, chunkStart, openEnd, attrChunk, "lang", options.locale);
+      continue;
+    }
+    const attrs = parseAttrs(attrChunk);
+    const key = attrs.get(attr);
+    const attrMapRaw = attrs.get(attrsAttr);
+    if (key === void 0 && attrMapRaw === void 0) continue;
+    const args = parseArgs(attrs.get(argsAttr));
+    if (key) {
+      if (!v.has(key)) {
+        missing.add(key);
+      } else if (!VOID_TAGS.has(tagName) && !attrChunk.trimEnd().endsWith("/")) {
+        const close = findClose(html, tagName, openEnd, inSkip);
+        if (close) {
+          const text = t(key, args);
+          const content = attrs.has(richAttr) ? richToHtml(parseTags(text), richTags) : escapeHtml(text);
+          if (html.slice(openEnd, close.contentEnd) !== content) {
+            if (openEnd === close.contentEnd) ms.appendLeft(openEnd, content);
+            else ms.overwrite(openEnd, close.contentEnd, content);
+          }
+        }
+      }
+    }
+    if (attrMapRaw !== void 0) {
+      const map = parseArgs(attrMapRaw);
+      if (map) {
+        for (const [name, attrKey] of Object.entries(map)) {
+          if (typeof attrKey !== "string" || name.toLowerCase().startsWith("on")) continue;
+          if (!v.has(attrKey)) {
+            missing.add(attrKey);
+            continue;
+          }
+          setAttribute(ms, html, chunkStart, openEnd, attrChunk, name, t(attrKey, args));
+        }
+      }
+    }
+  }
+  return { html: ms.toString(), missing: [...missing] };
+}
+async function renderSite(cfg, options = {}) {
+  const site = join4(cfg.root, options.site ?? "dist");
+  const locales = options.locales ?? cfg.locales;
+  const catalogs = loadCatalogs(cfg);
+  const files = await glob2("**/*.html", {
+    cwd: site,
+    absolute: true,
+    ignore: locales.map((locale) => `${locale}/**`)
+  });
+  const missing = {};
+  for (const file of files) {
+    const html = readFileSync4(file, "utf8");
+    const rel = relative(site, file);
+    for (const locale of locales) {
+      const result = renderHtml(html, {
+        locale,
+        catalogs,
+        sourceLocale: cfg.sourceLocale,
+        attribute: options.attribute,
+        richTags: options.richTags
+      });
+      for (const key of result.missing) {
+        const list = missing[locale] ??= [];
+        if (!list.includes(key)) list.push(key);
+      }
+      const out = locale === cfg.sourceLocale ? file : join4(site, locale, rel);
+      mkdirSync2(dirname(out), { recursive: true });
+      writeFileSync3(out, result.html);
+    }
+  }
+  return { files: files.length, locales: [...locales], missing };
+}
+function parseAttrs(chunk) {
+  const attrs = /* @__PURE__ */ new Map();
+  ATTR.lastIndex = 0;
+  let m;
+  while ((m = ATTR.exec(chunk)) !== null) {
+    attrs.set(m[1].toLowerCase(), m[2] ?? m[3] ?? m[4] ?? "");
+  }
+  return attrs;
+}
+function parseArgs(raw) {
+  if (!raw) return void 0;
+  try {
+    return JSON.parse(decodeEntities(raw));
+  } catch {
+    console.warn(`[verbaly] invalid args JSON: ${raw}`);
+    return void 0;
+  }
+}
+function protectedRanges(html) {
+  const ranges = [];
+  const re = /<!--[\s\S]*?-->|<script\b[\s\S]*?<\/script\s*>|<style\b[\s\S]*?<\/style\s*>/gi;
+  let m;
+  while ((m = re.exec(html)) !== null) {
+    const openEnd = m[0].startsWith("<!--") ? m.index : html.indexOf(">", m.index) + 1;
+    ranges.push([openEnd, m.index + m[0].length]);
+  }
+  return ranges;
+}
+function findClose(html, tagName, from, inSkip) {
+  const re = new RegExp(
+    `<${tagName}(?=[\\s/>])(?:"[^"]*"|'[^']*'|[^"'>])*>|</${tagName}\\s*>`,
+    "gi"
+  );
+  re.lastIndex = from;
+  let depth = 1;
+  let m;
+  while ((m = re.exec(html)) !== null) {
+    if (inSkip(m.index)) continue;
+    if (m[0][1] === "/") {
+      depth -= 1;
+      if (depth === 0) return { contentEnd: m.index };
+    } else if (!m[0].endsWith("/>")) {
+      depth += 1;
+    }
+  }
+  return null;
+}
+function setAttribute(ms, html, chunkStart, openEnd, attrChunk, name, value) {
+  const escaped = escapeAttr(value);
+  const existing = new RegExp(`(\\s${name}\\s*=\\s*)("[^"]*"|'[^']*'|[^\\s>]+)`, "i").exec(
+    attrChunk
+  );
+  if (existing) {
+    const valueStart = chunkStart + existing.index + existing[1].length;
+    const valueEnd = valueStart + existing[2].length;
+    if (html.slice(valueStart, valueEnd) !== `"${escaped}"`) {
+      ms.overwrite(valueStart, valueEnd, `"${escaped}"`);
+    }
+    return;
+  }
+  const selfClosing = html.slice(openEnd - 2, openEnd) === "/>";
+  const insertAt = openEnd - (selfClosing ? 2 : 1);
+  ms.appendLeft(insertAt, ` ${name}="${escaped}"`);
+}
+function richToHtml(nodes, allowed) {
+  let out = "";
+  for (const node of nodes) {
+    if (typeof node === "string") {
+      out += escapeHtml(node);
+    } else if (allowed.has(node.name)) {
+      out += `<${node.name}>${richToHtml(node.children, allowed)}</${node.name}>`;
+    } else {
+      out += richToHtml(node.children, allowed);
+    }
+  }
+  return out;
+}
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttr(text) {
+  return escapeHtml(text).replace(/"/g, "&quot;");
+}
+function decodeEntities(text) {
+  return text.replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
 // src/translate.ts
 async function translateCatalogs(cfg, catalogs, provider, options = {}) {
   const batchSize = options.batchSize ?? 20;
@@ -646,6 +979,8 @@ Usage:
   verbaly extract    scan sources, update catalogs and types
   verbaly check      verify translations are complete (CI)
   verbaly translate  fill missing translations via a provider (default: claude)
+  verbaly pseudo     generate a pseudo-locale catalog for i18n QA (default: en-XA)
+  verbaly render     pre-fill data-verbaly HTML per locale (SSG, kills the FOUC)
 Options:
   --root <path>      project root (default: cwd)
@@ -655,12 +990,14 @@ Options:
   --prune            drop keys no longer referenced (extract)
   --model <id>       model override for the claude provider (translate)
   --dry-run          list what would be translated, write nothing (translate)
+  --locale <id>      pseudo-locale id (pseudo, default: en-XA)
+  --site <path>      built site directory (render, default: dist)
 Config file: verbaly.config.{js,mjs,ts,mts,json} at root (flags win).
 The claude provider needs @anthropic-ai/sdk installed and ANTHROPIC_API_KEY set.
 `;
 async function main() {
-  const { positionals, values } = parseArgs({
+  const { positionals, values } = parseArgs2({
     allowPositionals: true,
     options: {
       root: { type: "string" },
@@ -669,6 +1006,8 @@ async function main() {
       locales: { type: "string" },
       prune: { type: "boolean" },
       model: { type: "string" },
+      locale: { type: "string" },
+      site: { type: "string" },
       "dry-run": { type: "boolean" },
       help: { type: "boolean", short: "h" }
     }
@@ -750,6 +1089,27 @@ ${formatCheckResult(result)}`);
     }
     return;
   }
+  if (command === "render") {
+    const result = await renderSite(cfg, {
+      site: values.site,
+      locales: values.locales?.split(",")
+    });
+    console.log(
+      `[verbaly] ${result.files} pages \xD7 ${result.locales.length} locales (${result.locales.join(", ")})`
+    );
+    for (const [locale, keys] of Object.entries(result.missing)) {
+      console.warn(`  ${locale}: ${keys.length} keys not pre-filled \u2014 ${keys.join(", ")}`);
+    }
+    return;
+  }
+  if (command === "pseudo") {
+    const catalogs = loadCatalogs(cfg);
+    const locale = values.locale ?? PSEUDO_LOCALE;
+    const keys = pseudoCatalogs(cfg, catalogs, locale);
+    writeCatalog(cfg, locale, catalogs[locale] ?? {});
+    console.log(`[verbaly] ${keys.length} messages pseudo-localized \u2192 ${locale}`);
+    return;
+  }
   console.error(`[verbaly] unknown command "${command}"
 ${HELP}`);
   process.exitCode = 1;