@verbaly/compiler 0.22.0 → 0.23.0

package/README.md

@@ -11,9 +11,9 @@
 
 ---
 
-The compiler behind [Verbaly](https://github.com/AronSoto/verbaly): AST extraction of `t\`...\``**and JSX`<Trans>` children** into stable hashed keys — or **readable keys** via `` t.id('inbox.title')`…` `` and `<Trans id="inbox.title">…</Trans>` — flat JSON catalog sync, and typed codegen. It also ships the **`verbaly` CLI**. Extraction covers `.js/.ts/.jsx/.tsx` **and `.svelte`/`.vue` single-file components** (script blocks and markup, including Svelte's `$t` store form).
+The compiler behind [Verbaly](https://github.com/AronSoto/verbaly): AST extraction of `t\`...\``**and JSX`<Trans>` children** into stable hashed keys (or **readable keys** via `` t.id('inbox.title')`…` `` and `<Trans id="inbox.title">…</Trans>`), flat JSON catalog sync, and typed codegen. It also ships the **`verbaly` CLI**. Extraction covers `.js/.ts/.jsx/.tsx` **and `.svelte`/`.vue` single-file components** (script blocks and markup, including Svelte's `$t` store form).
 
-> Most projects don't install this directly — [`@verbaly/vite`](https://www.npmjs.com/package/@verbaly/vite) wraps it with zero config. Reach for it when scripting extraction/checks yourself.
+> Most projects don't install this directly: [`@verbaly/vite`](https://www.npmjs.com/package/@verbaly/vite) wraps it with zero config. Reach for it when scripting extraction/checks yourself.
 
 ## 🧰 CLI
 
@@ -21,20 +21,22 @@ The compiler behind [Verbaly](https://github.com/AronSoto/verbaly): AST extracti
 npx verbaly init           # scaffold config + locale catalogs (detects your bundler)
 npx verbaly doctor         # diagnose the setup (config, catalogs, plugin, types, keys)
 npx verbaly extract        # sync catalogs + types
-npx verbaly check          # exit 1 if anything is missing (CI)
+npx verbaly extract --watch  # keep extracting as you code (dev loop)
 npx verbaly extract --prune  # drop orphaned keys
+npx verbaly status         # translation coverage per locale, at a glance
+npx verbaly check          # exit 1 if anything is missing (CI)
 npx verbaly translate      # fill missing translations via Claude (or your provider)
 npx verbaly export         # translator files (XLIFF 2.0, CSV) or mobile resources (Android, iOS)
 npx verbaly import <files> # fill catalogs back from translated XLIFF/CSV files
 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)
+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.
+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.
 
 ## 🤖 Machine translation
 
-`verbaly translate` fills the `""` holes `check` reports. The default provider uses Claude via the official SDK — install it as a dev dependency (translation is a build-time step, not an app runtime dependency): `pnpm add -D @anthropic-ai/sdk` (or `npm i -D`), plus `ANTHROPIC_API_KEY`. Default model is `claude-sonnet-5` (balanced quality/cost); override with `translate.model` in config or `--model <id>`. Placeholders, variants and tags are validated after translation — anything not preserved verbatim stays `""` so `check` keeps failing. Plug your own provider in `verbaly.config.ts`:
+`verbaly translate` fills the `""` holes `check` reports. The default provider uses Claude via the official SDK; install it as a dev dependency (translation is a build-time step, not an app runtime dependency): `pnpm add -D @anthropic-ai/sdk` (or `npm i -D`), plus `ANTHROPIC_API_KEY`. Default model is `claude-sonnet-5` (balanced quality/cost); override with `translate.model` in config or `--model <id>`. Placeholders, variants and tags are validated after translation: anything not preserved verbatim stays `""` so `check` keeps failing. Plug your own provider in `verbaly.config.ts`:
 
 ```ts
 translate: {
@@ -44,7 +46,7 @@ translate: {
 
 ## 🌍 Human translators & TMS
 
-Catalogs are **flat JSON** — most TMS platforms (Crowdin, Lokalise, Phrase, …) ingest them natively; point the platform at `locales/` and you're done. For everything else there's a built-in round-trip:
+Catalogs are **flat JSON**: most TMS platforms (Crowdin, Lokalise, Phrase, …) ingest them natively; point the platform at `locales/` and you're done. For everything else there's a built-in round-trip:
 
 ```bash
 npx verbaly export                    # verbaly-export/<locale>.xlf (XLIFF 2.0, source + target per unit)
@@ -52,7 +54,7 @@ npx verbaly export --format csv       # spreadsheet-friendly: key,source,target
 npx verbaly import verbaly-export/es.xlf   # fill the catalog back
 ```
 
-`export` writes one file per target locale with the source text alongside the current translation (`--missing` exports only the untranslated entries). `import` reads XLIFF 2.0/1.2 or CSV back and **validates every entry like `translate` does** — a translation that drops a `{param}`, a variant block or an `<em>` tag is rejected and reported, so a translator's typo can't break your UI. Existing translations are kept unless `--overwrite`; `--dry-run` previews everything.
+`export` writes one file per target locale with the source text alongside the current translation (`--missing` exports only the untranslated entries). `import` reads XLIFF 2.0/1.2 or CSV back and **validates every entry like `translate` does**: a translation that drops a `{param}`, a variant block or an `<em>` tag is rejected and reported, so a translator's typo can't break your UI. Existing translations are kept unless `--overwrite`; `--dry-run` previews everything.
 
 ## 📱 Mobile resources
 
@@ -67,9 +69,9 @@ Your source locale becomes the platform default (`values/strings.xml`, `en.lproj
 
 ## 📄 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.
+`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.
 
-Named links in rich messages render as real `<a>` elements — hrefs come from config or markup, never from messages (`javascript:` blocked):
+Named links in rich messages render as real `<a>` elements; hrefs come from config or markup, never from messages (`javascript:` blocked):
 
 ```ts
 // verbaly.config.ts
@@ -78,15 +80,15 @@ render: { links: { docs: { href: '/docs', target: '_blank', rel: 'noopener' } }
 
 Per-element `data-verbaly-links='{"repo":"https://…"}'` merges over the config map.
 
-**Multi-locale SEO** — set `render.baseUrl` (or `--base-url`) and every page gets reciprocal `<link rel="alternate" hreflang>` (plus `x-default`) for the whole locale set; `--sitemap` writes a locale-aware `sitemap-i18n.xml`. `--clean` drops stale `dist/<locale>/` pages before mirroring. Injection is idempotent.
+**Multi-locale SEO**: set `render.baseUrl` (or `--base-url`) and every page gets reciprocal `<link rel="alternate" hreflang>` (plus `x-default`) for the whole locale set; `--sitemap` writes a locale-aware `sitemap-i18n.xml`. `--clean` drops stale `dist/<locale>/` pages before mirroring. Injection is idempotent.
 
 ## 🔍 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`.
+`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, with the same structural validation as `translate`.
 
 📖 Docs: **https://verbaly-web.vercel.app/docs/cli**
 
-> ⚠️ Early development (`0.x`) — API not stable yet.
+> ⚠️ Early development (`0.x`): API not stable yet.
 
 ## License
 

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, watch, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { RICH_TAGS, createVerbaly, parse, parseTags, safeHref } from "verbaly";
 import { pathToFileURL } from "node:url";
@@ -40,8 +40,13 @@ function serializeCatalog(catalog) {
 }
 function writeCatalog(cfg, locale, catalog) {
 	const serialized = serializeCatalog(catalog);
-	mkdirSync(cfg.dir, { recursive: true });
-	writeFileSync(catalogPath(cfg, locale), serialized);
+	const path = catalogPath(cfg, locale);
+	try {
+		if (readFileSync(path, "utf8") === serialized) return serialized;
+	} catch {
+		mkdirSync(cfg.dir, { recursive: true });
+	}
+	writeFileSync(path, serialized);
 	return serialized;
 }
 //#endregion
@@ -143,8 +148,6 @@ function renderParamType(types) {
 	]) members.add(m);
 	return [...members].join(" | ");
 }
-//#endregion
-//#region src/codegen.ts
 function generateDts(catalog) {
 	const lines = [];
 	for (const [key, message] of Object.entries(catalog).sort(([a], [b]) => a.localeCompare(b))) {
@@ -1592,6 +1595,83 @@ function decodeEntities(text) {
 	return text.replace(/&quot;/g, "\"").replace(/&#39;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
 }
 //#endregion
+//#region src/status.ts
+function status(cfg, catalogs, registry) {
+	const source = catalogs[cfg.sourceLocale] ?? {};
+	const needed = /* @__PURE__ */ new Set([...registry.messages().keys(), ...Object.keys(source)]);
+	const locales = [];
+	for (const locale of cfg.locales) {
+		if (locale === cfg.sourceLocale) continue;
+		let translated = 0;
+		for (const key of needed) if (catalogs[locale]?.[key]) translated += 1;
+		locales.push({
+			locale,
+			translated,
+			total: needed.size
+		});
+	}
+	return {
+		messages: needed.size,
+		source: cfg.sourceLocale,
+		locales
+	};
+}
+function formatStatusResult(result) {
+	const lines = [`[verbaly] ${result.messages} messages · source: ${result.source}`];
+	if (result.locales.length === 0) {
+		lines.push("  no target locales (add locales to your config)");
+		return lines.join("\n");
+	}
+	for (const { locale, translated, total } of result.locales) {
+		const pct = total === 0 ? 100 : Math.floor(translated / total * 100);
+		const mark = translated === total ? " ✓" : "";
+		lines.push(`  ${locale}: ${translated}/${total} translated (${pct}%)${mark}`);
+	}
+	return lines.join("\n");
+}
+const SOURCE_FILE_RE = /\.(?:[cm]?[jt]sx?|svelte|vue)$/;
+//#endregion
+//#region src/watch.ts
+function watchProject(cfg, run, options = {}) {
+	const catalogDir = relative(cfg.root, cfg.dir).replaceAll("\\", "/");
+	let timer;
+	let running = false;
+	let queued = false;
+	async function refresh() {
+		if (running) {
+			queued = true;
+			return;
+		}
+		running = true;
+		try {
+			await run();
+		} catch (error) {
+			console.warn("[verbaly] watch run failed:", error);
+		} finally {
+			running = false;
+			if (queued) {
+				queued = false;
+				schedule();
+			}
+		}
+	}
+	function schedule() {
+		clearTimeout(timer);
+		timer = setTimeout(() => void refresh(), options.debounce ?? 150);
+	}
+	const watcher = watch(cfg.root, { recursive: true }, (_event, filename) => {
+		if (!filename) return;
+		const file = filename.replaceAll("\\", "/");
+		if (file.includes("node_modules/") || file.endsWith(".d.ts")) return;
+		if (catalogDir && file.startsWith(`${catalogDir}/`)) return;
+		if (SOURCE_FILE_RE.test(file)) schedule();
+	});
+	return () => {
+		clearTimeout(timer);
+		watcher.close();
+	};
+}
+//#endregion
 //#region src/run.ts
 const HELP = `verbaly · i18n compiler
 
@@ -1599,6 +1679,7 @@ Usage:
   verbaly init       scaffold config + locale catalogs (detects your bundler)
   verbaly doctor     diagnose the setup (config, catalogs, plugin, types, keys)
   verbaly extract    scan sources, update catalogs and types
+  verbaly status     translation coverage per locale, at a glance
   verbaly check      verify translations are complete (CI)
   verbaly translate  fill missing translations via a provider (default: claude)
   verbaly export     write translator files (XLIFF 2.0, CSV) or mobile resources (Android, iOS)
@@ -1612,6 +1693,7 @@ Options:
   --source <locale>  source locale (default: en)
   --locales <csv>    extra locales; for translate: target locales to fill
   --prune            drop keys no longer referenced (extract)
+  --watch            keep extracting as source files change (extract)
   --model <id>       model override for the claude provider (translate)
   --dry-run          list what would happen, write nothing (translate, import, extract)
   --format <f>       export format: xliff (default), csv, android-xml or ios-strings (export)
@@ -1638,6 +1720,7 @@ async function runCli(args = process.argv.slice(2)) {
 			source: { type: "string" },
 			locales: { type: "string" },
 			prune: { type: "boolean" },
+			watch: { type: "boolean" },
 			model: { type: "string" },
 			locale: { type: "string" },
 			site: { type: "string" },
@@ -1705,20 +1788,37 @@ async function runCli(args = process.argv.slice(2)) {
 	}
 	if (command === "extract") {
 		const dryRun = values["dry-run"];
-		const registry = await extractProject(cfg);
-		const catalogs = loadCatalogs(cfg);
-		if (values.prune) {
-			const removed = pruneCatalogs(cfg, catalogs, registry);
-			for (const [locale, keys] of Object.entries(removed)) console.log(dryRun ? `  ${locale}: would prune ${keys.length}: ${keys.join(", ")}` : `  ${locale}: -${keys.length} pruned`);
+		if (values.watch && (dryRun || values.prune)) {
+			console.error("[verbaly] --watch runs alone: prune is a deliberate one-shot action and dry-run writes nothing");
+			process.exitCode = 1;
+			return;
+		}
+		async function runExtract() {
+			const registry = await extractProject(cfg);
+			const catalogs = loadCatalogs(cfg);
+			if (values.prune) {
+				const removed = pruneCatalogs(cfg, catalogs, registry);
+				for (const [locale, keys] of Object.entries(removed)) console.log(dryRun ? `  ${locale}: would prune ${keys.length}: ${keys.join(", ")}` : `  ${locale}: -${keys.length} pruned`);
+			}
+			const { added } = syncCatalogs(cfg, catalogs, registry);
+			if (!dryRun) {
+				for (const locale of cfg.locales) writeCatalog(cfg, locale, catalogs[locale] ?? {});
+				writeDts(cfg, catalogs[cfg.sourceLocale] ?? {});
+			}
+			const total = registry.messages().size;
+			console.log(`[verbaly] ${total} messages · locales: ${cfg.locales.join(", ")}${dryRun ? " (dry run, nothing written)" : ""}`);
+			for (const [locale, keys] of Object.entries(added)) console.log(`  ${locale}: ${dryRun ? `would add ${keys.length}` : `+${keys.length}`}`);
 		}
-		const { added } = syncCatalogs(cfg, catalogs, registry);
-		if (!dryRun) {
-			for (const locale of cfg.locales) writeCatalog(cfg, locale, catalogs[locale] ?? {});
-			writeDts(cfg, catalogs[cfg.sourceLocale] ?? {});
+		await runExtract();
+		if (values.watch) {
+			watchProject(cfg, runExtract);
+			console.log("[verbaly] watching for source changes (ctrl+c to stop)");
 		}
-		const total = registry.messages().size;
-		console.log(`[verbaly] ${total} messages · locales: ${cfg.locales.join(", ")}${dryRun ? " (dry run, nothing written)" : ""}`);
-		for (const [locale, keys] of Object.entries(added)) console.log(`  ${locale}: ${dryRun ? `would add ${keys.length}` : `+${keys.length}`}`);
+		return;
+	}
+	if (command === "status") {
+		const registry = await extractProject(cfg);
+		console.log(formatStatusResult(status(cfg, loadCatalogs(cfg), registry)));
 		return;
 	}
 	if (command === "check") {
@@ -1846,7 +1946,12 @@ const COMMON_FLAGS = /* @__PURE__ */ new Set([
 const COMMAND_FLAGS = {
 	init: [],
 	doctor: [],
-	extract: ["prune", "dry-run"],
+	extract: [
+		"prune",
+		"dry-run",
+		"watch"
+	],
+	status: [],
 	check: [],
 	translate: ["model", "dry-run"],
 	export: [