@verbaly/compiler 0.25.0 → 0.27.0

package/dist/cli.js

@@ -8,6 +8,7 @@ import { glob } from "tinyglobby";
 import { parse as parse$1 } from "@babel/parser";
 import { createHash } from "node:crypto";
 import MagicString from "magic-string";
+import "picomatch";
 //#region src/catalog.ts
 function catalogPath(cfg, locale) {
 	return join(cfg.dir, `${locale}.json`);
@@ -98,6 +99,57 @@ function formatCheckResult(result) {
 function truncate(text, max) {
 	return text.length > max ? text.slice(0, max - 1) + "…" : text;
 }
+function githubCheckAnnotations(result, registry, root) {
+	const messages = registry.messages();
+	const contents = /* @__PURE__ */ new Map();
+	const readSource = (file) => {
+		if (!contents.has(file)) try {
+			contents.set(file, readFileSync(file, "utf8"));
+		} catch {
+			contents.set(file, void 0);
+		}
+		return contents.get(file);
+	};
+	const lines = [];
+	const byKey = /* @__PURE__ */ new Map();
+	for (const entry of result.missing) {
+		const grouped = byKey.get(entry.key);
+		if (grouped) grouped.locales.push(entry.locale);
+		else byKey.set(entry.key, {
+			...entry,
+			locales: [entry.locale]
+		});
+	}
+	for (const entry of byKey.values()) {
+		const origin = messages.get(entry.key);
+		const hint = entry.source ? `: "${truncate(entry.source, 60)}"` : "";
+		const text = escapeData(`missing [${entry.locales.join(", ")}] ${entry.key}${hint}`);
+		if (origin) {
+			const file = relative(root, origin.file).replaceAll("\\", "/");
+			const content = readSource(origin.file);
+			const line = content === void 0 ? void 0 : lineAt(content, origin.start);
+			lines.push(`::error file=${escapeProperty(file)}${line ? `,line=${line}` : ""}::${text}`);
+		} else lines.push(`::error::${text}`);
+	}
+	for (const entry of result.unknown) {
+		const text = escapeData(`unknown key "${entry.key}" (not in any catalog)`);
+		const file = entry.files[0];
+		lines.push(file ? `::error file=${escapeProperty(relative(root, file).replaceAll("\\", "/"))}::${text}` : `::error::${text}`);
+	}
+	return lines;
+}
+function lineAt(content, offset) {
+	let line = 1;
+	const end = Math.min(offset, content.length);
+	for (let i = 0; i < end; i++) if (content[i] === "\n") line += 1;
+	return line;
+}
+function escapeData(text) {
+	return text.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+}
+function escapeProperty(text) {
+	return escapeData(text).replaceAll(":", "%3A").replaceAll(",", "%2C");
+}
 //#endregion
 //#region src/params.ts
 const PLURAL_KEYS = /* @__PURE__ */ new Set([
@@ -199,12 +251,13 @@ declare module 'virtual:verbaly/locale/*' {
 }
 `;
 }
-function writeDts(cfg, catalog) {
-	const file = join(cfg.root, "verbaly.d.ts");
+function writeDts(cfg, catalog, file) {
+	file ??= join(cfg.root, "verbaly.d.ts");
 	const content = generateDts(catalog);
 	try {
 		if (readFileSync(file, "utf8") === content) return;
 	} catch {}
+	mkdirSync(dirname(file), { recursive: true });
 	writeFileSync(file, content);
 }
 //#endregion
@@ -334,15 +387,16 @@ function resolveConfig(config = {}) {
 	const sourceLocale = config.sourceLocale ?? "en";
 	const locales = /* @__PURE__ */ new Set([sourceLocale, ...config.locales ?? []]);
 	if (existsSync(dir)) {
-		for (const file of readdirSync(dir)) if (file.endsWith(".json") && file !== `en-XA.json`) locales.add(file.slice(0, -5));
+		for (const file of readdirSync(dir)) if (file.endsWith(".json") && !file.startsWith(".") && file !== `en-XA.json`) locales.add(file.slice(0, -5));
 	}
 	return {
 		root,
 		dir,
 		sourceLocale,
 		locales: [...locales],
-		include: config.include ?? ["{src,app}/**/*.{js,jsx,ts,tsx,mjs,mts,svelte,vue}"],
+		include: config.include ?? ["{src,app}/**/*.{js,jsx,ts,tsx,mjs,mts,svelte,vue,astro}"],
 		exclude: config.exclude ?? ["**/node_modules/**", "**/dist/**"],
+		dts: typeof config.dts === "string" ? resolve(root, config.dts) : config.dts,
 		translate: config.translate ?? {},
 		render: config.render ?? {}
 	};
@@ -705,13 +759,14 @@ function isNode(value) {
 }
 //#endregion
 //#region src/sfc.ts
-const SFC_FILE_RE = /\.(?:svelte|vue)$/;
+const SFC_FILE_RE = /\.(?:svelte|vue|astro)$/;
 function analyzeFile(code, file) {
 	return SFC_FILE_RE.test(file) ? analyzeSfc(code, file) : analyze(code, file);
 }
 const SCRIPT_RE = /(<script\b[^>]*>)([\s\S]*?)(<\/script\s*>)/gi;
 const STYLE_RE = /<style\b[^>]*>[\s\S]*?<\/style\s*>/gi;
 const COMMENT_RE = /<!--[\s\S]*?-->/g;
+const FRONTMATTER_RE = /^(\uFEFF?\s*---\r?\n)([\s\S]*?)\r?\n---(?=\r?\n|$)/;
 const CANDIDATE_SVELTE = /(?<![\w$])\$?t(?=[`(]|\.id\()/g;
 const CANDIDATE_VUE = /(?<![\w$])t(?=[`(]|\.id\()/g;
 function analyzeSfc(code, file) {
@@ -719,12 +774,14 @@ function analyzeSfc(code, file) {
 	const options = svelte ? { tNames: ["t", "$t"] } : void 0;
 	const tagged = [];
 	const usedKeys = [];
+	const frontmatter = file.endsWith(".astro") ? FRONTMATTER_RE.exec(code) : null;
+	if (frontmatter?.[2]) merge(analyzeSegment(frontmatter[2], file, options), frontmatter[1].length, false);
 	for (const match of code.matchAll(SCRIPT_RE)) {
 		const content = match[2];
 		if (!content) continue;
 		merge(analyzeSegment(content, file, options), match.index + match[1].length, false);
 	}
-	const markup = blank(blank(blank(code, SCRIPT_RE), STYLE_RE), COMMENT_RE);
+	const markup = blank(blank(blank(frontmatter ? " ".repeat(frontmatter[0].length) + code.slice(frontmatter[0].length) : code, SCRIPT_RE), STYLE_RE), COMMENT_RE);
 	const candidates = svelte ? CANDIDATE_SVELTE : CANDIDATE_VUE;
 	let consumedTo = 0;
 	for (const match of markup.matchAll(candidates)) {
@@ -854,6 +911,7 @@ function pruneCatalogs(cfg, catalogs, registry) {
 //#endregion
 //#region src/init.ts
 const BUNDLERS = [
+	"astro",
 	"vite",
 	"webpack",
 	"rollup",
@@ -907,7 +965,8 @@ function init(options = {}) {
 	}
 	const bundler = detectBundler(root);
 	const next = [];
-	if (bundler === "vite") next.push("install the plugin: pnpm add -D @verbaly/vite", "add verbaly() to the plugins in vite.config");
+	if (bundler === "astro") next.push("install the integration: pnpm add -D @verbaly/astro", "add verbaly() to the integrations in astro.config");
+	else if (bundler === "vite") next.push("install the plugin: pnpm add -D @verbaly/vite", "add verbaly() to the plugins in vite.config");
 	else if (bundler) next.push("install the plugin: pnpm add -D @verbaly/unplugin", `add the verbaly ${bundler} plugin to your build config`);
 	else next.push("run \"verbaly extract\" after writing your first t`…` message");
 	return {
@@ -980,8 +1039,8 @@ async function doctor(cfg) {
 	else if (wired) ok("plugin", `${deps["@verbaly/vite"] ? "@verbaly/vite" : "@verbaly/unplugin"} installed for ${bundler}`);
 	else if (bundler === "vite") warn("plugin", "vite detected but @verbaly/vite is not installed", "pnpm add -D @verbaly/vite and add verbaly() to the plugins in vite.config");
 	else warn("plugin", `${bundler} detected but @verbaly/unplugin is not installed`, `pnpm add -D @verbaly/unplugin and add the verbaly ${bundler} plugin to your build config`);
-	if (source) {
-		const dtsPath = join(cfg.root, "verbaly.d.ts");
+	if (source && cfg.dts !== false) {
+		const dtsPath = cfg.dts ?? join(cfg.root, "verbaly.d.ts");
 		if (!existsSync(dtsPath)) warn("types", "verbaly.d.ts has not been generated", "run `npx verbaly extract`");
 		else if (readFileSync(dtsPath, "utf8") !== generateDts(source)) warn("types", "verbaly.d.ts is stale", "run `npx verbaly extract`");
 		else ok("types", "verbaly.d.ts is up to date");
@@ -1024,6 +1083,66 @@ function readDeps(root) {
 	}
 }
 //#endregion
+//#region src/drafts.ts
+const DRAFTS_FILE = ".verbaly-drafts.json";
+function draftsPath(cfg) {
+	return join(cfg.dir, DRAFTS_FILE);
+}
+function loadDrafts(cfg) {
+	let content;
+	try {
+		content = readFileSync(draftsPath(cfg), "utf8");
+	} catch {
+		return {};
+	}
+	try {
+		return JSON.parse(content.replace(/^\uFEFF/, ""));
+	} catch (error) {
+		throw new Error(`[verbaly] ${draftsPath(cfg)} is not valid JSON, fix or delete the file`, { cause: error });
+	}
+}
+function serializeDrafts(drafts) {
+	const sorted = {};
+	for (const locale of Object.keys(drafts).sort()) {
+		const keys = [...new Set(drafts[locale])].sort();
+		if (keys.length) sorted[locale] = keys;
+	}
+	return JSON.stringify(sorted, null, 2) + "\n";
+}
+function saveDrafts(cfg, drafts) {
+	const serialized = serializeDrafts(drafts);
+	const path = draftsPath(cfg);
+	try {
+		if (readFileSync(path, "utf8") === serialized) return;
+	} catch {
+		mkdirSync(cfg.dir, { recursive: true });
+	}
+	writeFileSync(path, serialized);
+}
+function markDrafts(drafts, locale, keys) {
+	if (!keys.length) return;
+	drafts[locale] = [.../* @__PURE__ */ new Set([...drafts[locale] ?? [], ...keys])];
+}
+function clearDrafts(drafts, locale, keys) {
+	if (!drafts[locale]) return;
+	if (!keys) {
+		delete drafts[locale];
+		return;
+	}
+	const drop = new Set(keys);
+	drafts[locale] = drafts[locale].filter((key) => !drop.has(key));
+	if (!drafts[locale].length) delete drafts[locale];
+}
+function effectiveDrafts(drafts, catalogs) {
+	const out = {};
+	for (const [locale, keys] of Object.entries(drafts)) {
+		const catalog = catalogs[locale] ?? {};
+		const live = keys.filter((key) => catalog[key]);
+		if (live.length) out[locale] = live;
+	}
+	return out;
+}
+//#endregion
 //#region src/mobile.ts
 function androidValuesDir(locale, sourceLocale) {
 	if (locale === sourceLocale) return "values";
@@ -1084,10 +1203,12 @@ async function translateCatalogs(cfg, catalogs, provider, options = {}) {
 		for (let i = 0; i < missing.length; i += batchSize) {
 			const keys = missing.slice(i, i + batchSize);
 			const messages = Object.fromEntries(keys.map((key) => [key, source[key]]));
+			const origins = options.origins ? Object.fromEntries(keys.filter((key) => options.origins[key]).map((key) => [key, options.origins[key]])) : void 0;
 			const out = await provider({
 				sourceLocale: cfg.sourceLocale,
 				targetLocale: locale,
-				messages
+				messages,
+				origins
 			});
 			for (const key of keys) {
 				const text = out[key];
@@ -1611,9 +1732,10 @@ function decodeEntities(text) {
 }
 //#endregion
 //#region src/status.ts
-function status(cfg, catalogs, registry) {
+function status(cfg, catalogs, registry, drafts = {}) {
 	const source = catalogs[cfg.sourceLocale] ?? {};
 	const needed = /* @__PURE__ */ new Set([...registry.messages().keys(), ...Object.keys(source)]);
+	const live = effectiveDrafts(drafts, catalogs);
 	const locales = [];
 	for (const locale of cfg.locales) {
 		if (locale === cfg.sourceLocale) continue;
@@ -1622,7 +1744,8 @@ function status(cfg, catalogs, registry) {
 		locales.push({
 			locale,
 			translated,
-			total: needed.size
+			total: needed.size,
+			drafts: live[locale]?.length ?? 0
 		});
 	}
 	return {
@@ -1637,14 +1760,15 @@ function formatStatusResult(result) {
 		lines.push("  no target locales (add locales to your config)");
 		return lines.join("\n");
 	}
-	for (const { locale, translated, total } of result.locales) {
+	for (const { locale, translated, total, drafts } 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}`);
+		const draftNote = drafts > 0 ? `, ${drafts} unreviewed` : "";
+		lines.push(`  ${locale}: ${translated}/${total} translated (${pct}%${draftNote})${mark}`);
 	}
 	return lines.join("\n");
 }
-const SOURCE_FILE_RE = /\.(?:[cm]?[jt]sx?|svelte|vue)$/;
+const SOURCE_FILE_RE = /\.(?:[cm]?[jt]sx?|svelte|vue|astro)$/;
 //#endregion
 //#region src/watch.ts
 function watchProject(cfg, run, options = {}) {
@@ -1687,16 +1811,230 @@ function watchProject(cfg, run, options = {}) {
 	};
 }
 //#endregion
+//#region src/wrap.ts
+const WRAP_ATTRS = /* @__PURE__ */ new Set([
+	"title",
+	"alt",
+	"placeholder",
+	"aria-label"
+]);
+const T_NAMES = /* @__PURE__ */ new Set(["t"]);
+const LETTER = /\p{L}/u;
+async function wrapProject(cfg, options = {}) {
+	const files = (await glob(cfg.include, {
+		cwd: cfg.root,
+		ignore: cfg.exclude,
+		absolute: true
+	})).filter((file) => /\.[jt]sx$/.test(file));
+	const result = {
+		files: files.length,
+		changed: [],
+		wrapped: [],
+		skipped: []
+	};
+	for (const file of files) {
+		const code = readFileSync(file, "utf8");
+		const label = relative(cfg.root, file).replaceAll("\\", "/");
+		const out = wrapCode(code, label);
+		result.wrapped.push(...out.wrapped);
+		result.skipped.push(...out.skipped);
+		if (out.code !== void 0) {
+			result.changed.push(label);
+			if (options.write) writeFileSync(file, out.code);
+		}
+	}
+	return result;
+}
+function wrapCode(code, file) {
+	const wrapped = [];
+	const skipped = [];
+	let ast;
+	try {
+		ast = parse$1(code, {
+			sourceType: "module",
+			errorRecovery: true,
+			plugins: ["typescript", "jsx"]
+		}).program;
+	} catch {
+		return {
+			wrapped,
+			skipped
+		};
+	}
+	const s = new MagicString(code);
+	const visited = /* @__PURE__ */ new Set();
+	let changed = false;
+	walk(ast, (node) => {
+		if (node.type !== "JSXElement" && node.type !== "JSXFragment") return;
+		if (visited.has(node)) return;
+		processElement(node);
+	});
+	return changed ? {
+		code: s.toString(),
+		wrapped,
+		skipped
+	} : {
+		wrapped,
+		skipped
+	};
+	function processElement(node) {
+		visited.add(node);
+		if (node.type === "JSXElement") {
+			const opening = node.openingElement;
+			const name = opening.name;
+			if (name.type === "JSXIdentifier" && name.name === "Trans") return markSubtree(node);
+			if (hasVerbalyAttr(opening)) return markSubtree(node);
+			wrapAttributes(opening);
+		}
+		const children = node.children ?? [];
+		const hasElementChild = children.some((c) => c.type === "JSXElement" || c.type === "JSXFragment");
+		const hasText = children.some((c) => c.type === "JSXText" && LETTER.test(c.value) || c.type === "JSXExpressionContainer" && c.expression.type === "StringLiteral" && LETTER.test(c.expression.value));
+		if (hasElementChild && hasText) {
+			skip(node, snippet(children), "mixed text and markup: wrap by hand or use <Trans>");
+			return markSubtree(node);
+		}
+		if (hasText) {
+			wrapSegment(node, children);
+			return markSubtree(node);
+		}
+		for (const child of children) if (child.type === "JSXElement" || child.type === "JSXFragment") processElement(child);
+	}
+	function wrapSegment(parent, children) {
+		const meaningful = children.filter((c) => c.type === "JSXText" && c.value.trim() !== "" || c.type === "JSXExpressionContainer" && c.expression.type !== "JSXEmptyExpression");
+		if (meaningful.length === 0) return;
+		const first = meaningful[0];
+		const last = meaningful[meaningful.length - 1];
+		let template = "";
+		let report = "";
+		for (let i = children.indexOf(first); i <= children.indexOf(last); i++) {
+			const child = children[i];
+			if (child.type === "JSXText") {
+				let value = cleanJsxText(child.value);
+				if (child === first) value = value.trimStart();
+				if (child === last) value = value.trimEnd();
+				template += escapeTemplate(value);
+				report += value;
+			} else if (child.type === "JSXExpressionContainer") {
+				const expr = child.expression;
+				if (expr.type === "JSXEmptyExpression") continue;
+				if (usesT(expr)) {
+					skip(parent, snippet(children), "already uses t: finish it by hand");
+					return;
+				}
+				if (containsJsx(expr)) {
+					skip(parent, snippet(children), "an expression renders markup: wrap by hand or use <Trans>");
+					markSubtree(child);
+					return;
+				}
+				if (expr.type === "StringLiteral") {
+					template += escapeTemplate(expr.value);
+					report += expr.value;
+				} else {
+					const source = code.slice(expr.start, expr.end);
+					template += "${" + source + "}";
+					report += "${" + source + "}";
+				}
+			} else return;
+		}
+		if (!LETTER.test(report)) return;
+		const start = first.type === "JSXText" ? first.start + leadingWs(first.value) : first.start;
+		const end = last.type === "JSXText" ? last.end - trailingWs(last.value) : last.end;
+		s.overwrite(start, end, "{t`" + template + "`}");
+		changed = true;
+		wrapped.push({
+			file,
+			line: line(first),
+			text: report,
+			kind: "text"
+		});
+	}
+	function wrapAttributes(opening) {
+		for (const attr of opening.attributes) {
+			if (attr.type !== "JSXAttribute") continue;
+			const name = attr.name;
+			if (name.type !== "JSXIdentifier" || !WRAP_ATTRS.has(name.name)) continue;
+			const value = attr.value;
+			if (value?.type !== "StringLiteral") continue;
+			const raw = value.value;
+			if (!LETTER.test(raw)) continue;
+			s.overwrite(value.start, value.end, "{t`" + escapeTemplate(raw) + "`}");
+			changed = true;
+			wrapped.push({
+				file,
+				line: line(value),
+				text: raw,
+				kind: "attribute",
+				attribute: name.name
+			});
+		}
+	}
+	function skip(node, text, reason) {
+		skipped.push({
+			file,
+			line: line(node),
+			text,
+			reason
+		});
+	}
+	function snippet(children) {
+		const start = children[0]?.start ?? 0;
+		const end = children[children.length - 1]?.end ?? start;
+		const text = code.slice(start, end).replace(/\s+/g, " ").trim();
+		return text.length > 60 ? text.slice(0, 59) + "…" : text;
+	}
+	function markSubtree(node) {
+		walk(node, (n) => {
+			if (n.type === "JSXElement" || n.type === "JSXFragment") visited.add(n);
+		});
+	}
+}
+function hasVerbalyAttr(opening) {
+	return opening.attributes.some((attr) => {
+		if (attr.type !== "JSXAttribute") return false;
+		const name = attr.name;
+		return name.type === "JSXIdentifier" && name.name.startsWith("data-verbaly");
+	});
+}
+function usesT(node) {
+	let found = false;
+	walk(node, (n) => {
+		if (n.type === "TaggedTemplateExpression" && isTReference(n.tag, T_NAMES)) found = true;
+		if (n.type === "CallExpression" && isTReference(n.callee, T_NAMES)) found = true;
+	});
+	return found;
+}
+function containsJsx(node) {
+	let found = false;
+	walk(node, (n) => {
+		if (n.type === "JSXElement" || n.type === "JSXFragment") found = true;
+	});
+	return found;
+}
+function escapeTemplate(text) {
+	return text.replace(/[\\`]/g, "\\$&").replace(/\$\{/g, "\\${");
+}
+function leadingWs(text) {
+	return text.length - text.trimStart().length;
+}
+function trailingWs(text) {
+	return text.length - text.trimEnd().length;
+}
+function line(node) {
+	return node.loc?.start?.line ?? 1;
+}
+//#endregion
 //#region src/run.ts
 const HELP = `verbaly · i18n compiler
 
 Usage:
   verbaly init       scaffold config + locale catalogs (detects your bundler)
   verbaly doctor     diagnose the setup (config, catalogs, plugin, types, keys)
+  verbaly wrap       find hardcoded JSX text and wrap it in t\`…\` (report; --write applies)
   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 review     list machine translations awaiting review (--approve marks them reviewed)
   verbaly export     write translator files (XLIFF 2.0, CSV) or mobile resources (Android, iOS)
   verbaly import <files…>  fill catalogs back from translated XLIFF/CSV files
   verbaly pseudo     generate a pseudo-locale catalog for i18n QA (default: en-XA)
@@ -1709,6 +2047,11 @@ Options:
   --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)
+  --write            apply the rewrites instead of only reporting (wrap)
+  --json             machine-readable output (status)
+  --drafts           also fail on unreviewed machine translations (check)
+  --approve          mark listed drafts as reviewed (review)
+  --reporter <name>  failure format: text (default) or github annotations (check)
   --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)
@@ -1736,6 +2079,11 @@ async function runCli(args = process.argv.slice(2)) {
 			locales: { type: "string" },
 			prune: { type: "boolean" },
 			watch: { type: "boolean" },
+			write: { type: "boolean" },
+			json: { type: "boolean" },
+			drafts: { type: "boolean" },
+			approve: { type: "boolean" },
+			reporter: { type: "string" },
 			model: { type: "string" },
 			locale: { type: "string" },
 			site: { type: "string" },
@@ -1818,7 +2166,7 @@ async function runCli(args = process.argv.slice(2)) {
 			const { added } = syncCatalogs(cfg, catalogs, registry);
 			if (!dryRun) {
 				for (const locale of cfg.locales) writeCatalog(cfg, locale, catalogs[locale] ?? {});
-				writeDts(cfg, catalogs[cfg.sourceLocale] ?? {});
+				if (cfg.dts !== false) writeDts(cfg, catalogs[cfg.sourceLocale] ?? {}, cfg.dts);
 			}
 			const total = registry.messages().size;
 			console.log(`[verbaly] ${total} messages · locales: ${cfg.locales.join(", ")}${dryRun ? " (dry run, nothing written)" : ""}`);
@@ -1831,19 +2179,58 @@ async function runCli(args = process.argv.slice(2)) {
 		}
 		return;
 	}
+	if (command === "wrap") {
+		const result = await wrapProject(cfg, { write: values.write });
+		if (result.wrapped.length === 0 && result.skipped.length === 0) {
+			console.log(`[verbaly] nothing to wrap (${result.files} files scanned) ✓`);
+			return;
+		}
+		const verb = values.write ? "wrapped" : "would wrap";
+		const note = values.write ? "" : " (report only, use --write to apply)";
+		console.log(`[verbaly] ${verb} ${result.wrapped.length} texts in ${result.changed.length} files${note}`);
+		for (const entry of result.wrapped) {
+			const attr = entry.kind === "attribute" ? `${entry.attribute} → ` : "";
+			console.log(`  ${entry.file}:${entry.line}  ${attr}"${entry.text}"`);
+		}
+		if (result.skipped.length > 0) {
+			console.log("  needs a human:");
+			for (const entry of result.skipped) console.log(`  ${entry.file}:${entry.line}  "${entry.text}" (${entry.reason})`);
+		}
+		if (values.write && result.changed.length > 0) console.log("  next: make t available where TS complains (React: const t = useT()), then run verbaly extract");
+		return;
+	}
 	if (command === "status") {
 		const registry = await extractProject(cfg);
-		console.log(formatStatusResult(status(cfg, loadCatalogs(cfg), registry)));
+		const result = status(cfg, loadCatalogs(cfg), registry, loadDrafts(cfg));
+		console.log(values.json ? JSON.stringify(result) : formatStatusResult(result));
 		return;
 	}
 	if (command === "check") {
+		const reporter = values.reporter ?? "text";
+		if (reporter !== "text" && reporter !== "github") {
+			console.error(`[verbaly] unknown reporter "${values.reporter}", use text or github`);
+			process.exitCode = 1;
+			return;
+		}
 		const registry = await extractProject(cfg);
-		const result = check(cfg, loadCatalogs(cfg), registry);
-		if (result.ok) {
+		const catalogs = loadCatalogs(cfg);
+		const result = check(cfg, catalogs, registry);
+		const unreviewed = values.drafts ? effectiveDrafts(loadDrafts(cfg), catalogs) : {};
+		const draftKeys = Object.entries(unreviewed);
+		if (result.ok && draftKeys.length === 0) {
 			console.log("[verbaly] all translations complete ✓");
 			return;
 		}
-		console.error(`[verbaly] check failed\n${formatCheckResult(result)}`);
+		if (result.ok && draftKeys.length > 0) {
+			for (const [locale, keys] of draftKeys) console.error(`  [${locale}] ${keys.length} unreviewed: ${keys.join(", ")}`);
+			console.error("[verbaly] check failed: machine translations awaiting review (run verbaly review --approve)");
+			process.exitCode = 1;
+			return;
+		}
+		if (reporter === "github") {
+			for (const line of githubCheckAnnotations(result, registry, cfg.root)) console.error(line);
+			console.error(`[verbaly] check failed: ${result.missing.length} missing, ${result.unknown.length} unknown`);
+		} else console.error(`[verbaly] check failed\n${formatCheckResult(result)}`);
 		process.exitCode = 1;
 		return;
 	}
@@ -1852,7 +2239,8 @@ async function runCli(args = process.argv.slice(2)) {
 		const result = await translateCatalogs(cfg, catalogs, await resolveProvider(cfg, values.model), {
 			locales: values.locales?.split(","),
 			batchSize: cfg.translate.batchSize,
-			dryRun: values["dry-run"]
+			dryRun: values["dry-run"],
+			origins: values["dry-run"] ? void 0 : await collectOrigins(cfg)
 		});
 		if (values["dry-run"]) {
 			const entries = Object.entries(result.pending);
@@ -1863,14 +2251,43 @@ async function runCli(args = process.argv.slice(2)) {
 			for (const [locale, keys] of entries) console.log(`  ${locale}: ${keys.length} missing: ${keys.join(", ")}`);
 			return;
 		}
+		const drafts = loadDrafts(cfg);
 		for (const locale of Object.keys(result.translated)) {
 			writeCatalog(cfg, locale, catalogs[locale] ?? {});
-			console.log(`  ${locale}: +${result.translated[locale].length} translated`);
+			markDrafts(drafts, locale, result.translated[locale]);
+			console.log(`  ${locale}: +${result.translated[locale].length} translated (draft)`);
 		}
+		if (Object.keys(result.translated).length > 0) saveDrafts(cfg, drafts);
 		for (const [locale, keys] of Object.entries(result.invalid)) console.warn(`  ${locale}: ${keys.length} rejected (params/tags not preserved): ${keys.join(", ")}`);
 		if (Object.keys(result.translated).length === 0 && Object.keys(result.invalid).length === 0) console.log("[verbaly] nothing to translate ✓");
 		return;
 	}
+	if (command === "review") {
+		const catalogs = loadCatalogs(cfg);
+		const drafts = loadDrafts(cfg);
+		const live = effectiveDrafts(drafts, catalogs);
+		const targets = values.locale ? { [values.locale]: live[values.locale] ?? [] } : live;
+		const entries = Object.entries(targets).filter(([, keys]) => keys.length);
+		if (entries.length === 0) {
+			console.log("[verbaly] no machine translations awaiting review ✓");
+			return;
+		}
+		if (values.approve) {
+			let count = 0;
+			for (const [locale, keys] of entries) {
+				clearDrafts(drafts, locale, keys);
+				count += keys.length;
+				console.log(`  ${locale}: ${keys.length} approved`);
+			}
+			saveDrafts(cfg, drafts);
+			console.log(`[verbaly] ${count} translations marked reviewed ✓`);
+			return;
+		}
+		const total = entries.reduce((sum, [, keys]) => sum + keys.length, 0);
+		console.log(`[verbaly] ${total} machine translations awaiting review (--approve to accept)`);
+		for (const [locale, keys] of entries) console.log(`  ${locale}: ${keys.join(", ")}`);
+		return;
+	}
 	if (command === "export") {
 		const format = values.format ?? "xliff";
 		if (![
@@ -1917,11 +2334,18 @@ async function runCli(args = process.argv.slice(2)) {
 			overwrite: values.overwrite,
 			dryRun: values["dry-run"]
 		});
+		const drafts = loadDrafts(cfg);
+		let draftsChanged = false;
 		for (const [locale, keys] of Object.entries(result.imported)) {
-			if (!values["dry-run"]) writeCatalog(cfg, locale, catalogs[locale] ?? {});
+			if (!values["dry-run"]) {
+				writeCatalog(cfg, locale, catalogs[locale] ?? {});
+				clearDrafts(drafts, locale, keys);
+				draftsChanged = true;
+			}
 			const verb = values["dry-run"] ? "would import" : "imported";
 			console.log(`  ${locale}: +${keys.length} ${verb}`);
 		}
+		if (draftsChanged) saveDrafts(cfg, drafts);
 		for (const [locale, keys] of Object.entries(result.skipped)) console.log(`  ${locale}: ${keys.length} already translated, kept (use --overwrite to replace)`);
 		for (const [locale, keys] of Object.entries(result.rejected)) console.warn(`  ${locale}: ${keys.length} rejected (params/tags not preserved): ${keys.join(", ")}`);
 		for (const [locale, keys] of Object.entries(result.unknown)) console.warn(`  ${locale}: ${keys.length} unknown keys ignored (not in the source catalog): ${keys.join(", ")}`);
@@ -1967,9 +2391,11 @@ const COMMAND_FLAGS = {
 		"dry-run",
 		"watch"
 	],
-	status: [],
-	check: [],
+	wrap: ["write"],
+	status: ["json"],
+	check: ["reporter", "drafts"],
 	translate: ["model", "dry-run"],
+	review: ["approve", "locale"],
 	export: [
 		"format",
 		"out",
@@ -2008,7 +2434,7 @@ async function collectOrigins(cfg) {
 async function resolveProvider(cfg, model) {
 	const configured = cfg.translate.provider;
 	if (typeof configured === "function") return configured;
-	const { claudeProvider } = await import("./claude-C-ETlqsW.js");
+	const { claudeProvider } = await import("./claude-h9WA0ppg.js");
 	return claudeProvider({ model: model ?? cfg.translate.model });
 }
 //#endregion