@dialexjs/cli 0.3.0 → 0.5.0

package/dist/index.mjs

@@ -1,972 +1,1125 @@
 #!/usr/bin/env node
-import { C as saveDictionaryFile, D as logger, E as runGenerate, T as generateDictionaries, _ as listLeaves, c as analyzeProject, d as TODO_PREFIX, f as copyLeaf, g as hasPath, h as getString, r as toKey, t as loadProject, v as listLocales, w as setString, y as loadDictionaryFile } from "./project-ClQxaIMc.mjs";
+import { A as listLocales, C as TODO_PREFIX, D as getString, F as saveDictionaryFile, I as setString, O as hasPath, S as writeLock, _ as isStale, a as renderGenerated, b as readLock, f as analyzeProject, h as LOCK_FILE, i as generateDictionaries, j as loadDictionaryFile, k as listLeaves, o as runGenerate, r as toKey, t as loadProject, u as logger, v as lockFor, w as copyLeaf, x as record, y as lockPath } from "./project-BJYmnKiU.mjs";
 import { Command } from "commander";
 import fs from "node:fs";
 import path from "node:path";
-import fg from "fast-glob";
 import { resolveDialexConfig } from "dialexjs/scanner";
+import fg from "fast-glob";
 import pc from "picocolors";
-import * as p from "@clack/prompts";
-import { loadFile, parseModule, writeFile } from "magicast";
-import { addNuxtModule, addVitePlugin } from "magicast/helpers";
 import { fileURLToPath } from "node:url";
+import { loadFile, parseModule, writeFile } from "magicast";
 import { argumentSignature, getArguments, isIcuStructured, parseMessage } from "dialexjs/icu";
-//#region src/utils/detector.ts
+import * as p from "@clack/prompts";
+import { addNuxtModule } from "magicast/helpers";
+//#region package.json
+var version = "0.5.0";
+//#endregion
+//#region src/commands/check.ts
+const DICTIONARY_IGNORE = [
+	"**/node_modules/**",
+	"**/dist/**",
+	"**/.next/**",
+	"**/dialex.locales/**"
+];
+function addIssue(diag, issue) {
+	const level = issue.level === "error" ? "error" : "warning";
+	(level === "error" ? diag.errors : diag.warnings).push(issue.message);
+	diag.annotations.push({
+		level,
+		message: issue.message,
+		line: issue.range ? issue.range.start.line + 1 : void 0
+	});
+}
 /**
-* Automatically inspects package.json dependencies and configuration files
-* to detect the active framework in the target project.
+* Inserts keys that exist in one locale but not in another, copying the default-locale value
+* (strings get a `[TODO]` prefix). Returns how many keys were inserted.
 */
-function detectFramework(root) {
-	const pkgPath = path.join(root, "package.json");
-	if (fs.existsSync(pkgPath)) try {
-		const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-		const allDeps = {
-			...pkg.dependencies,
-			...pkg.devDependencies
-		};
-		if ("nuxt" in allDeps) return {
-			framework: "nuxt",
-			confidence: "high",
-			matchedRule: "package.json dependencies (nuxt)"
-		};
-		if ("@sveltejs/kit" in allDeps) return {
-			framework: "sveltekit",
-			confidence: "high",
-			matchedRule: "package.json dependencies (@sveltejs/kit)"
-		};
-		if ("astro" in allDeps) return {
-			framework: "astro",
-			confidence: "high",
-			matchedRule: "package.json dependencies (astro)"
-		};
-		if ("next" in allDeps) return {
-			framework: "next",
-			confidence: "high",
-			matchedRule: "package.json dependencies (next)"
-		};
-		if ("@nestjs/core" in allDeps || "@nestjs/common" in allDeps) return {
-			framework: "nestjs",
-			confidence: "high",
-			matchedRule: "package.json dependencies (@nestjs/core)"
-		};
-		if ("fastify" in allDeps) return {
-			framework: "fastify",
-			confidence: "high",
-			matchedRule: "package.json dependencies (fastify)"
-		};
-		if ("koa" in allDeps) return {
-			framework: "koa",
-			confidence: "high",
-			matchedRule: "package.json dependencies (koa)"
-		};
-		if ("express" in allDeps) return {
-			framework: "express",
-			confidence: "high",
-			matchedRule: "package.json dependencies (express)"
-		};
-		if ("elysia" in allDeps) return {
-			framework: "elysia",
-			confidence: "high",
-			matchedRule: "package.json dependencies (elysia)"
-		};
-		if ("hono" in allDeps) return {
-			framework: "hono",
-			confidence: "high",
-			matchedRule: "package.json dependencies (hono)"
-		};
-		if ("vue" in allDeps && !("react" in allDeps)) return {
-			framework: "vue",
-			confidence: "high",
-			matchedRule: "package.json dependencies (vue)"
-		};
-		if ("react" in allDeps || "vite" in allDeps) return {
-			framework: "react",
-			confidence: "high",
-			matchedRule: "package.json dependencies (react/vite)"
-		};
-	} catch {}
-	if (fs.existsSync(path.join(root, "next.config.js")) || fs.existsSync(path.join(root, "next.config.mjs")) || fs.existsSync(path.join(root, "next.config.ts"))) return {
-		framework: "next",
-		confidence: "medium",
-		matchedRule: "next.config file presence"
-	};
-	for (const [framework, base] of [
-		["nuxt", "nuxt.config"],
-		["sveltekit", "svelte.config"],
-		["astro", "astro.config"]
-	]) if ([
-		"js",
-		"mjs",
-		"ts"
-	].some((ext) => fs.existsSync(path.join(root, `${base}.${ext}`)))) return {
-		framework,
-		confidence: "medium",
-		matchedRule: `${base} file presence`
-	};
-	if (fs.existsSync(path.join(root, "vite.config.js")) || fs.existsSync(path.join(root, "vite.config.mjs")) || fs.existsSync(path.join(root, "vite.config.ts"))) return {
-		framework: "react",
-		confidence: "medium",
-		matchedRule: "vite.config file presence"
-	};
-	return {
-		framework: "hono",
-		confidence: "fallback",
-		matchedRule: "default fallback"
-	};
-}
-//#endregion
-//#region src/utils/package-json.ts
-/** Version of this CLI, which the other Dialex packages share. Read from the nearest package.json. */
-function cliVersion() {
-	let dir = path.dirname(fileURLToPath(import.meta.url));
-	for (let i = 0; i < 4; i++) {
-		try {
-			const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8"));
-			if (pkg.name === "@dialexjs/cli") return pkg.version;
-		} catch {}
-		dir = path.dirname(dir);
+async function applyFixes(files, configuredLocales, defaultLocale) {
+	let fixed = 0;
+	for (const file of files) {
+		const df = await loadDictionaryFile(file);
+		if (!df?.complete) continue;
+		const present = listLocales(df);
+		const targets = Array.from(/* @__PURE__ */ new Set([...present, ...configuredLocales]));
+		const sourceOrder = [defaultLocale, ...present.filter((l) => l !== defaultLocale)].filter((l) => present.includes(l));
+		const allPaths = /* @__PURE__ */ new Map();
+		for (const locale of present) for (const leaf of listLeaves(df, locale)) allPaths.set(leaf.path.join("\0"), leaf.path);
+		let changed = false;
+		for (const target of targets) for (const leafPath of allPaths.values()) {
+			if (hasPath(df, target, leafPath)) continue;
+			const source = sourceOrder.find((l) => l !== target && hasPath(df, l, leafPath));
+			if (source && copyLeaf(df, source, target, leafPath, (v) => `[TODO] ${v}`)) {
+				fixed++;
+				changed = true;
+			}
+		}
+		if (changed) await saveDictionaryFile(df);
 	}
+	return fixed;
 }
-/** The install command for the package manager a project uses, judged by its lockfile. */
-function installCommand(root) {
-	const has = (file) => fs.existsSync(path.join(root, file));
-	if (has("bun.lock") || has("bun.lockb")) return "bun install";
-	if (has("pnpm-lock.yaml")) return "pnpm install";
-	if (has("yarn.lock")) return "yarn install";
-	return "npm install";
+function escapeAnnotation(value) {
+	return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
 }
-const sorted = (deps) => Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)));
 /**
-* Adds the packages a Dialex project needs: `dialexjs` as a dependency and the CLI as a dev
-* dependency (the `dx:generate` script runs it). Packages already listed anywhere are left alone.
-* Returns the names it added.
+* What a formatter (Prettier, Biome, oxfmt) can change without changing the code: whitespace,
+* quote style, quoted object keys and trailing commas. Comparing this form keeps `check` quiet
+* when your pre-commit hook formats the generated files.
 */
-function addRequiredPackages(pkg, version = cliVersion()) {
-	const range = version ? `^${version}` : "latest";
-	const listed = (name) => [
-		pkg.dependencies,
-		pkg.devDependencies,
-		pkg.peerDependencies
-	].some((deps) => deps && name in deps);
-	const added = [];
-	if (!listed("dialexjs")) {
-		pkg.dependencies = sorted({
-			...pkg.dependencies,
-			dialexjs: range
-		});
-		added.push("dialexjs");
+function normalizeGenerated(text) {
+	return text.replace(/'/g, "\"").replace(/"([A-Za-z_$][\w$]*)"\s*:/g, "$1:").replace(/\s+/g, "").replace(/,(?=[\]})])/g, "");
+}
+/**
+* Generated files that exist but no longer match the dictionaries and config. Nothing builds them
+* for you any more, so a stale `dialex.generated.ts` would otherwise fail silently at runtime.
+* With `fix` they are rewritten.
+*/
+function staleGeneratedFiles(root, options) {
+	let rendered;
+	try {
+		rendered = renderGenerated(root, { config: options.config });
+	} catch {
+		return {
+			stale: [],
+			rewritten: 0
+		};
 	}
-	if (!listed("@dialexjs/cli")) {
-		pkg.devDependencies = sorted({
-			...pkg.devDependencies,
-			"@dialexjs/cli": range
+	const stale = [];
+	let rewritten = 0;
+	const targets = [[rendered.outputPath, rendered.content], [rendered.dtsPath, rendered.dtsContent]];
+	if (fs.existsSync(rendered.outputPath)) for (const extra of rendered.extraFiles) targets.push([extra.path, extra.content]);
+	for (const [file, content] of targets) {
+		if (content === void 0) continue;
+		const isExtra = rendered.extraFiles.some((f) => f.path === file);
+		if (!fs.existsSync(file)) {
+			if (!isExtra) continue;
+			if (options.fix) {
+				fs.mkdirSync(path.dirname(file), { recursive: true });
+				fs.writeFileSync(file, content, "utf-8");
+				rewritten++;
+			} else stale.push({
+				file: path.relative(root, file),
+				message: "Missing. Run `dx generate` (or `dx check --fix`)."
+			});
+			continue;
+		}
+		if (normalizeGenerated(fs.readFileSync(file, "utf-8")) === normalizeGenerated(content)) continue;
+		if (options.fix) {
+			fs.writeFileSync(file, content, "utf-8");
+			rewritten++;
+		} else stale.push({
+			file: path.relative(root, file),
+			message: "Out of date with your dictionaries or config. Run `dx generate` (or `dx check --fix`)."
 		});
-		added.push("@dialexjs/cli");
 	}
-	return added;
+	return {
+		stale,
+		rewritten
+	};
 }
-//#endregion
-//#region src/commands/init.ts
-async function runInit(options = {}) {
+async function runCheck(options = {}) {
 	const root = options.cwd || process.cwd();
-	const detected = detectFramework(root);
-	const isInteractive = !options.yes && process.stdin.isTTY;
-	let framework = options.framework || detected.framework;
-	let defaultLocale = options.defaultLocale || "en";
-	let localesInput = options.locales || "en,tr";
-	if (isInteractive) {
-		p.intro(pc.bgCyan(pc.black(" dialex init ")));
-		const frameworkOptions = [
-			{
-				value: "hono",
-				label: "Hono",
-				hint: detected.framework === "hono" ? "detected" : void 0
-			},
-			{
-				value: "express",
-				label: "Express",
-				hint: detected.framework === "express" ? "detected" : void 0
-			},
-			{
-				value: "fastify",
-				label: "Fastify",
-				hint: detected.framework === "fastify" ? "detected" : void 0
-			},
-			{
-				value: "koa",
-				label: "Koa",
-				hint: detected.framework === "koa" ? "detected" : void 0
-			},
-			{
-				value: "nestjs",
-				label: "NestJS",
-				hint: detected.framework === "nestjs" ? "detected" : void 0
-			},
-			{
-				value: "next",
-				label: "Next.js",
-				hint: detected.framework === "next" ? "detected" : void 0
-			},
-			{
-				value: "react",
-				label: "React / Vite",
-				hint: detected.framework === "react" ? "detected" : void 0
-			},
-			{
-				value: "elysia",
-				label: "Elysia",
-				hint: detected.framework === "elysia" ? "detected" : void 0
-			},
-			{
-				value: "sveltekit",
-				label: "SvelteKit",
-				hint: detected.framework === "sveltekit" ? "detected" : void 0
-			},
-			{
-				value: "astro",
-				label: "Astro",
-				hint: detected.framework === "astro" ? "detected" : void 0
-			},
-			{
-				value: "vue",
-				label: "Vue / Vite",
-				hint: detected.framework === "vue" ? "detected" : void 0
-			},
-			{
-				value: "nuxt",
-				label: "Nuxt",
-				hint: detected.framework === "nuxt" ? "detected" : void 0
-			}
-		];
-		const selectedFramework = await p.select({
-			message: `Framework detected as ${pc.bold(detected.framework)} (${detected.matchedRule}). Select framework:`,
-			options: frameworkOptions,
-			initialValue: detected.framework
-		});
-		if (p.isCancel(selectedFramework)) {
-			p.cancel("Operation cancelled.");
-			return;
-		}
-		framework = selectedFramework;
-		const inputDefault = await p.text({
-			message: "What is your default locale?",
-			initialValue: "en",
-			validate: (v) => !v || !v.trim() ? "Default locale cannot be empty" : void 0
-		});
-		if (p.isCancel(inputDefault)) {
-			p.cancel("Operation cancelled.");
-			return;
+	const quiet = options.json === true;
+	const inlineConfig = options.config ? { configFile: options.config } : {};
+	const config = resolveDialexConfig(root, inlineConfig);
+	const include = config.include || "**/*.content.ts";
+	const configuredLocales = config.locales || [];
+	const defaultLocale = config.defaultLocale || "en";
+	const files = fg.sync(include, {
+		cwd: root,
+		absolute: true,
+		ignore: DICTIONARY_IGNORE
+	});
+	if (files.length === 0) {
+		if (!quiet) {
+			const patternStr = Array.isArray(include) ? include.join(", ") : include;
+			logger.warn(`No dictionary files found matching "${patternStr}".`);
 		}
-		defaultLocale = inputDefault.trim();
-		const inputLocales = await p.text({
-			message: "Comma-separated list of supported locales:",
-			initialValue: `${defaultLocale},tr`,
-			validate: (v) => !v || !v.trim() ? "Locales list cannot be empty" : void 0
-		});
-		if (p.isCancel(inputLocales)) {
-			p.cancel("Operation cancelled.");
-			return;
+		const empty = {
+			success: true,
+			diagnostics: [],
+			totalIssues: 0,
+			totalWarnings: 0,
+			fixed: 0
+		};
+		if (quiet) console.log(JSON.stringify(empty, null, 2));
+		return empty;
+	}
+	let fixed = 0;
+	if (options.fix) {
+		fixed = await applyFixes(files, configuredLocales, defaultLocale);
+		if (fixed > 0 && !quiet) logger.success(`Inserted ${fixed} missing key${fixed === 1 ? "" : "s"} marked ${TODO_PREFIX.trim()}`);
+	}
+	const generated = staleGeneratedFiles(root, options);
+	fixed += generated.rewritten;
+	if (generated.rewritten > 0 && !quiet) logger.success(`Regenerated ${generated.rewritten} out-of-date generated file${generated.rewritten === 1 ? "" : "s"}`);
+	const analysis = await analyzeProject({
+		root,
+		config,
+		src: options.src && options.src.length > 0 ? options.src : void 0,
+		runtime: true
+	});
+	const byFile = /* @__PURE__ */ new Map();
+	const dictionaryFiles = new Set(analysis.files);
+	for (const issue of analysis.issues) {
+		if (options.failOnStale && issue.code === "stale-translation") issue.level = "error";
+		if (issue.level === "info") continue;
+		const rel = path.relative(root, issue.file);
+		let diag = byFile.get(rel);
+		if (!diag) {
+			diag = {
+				file: rel,
+				errors: [],
+				warnings: [],
+				annotations: []
+			};
+			byFile.set(rel, diag);
 		}
-		localesInput = inputLocales.trim();
-		if (options.ai === void 0 && options.noAi === void 0) {
-			const confirmAi = await p.confirm({
-				message: "Configure AI agent support (Claude/Cursor skills, .mcp.json, AGENTS.md)?",
-				initialValue: true
-			});
-			if (!p.isCancel(confirmAi)) options.ai = confirmAi;
+		if (dictionaryFiles.has(issue.file) && issue.dictionary && !diag.name) diag.name = issue.dictionary;
+		addIssue(diag, issue);
+	}
+	for (const { file, message } of generated.stale) {
+		let diag = byFile.get(file);
+		if (!diag) {
+			diag = {
+				file,
+				errors: [],
+				warnings: [],
+				annotations: []
+			};
+			byFile.set(file, diag);
 		}
-	} else logger.info(`Auto-detected framework: ${pc.bold(framework)} (${detected.matchedRule})`);
-	const localeList = Array.from(/* @__PURE__ */ new Set([defaultLocale, ...localesInput.split(",").map((s) => s.trim()).filter(Boolean)]));
-	const configPath = fs.existsSync(path.join(root, "dialex.config.ts")) ? path.join(root, "dialex.config.ts") : fs.existsSync(path.join(root, "i18n.config.ts")) ? path.join(root, "i18n.config.ts") : path.join(root, "dialex.config.ts");
-	const configFileName = path.basename(configPath);
-	try {
-		if (fs.existsSync(configPath)) {
-			const mod = await loadFile(configPath);
-			if (mod && mod.exports.default) {
-				if (mod.exports.default.$args && mod.exports.default.$args[0]) {
-					mod.exports.default.$args[0].defaultLocale = defaultLocale;
-					mod.exports.default.$args[0].locales = localeList;
-				}
-				await writeFile(mod, configPath);
-				logger.success(`Updated ${pc.bold(configFileName)} via Magicast`);
+		diag.errors.push(message);
+		diag.annotations.push({
+			level: "error",
+			message
+		});
+	}
+	const diagnostics = [...byFile.values()];
+	const totalIssues = diagnostics.reduce((n, d) => n + d.errors.length, 0);
+	const totalWarnings = diagnostics.reduce((n, d) => n + d.warnings.length, 0);
+	const reported = diagnostics.filter((d) => d.errors.length > 0 || d.warnings.length > 0);
+	const result = {
+		success: totalIssues === 0,
+		diagnostics: reported,
+		totalIssues,
+		totalWarnings,
+		fixed
+	};
+	if (options.github) for (const d of reported) for (const a of d.annotations) {
+		const location = `file=${d.file}${a.line ? `,line=${a.line}` : ""}`;
+		console.log(`::${a.level} ${location},title=dialex::${escapeAnnotation(a.message)}`);
+	}
+	if (quiet) console.log(JSON.stringify(result, null, 2));
+	else if (reported.length > 0) {
+		logger.log("");
+		if (totalIssues > 0) logger.error(`Found ${totalIssues} issue${totalIssues === 1 ? "" : "s"} across ${reported.filter((d) => d.errors.length > 0).length} file${reported.length === 1 ? "" : "s"}:`);
+		logger.log("");
+		for (const d of reported) {
+			logger.log(`  ${pc.underline(pc.bold(d.file))} ${d.name ? pc.dim(`(${d.name})`) : ""}:`);
+			for (const a of d.annotations) {
+				const where = a.line ? pc.dim(`:${a.line}`) : "";
+				const mark = a.level === "error" ? pc.red("✖") : pc.yellow("⚠");
+				logger.log(`    ${mark} ${a.message}${where}`);
 			}
-		} else {
-			const mod = parseModule(`import { defineConfig } from "dialexjs";
-
-export default defineConfig({});
-`);
-			mod.exports.default.$args[0].defaultLocale = defaultLocale;
-			mod.exports.default.$args[0].locales = localeList;
-			await writeFile(mod, configPath);
-			logger.success(`Created ${pc.bold(configFileName)} via Magicast`);
+			logger.log("");
 		}
-	} catch (err) {
-		logger.warn(`Magicast config update notice: ${err.message || String(err)}`);
-		const fallback = `import { defineConfig } from "dialexjs";
-
-export default defineConfig({
-  defaultLocale: "${defaultLocale}",
-  locales: [${localeList.map((l) => `"${l}"`).join(", ")}],
-});
-`;
-		fs.writeFileSync(configPath, fallback, "utf-8");
 	}
-	if (framework === "react" || framework === "vue") {
-		const possibleViteConfigs = [
-			path.join(root, "vite.config.ts"),
-			path.join(root, "vite.config.js"),
-			path.join(root, "vite.config.mjs")
-		];
-		for (const vConfig of possibleViteConfigs) if (fs.existsSync(vConfig)) try {
-			const vMod = await loadFile(vConfig);
-			addVitePlugin(vMod, {
-				from: "dialexjs/vite",
-				imported: "dialexPlugin",
-				constructor: "dialexPlugin"
-			});
-			await writeFile(vMod, vConfig);
-			logger.success(`Injected dialexPlugin() into ${pc.bold(path.basename(vConfig))} via Magicast`);
-			break;
-		} catch {}
+	if (totalIssues > 0) {
+		if (options.exitOnError !== false) process.exit(1);
+		return result;
 	}
-	if (framework === "nuxt") {
-		const nuxtConfig = [
-			"nuxt.config.ts",
-			"nuxt.config.js",
-			"nuxt.config.mjs"
-		].map((f) => path.join(root, f)).find((f) => fs.existsSync(f));
-		if (nuxtConfig) try {
-			const nMod = await loadFile(nuxtConfig);
-			addNuxtModule(nMod, "dialexjs/nuxt", "dialex", {
-				defaultLocale,
-				locales: localeList
+	if (!quiet) {
+		const warningNote = totalWarnings > 0 ? ` (${totalWarnings} warning${totalWarnings === 1 ? "" : "s"})` : "";
+		logger.success(`All ${files.length} dictionary file${files.length === 1 ? "" : "s"} passed checks with 0 issues${warningNote}!`);
+	}
+	return result;
+}
+//#endregion
+//#region src/commands/export.ts
+const escapeXml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const csvCell = (value) => /[",\r\n]/.test(value) ? `"${value.replace(/"/g, "\"\"")}"` : value;
+async function runExport(options = {}) {
+	const root = options.cwd || process.cwd();
+	const format = options.format || "json";
+	if (![
+		"json",
+		"csv",
+		"xliff"
+	].includes(format)) throw new Error(`Unsupported format "${format}". Use json, csv, or xliff.`);
+	const outDir = path.resolve(root, options.out || "dialex-export");
+	const project = await loadProject(root, options.config);
+	const defaultLocale = project.config.defaultLocale || "en";
+	const table = /* @__PURE__ */ new Map();
+	const orderedKeys = /* @__PURE__ */ new Set();
+	let skippedFunctions = 0;
+	const localeSet = new Set(project.config.locales || []);
+	for (const { df } of project.dictionaries) listLocales(df).forEach((l) => localeSet.add(l));
+	let locales = Array.from(localeSet);
+	if (options.locale && options.locale.length > 0) locales = locales.filter((l) => options.locale.includes(l) || l === defaultLocale);
+	for (const locale of locales) table.set(locale, /* @__PURE__ */ new Map());
+	for (const { name, df } of project.dictionaries) for (const locale of listLocales(df)) {
+		if (!table.has(locale)) continue;
+		for (const leaf of listLeaves(df, locale)) if (leaf.kind === "string" && leaf.value !== void 0) {
+			const key = toKey(name, leaf.path);
+			table.get(locale).set(key, leaf.value);
+			orderedKeys.add(key);
+		} else if (locale === defaultLocale) skippedFunctions++;
+	}
+	fs.mkdirSync(outDir, { recursive: true });
+	const files = [];
+	const write = (name, content) => {
+		const file = path.join(outDir, name);
+		fs.writeFileSync(file, content, "utf-8");
+		files.push(path.relative(root, file));
+	};
+	if (format === "json") for (const [locale, values] of table) write(`${locale}.json`, JSON.stringify(Object.fromEntries(values), null, 2) + "\n");
+	else if (format === "csv") write("translations.csv", [["key", ...table.keys()].map(csvCell).join(","), ...[...orderedKeys].map((key) => [key, ...[...table.values()].map((v) => v.get(key) ?? "")].map(csvCell).join(","))].join("\n") + "\n");
+	else {
+		const source = table.get(defaultLocale);
+		for (const [locale, values] of table) {
+			if (locale === defaultLocale) continue;
+			const units = [...orderedKeys].map((key) => {
+				const src = source?.get(key) ?? "";
+				const target = values.get(key);
+				const targetXml = target === void 0 ? "" : `<target>${escapeXml(target)}</target>`;
+				return `      <trans-unit id="${escapeXml(key)}"><source>${escapeXml(src)}</source>${targetXml}</trans-unit>`;
 			});
-			await writeFile(nMod, nuxtConfig);
-			logger.success(`Registered dialexjs/nuxt in ${pc.bold(path.basename(nuxtConfig))} via Magicast`);
-		} catch {
-			logger.warn("Could not update the Nuxt config; add the dialexjs/nuxt module manually.");
+			write(`${locale}.xlf`, `<?xml version="1.0" encoding="UTF-8"?>
+<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
+  <file original="dialex" source-language="${escapeXml(defaultLocale)}" target-language="${escapeXml(locale)}" datatype="plaintext">
+    <body>
+${units.join("\n")}
+    </body>
+  </file>
+</xliff>
+`);
 		}
 	}
-	const targetDir = fs.existsSync(path.join(root, "src")) ? path.join(root, "src") : root;
-	const dictPath = path.join(targetDir, "home.content.ts");
-	if (!fs.existsSync(dictPath)) {
-		const dictContent = `import { defineDictionary } from "dialexjs";
-
-export default defineDictionary("home", {
-${localeList.map((loc) => `  ${loc}: {
-    title: "Welcome to Dialex (${loc})!",
-    description: "Type-safe internationalization.",
-    greeting: (name: string) => "Hello, " + name + "!",
-  },`).join("\n")}
-});
-`;
-		fs.writeFileSync(dictPath, dictContent, "utf-8");
-		logger.success(`Created starter dictionary at ${pc.bold(path.relative(root, dictPath))}`);
-	} else logger.info("home.content.ts already exists, skipping creation.");
-	generateDictionaries(root);
-	logger.success("Generated types and standalone dictionary registry!");
-	const pkgPath = path.join(root, "package.json");
-	if (fs.existsSync(pkgPath)) try {
-		const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-		const added = addRequiredPackages(pkg);
-		pkg.scripts = pkg.scripts || {};
-		const addScript = !pkg.scripts["dx:generate"];
-		if (addScript) pkg.scripts["dx:generate"] = "dx generate";
-		if (added.length > 0 || addScript) fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
-		if (added.length > 0) {
-			logger.success(`Added ${added.join(" and ")} to package.json`);
-			logger.info(`Run ${pc.bold(installCommand(root))} to install them.`);
-		}
-		if (addScript) logger.success("Added \"dx:generate\" script to package.json");
-	} catch {
-		logger.warn("Could not update package.json; add dialexjs and @dialexjs/cli manually.");
-	}
-	else logger.warn("No package.json found; install dialexjs and @dialexjs/cli in your project.");
-	if (options.ai === true || options.yes && options.ai !== false && options.noAi !== true) try {
-		const skillDir = path.join(root, ".agents/skills/dialex");
-		fs.mkdirSync(skillDir, { recursive: true });
-		fs.writeFileSync(path.join(skillDir, "SKILL.md"), `---
-name: dialex
-description: Guide for internationalizing JavaScript and TypeScript apps with Dialex. Use when adding translations, creating content dictionaries, configuring locales, or using Dialex with frameworks like Next.js, React, Express, Hono, Fastify, SvelteKit, and Nuxt.
----
-
-# Dialex Internationalization
-
-Dialex is a high-performance, type-safe internationalization toolchain for JavaScript and TypeScript.
-
-## Core Concepts
-- Dictionaries are defined with \`defineDictionary("name", { ... })\` in \`*.content.ts\` files.
-- Keys must match across all locales.
-- ICU message syntax is supported for plurals and selects.
-- Parity is validated at compile time with \`dialex check\`.
-
-## Useful Commands
-- \`dialex check --json\`: Check dictionary parity and references.
-- \`dialex check --fix\`: Automatically insert missing keys marked with [TODO].
-- \`dialex generate\`: Rebuild standalone dictionary bundle and types.
-- \`dialex translate --locale <locale>\`: Automatically translate missing keys.
-`, "utf-8");
-		const mcpConfigPath = path.join(root, ".mcp.json");
-		let mcpConfig = {};
-		if (fs.existsSync(mcpConfigPath)) try {
-			mcpConfig = JSON.parse(fs.readFileSync(mcpConfigPath, "utf-8"));
-		} catch {
-			mcpConfig = {};
-		}
-		mcpConfig.mcpServers = mcpConfig.mcpServers || {};
-		mcpConfig.mcpServers.dialex = mcpConfig.mcpServers.dialex || {
-			command: "npx",
-			args: ["@dialexjs/mcp"]
-		};
-		fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf-8");
-		const agentsMdPath = path.join(root, "AGENTS.md");
-		const dialexAgentSnippet = `
-## Internationalization (Dialex)
-
-This project uses [Dialex](https://github.com/awaiden/dialex) for type-safe internationalization.
-- Dictionaries are in \`*.content.ts\` files using \`defineDictionary\`.
-- Run \`dialex check --json\` to verify parity.
-- Run \`dialex check --fix\` to insert missing keys marked with \`[TODO]\`.
-- Run \`dx generate\` (alias of \`dialex\`) or \`npm run dx:generate\` to compile dictionary bundles and update types.
-`;
-		if (!fs.existsSync(agentsMdPath)) fs.writeFileSync(agentsMdPath, dialexAgentSnippet.trimStart(), "utf-8");
-		else {
-			const existing = fs.readFileSync(agentsMdPath, "utf-8");
-			if (!existing.includes("Dialex")) fs.writeFileSync(agentsMdPath, existing.trimEnd() + "\n" + dialexAgentSnippet, "utf-8");
-		}
-		logger.success("Configured AI assistant support (.agents/skills, .mcp.json, AGENTS.md)");
-	} catch (err) {
-		logger.warn(`Could not finish AI configuration: ${err.message || String(err)}`);
+	const quiet = options.json === true;
+	const result = {
+		success: true,
+		files,
+		keys: orderedKeys.size,
+		skippedFunctions,
+		skippedFiles: project.unsupported
+	};
+	if (quiet) console.log(JSON.stringify(result, null, 2));
+	else {
+		logger.success(`Exported ${orderedKeys.size} key${orderedKeys.size === 1 ? "" : "s"} to ${files.length} ${format} file${files.length === 1 ? "" : "s"} in ${path.relative(root, outDir) || "."}`);
+		if (skippedFunctions > 0) logger.warn(`${skippedFunctions} function value${skippedFunctions === 1 ? "" : "s"} skipped (not translatable as text)`);
+		for (const file of project.unsupported) logger.warn(`Skipped ${file}: unsupported dictionary shape`);
 	}
-	logger.log("");
-	logger.info(pc.bold(`Quick start for ${framework.toUpperCase()}:`));
-	switch (framework) {
-		case "hono":
-			logger.log(`
-import { Hono } from "hono";
-import { dialex } from "dialexjs/hono";
-import dictionaries from "./src/dialex.generated.js";
-
-const app = new Hono();
-app.use("*", dialex({ dictionaries }));
-
-app.get("/", (c) => {
-  const dict = c.var.getDictionary("home");
-  return c.json({ title: dict.title });
-});
-`);
-			break;
-		case "fastify":
-			logger.log(`
-import Fastify from "fastify";
-import { dialexPlugin } from "dialexjs/fastify";
-import dictionaries from "./src/dialex.generated.js";
-
-const app = Fastify();
-await app.register(dialexPlugin, { dictionaries });
-
-app.get("/", (req) => {
-  const dict = req.getDictionary("home");
-  return { title: dict.title };
-});
-`);
-			break;
-		case "express":
-			logger.log(`
-import express from "express";
-import { dialex } from "dialexjs/express";
-import dictionaries from "./src/dialex.generated.js";
-
-const app = express();
-app.use(dialex({ dictionaries }));
-
-app.get("/", (req, res) => {
-  const dict = req.getDictionary("home");
-  res.json({ title: dict.title });
-});
-`);
-			break;
-		case "koa":
-			logger.log(`
-import Koa from "koa";
-import { dialex } from "dialexjs/koa";
-import dictionaries from "./src/dialex.generated.js";
-
-const app = new Koa();
-app.use(dialex({ dictionaries }));
-
-app.use((ctx) => {
-  const dict = ctx.getDictionary("home");
-  ctx.body = { title: dict.title };
-});
-`);
-			break;
-		case "nestjs":
-			logger.log(`
-import { Module } from "@nestjs/common";
-import { DialexModule } from "dialexjs/nestjs";
-import dictionaries from "./src/dialex.generated.js";
-
-@Module({
-  imports: [DialexModule.forRoot({ dictionaries })],
-})
-export class AppModule {}
-`);
-			break;
-		case "next":
-			logger.log(`
-import { getDictionary } from "dialexjs/server";
-
-export default async function Page({ params }: { params: Promise<{ locale: string }> }) {
-  const { locale = "en" } = await params;
-  const dict = getDictionary("home", locale);
-  return <h1>{dict.title}</h1>;
+	return result;
 }
-`);
-			break;
-		case "elysia":
-			logger.log(`
-import { Elysia } from "elysia";
-import { dialex } from "dialexjs/elysia";
-import dictionaries from "./src/dialex.generated.js";
-
-new Elysia()
-  .use(dialex({ dictionaries }))
-  .get("/", ({ getDictionary }) => ({ title: getDictionary("home").title }))
-  .listen(3000);
-`);
-			break;
-		case "sveltekit":
-			logger.log(`
-// src/hooks.server.ts
-import { dialexHandle } from "dialexjs/sveltekit";
-import dictionaries from "./dialex.generated.js";
-
-export const handle = dialexHandle({ dictionaries });
-
-// src/app.html: <html lang="%dialex.lang%">
-// In load functions: locals.getDictionary("home")
-`);
-			break;
-		case "astro":
-			logger.log(`
-// src/middleware.ts
-import { dialex } from "dialexjs/astro";
-import dictionaries from "./dialex.generated.js";
-
-export const onRequest = dialex({ dictionaries });
-
-// In pages: Astro.locals.getDictionary("home")
-`);
-			break;
-		case "vue":
-			logger.log(`
-// src/main.ts
-import { createApp } from "vue";
-import { createDialex } from "dialexjs/vue";
-import App from "./App.vue";
-
-createApp(App).use(createDialex()).mount("#app");
-
-// In components: const dict = useDictionary("home")
-`);
-			break;
-		case "nuxt":
-			logger.log(`
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ["dialexjs/nuxt"],
-});
-
-// In components: const dict = useDictionary("home")
-`);
-			break;
-		default: logger.log(`
-Import dictionaries and register your framework middleware to begin!
-Run \`npm run dx:generate\` whenever you add new dictionary files.
-`);
+//#endregion
+//#region src/commands/import.ts
+const unescapeXml = (value) => value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+function parseCsv(text) {
+	const rows = [];
+	let row = [];
+	let cell = "";
+	let quoted = false;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		if (quoted) {
+			if (ch === "\"" && text[i + 1] === "\"") {
+				cell += "\"";
+				i++;
+			} else if (ch === "\"") quoted = false;
+			else cell += ch;
+		} else if (ch === "\"") quoted = true;
+		else if (ch === ",") {
+			row.push(cell);
+			cell = "";
+		} else if (ch === "\n" || ch === "\r") {
+			if (ch === "\r" && text[i + 1] === "\n") i++;
+			row.push(cell);
+			rows.push(row);
+			row = [];
+			cell = "";
+		} else cell += ch;
 	}
-	if (isInteractive) p.outro(pc.green("✔ dialex is configured and ready to go!"));
+	if (cell !== "" || row.length > 0) {
+		row.push(cell);
+		rows.push(row);
+	}
+	return rows.filter((r) => r.some((c) => c !== ""));
 }
-//#endregion
-//#region src/commands/check.ts
-const DICTIONARY_IGNORE = [
-	"**/node_modules/**",
-	"**/dist/**",
-	"**/.next/**"
-];
-function addIssue(diag, issue) {
-	const level = issue.level === "error" ? "error" : "warning";
-	(level === "error" ? diag.errors : diag.warnings).push(issue.message);
-	diag.annotations.push({
-		level,
-		message: issue.message,
-		line: issue.range ? issue.range.start.line + 1 : void 0
-	});
+function parseEntries(content, format, fallbackLocale) {
+	const entries = [];
+	if (format === "json") {
+		const data = JSON.parse(content);
+		if (Object.keys(data).length > 0 && Object.values(data).every((v) => v && typeof v === "object" && !Array.isArray(v))) {
+			for (const [locale, values] of Object.entries(data)) for (const [key, value] of Object.entries(values)) if (typeof value === "string") entries.push({
+				locale,
+				key,
+				value
+			});
+		} else {
+			if (!fallbackLocale) throw new Error("Cannot infer the locale; pass --locale.");
+			for (const [key, value] of Object.entries(data)) if (typeof value === "string") entries.push({
+				locale: fallbackLocale,
+				key,
+				value
+			});
+		}
+	} else if (format === "csv") {
+		const [header, ...rows] = parseCsv(content);
+		if (!header || header[0] !== "key") throw new Error("CSV must start with a \"key\" column.");
+		for (const row of rows) header.slice(1).forEach((locale, i) => {
+			const value = row[i + 1];
+			if (value !== void 0 && value !== "") entries.push({
+				locale,
+				key: row[0],
+				value
+			});
+		});
+	} else {
+		const locale = /target-language="([^"]*)"/.exec(content)?.[1] ?? fallbackLocale;
+		if (!locale) throw new Error("Cannot infer the locale; pass --locale.");
+		for (const match of content.matchAll(/<trans-unit\b[^>]*\bid="([^"]*)"[^>]*>([\s\S]*?)<\/trans-unit>/g)) {
+			const target = /<target\b[^>]*>([\s\S]*?)<\/target>/.exec(match[2])?.[1];
+			if (target !== void 0 && target !== "") entries.push({
+				locale,
+				key: unescapeXml(match[1]),
+				value: unescapeXml(target)
+			});
+		}
+	}
+	return entries;
+}
+function inferFormat(file) {
+	const ext = path.extname(file).toLowerCase();
+	if (ext === ".json") return "json";
+	if (ext === ".csv") return "csv";
+	if (ext === ".xlf" || ext === ".xliff") return "xliff";
+	throw new Error(`Cannot infer format from "${ext}". Pass --format json|csv|xliff.`);
 }
 /**
-* Inserts keys that exist in one locale but not in another, copying the default-locale value
-* (strings get a `[TODO]` prefix). Returns how many keys were inserted.
+* Why `value` must not replace the current text, if it is an ICU message that is invalid or uses
+* different arguments than the same key in another locale.
 */
-async function applyFixes(files, configuredLocales, defaultLocale) {
-	let fixed = 0;
-	for (const file of files) {
-		const df = await loadDictionaryFile(file);
-		if (!df?.complete) continue;
-		const present = listLocales(df);
-		const targets = Array.from(/* @__PURE__ */ new Set([...present, ...configuredLocales]));
-		const sourceOrder = [defaultLocale, ...present.filter((l) => l !== defaultLocale)].filter((l) => present.includes(l));
-		const allPaths = /* @__PURE__ */ new Map();
-		for (const locale of present) for (const leaf of listLeaves(df, locale)) allPaths.set(leaf.path.join("\0"), leaf.path);
-		let changed = false;
-		for (const target of targets) for (const leafPath of allPaths.values()) {
-			if (hasPath(df, target, leafPath)) continue;
-			const source = sourceOrder.find((l) => l !== target && hasPath(df, l, leafPath));
-			if (source && copyLeaf(df, source, target, leafPath, (v) => `[TODO] ${v}`)) {
-				fixed++;
-				changed = true;
-			}
+function icuProblem(df, defaultLocale, locale, keyPath, value) {
+	if (!value.includes("{")) return void 0;
+	let signature;
+	try {
+		signature = argumentSignature(parseMessage(value));
+	} catch (error) {
+		return `invalid ICU: ${error.message}`;
+	}
+	const locales = listLocales(df);
+	for (const other of [defaultLocale, ...locales.filter((l) => l !== defaultLocale)]) {
+		if (other === locale) continue;
+		const reference = getString(df, other, keyPath);
+		if (!reference?.includes("{")) continue;
+		try {
+			const expected = argumentSignature(parseMessage(reference));
+			return expected === signature ? void 0 : `arguments differ from "${other}": expected ${expected || "none"}, found ${signature || "none"}`;
+		} catch {
+			continue;
 		}
-		if (changed) await saveDictionaryFile(df);
 	}
-	return fixed;
 }
-function escapeAnnotation(value) {
-	return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
-}
-async function runCheck(options = {}) {
+async function runImport(options) {
 	const root = options.cwd || process.cwd();
+	const file = path.resolve(root, options.file);
+	const format = options.format || inferFormat(file);
+	const fallbackLocale = options.locale ?? path.basename(file, path.extname(file));
+	const entries = parseEntries(fs.readFileSync(file, "utf-8"), format, options.locale ?? fallbackLocale);
+	const project = await loadProject(root, options.config);
+	const byName = new Map(project.dictionaries.map((d) => [d.name, d]));
 	const quiet = options.json === true;
-	const inlineConfig = options.config ? { configFile: options.config } : {};
-	const config = resolveDialexConfig(root, inlineConfig);
-	const include = config.include || "**/*.content.ts";
-	const configuredLocales = config.locales || [];
-	const defaultLocale = config.defaultLocale || "en";
-	const files = fg.sync(include, {
-		cwd: root,
-		absolute: true,
-		ignore: DICTIONARY_IGNORE
-	});
-	if (files.length === 0) {
-		if (!quiet) {
-			const patternStr = Array.isArray(include) ? include.join(", ") : include;
-			logger.warn(`No dictionary files found matching "${patternStr}".`);
+	const result = {
+		success: true,
+		created: 0,
+		updated: 0,
+		skipped: [],
+		rejected: [],
+		unknown: [],
+		errors: []
+	};
+	const touched = /* @__PURE__ */ new Set();
+	const lockInUse = readLock(root) !== void 0;
+	const sourceLocale = readLock(root)?.sourceLocale ?? project.config.defaultLocale ?? "en";
+	const { lock } = lockFor(root, sourceLocale);
+	let recorded = 0;
+	for (const { locale, key, value } of entries) {
+		const [name, ...keyPath] = key.split(".");
+		const dict = byName.get(name);
+		if (!dict || keyPath.length === 0) {
+			result.unknown.push(key);
+			continue;
 		}
-		const empty = {
-			success: true,
-			diagnostics: [],
-			totalIssues: 0,
-			totalWarnings: 0,
-			fixed: 0
+		if (!listLocales(dict.df).some((l) => hasPath(dict.df, l, keyPath)) && !options.allowNew) {
+			result.unknown.push(key);
+			continue;
+		}
+		const problem = icuProblem(dict.df, project.config.defaultLocale ?? "en", locale, keyPath, value);
+		if (problem) {
+			result.rejected.push(`${locale}:${key} (${problem})`);
+			continue;
+		}
+		const outcome = setString(dict.df, locale, keyPath, value);
+		if (outcome === "skipped") result.skipped.push(`${locale}:${key}`);
+		else {
+			result[outcome]++;
+			touched.add(dict.rel);
+			const sourceText = getString(dict.df, sourceLocale, keyPath);
+			if (lockInUse && locale !== sourceLocale && sourceText !== void 0) {
+				record(lock, locale, key, sourceText);
+				recorded++;
+			}
+		}
+	}
+	if (recorded > 0) writeLock(root, lock);
+	for (const dict of project.dictionaries) if (touched.has(dict.rel)) await saveDictionaryFile(dict.df);
+	if (result.rejected.length > 0) result.success = false;
+	if (quiet) console.log(JSON.stringify(result, null, 2));
+	else {
+		logger.success(`Imported ${result.created + result.updated} value${result.created + result.updated === 1 ? "" : "s"} (${result.created} added, ${result.updated} updated)`);
+		if (result.unknown.length > 0) logger.warn(`${result.unknown.length} unknown key${result.unknown.length === 1 ? "" : "s"} ignored (use --allow-new to add): ${result.unknown.slice(0, 5).join(", ")}${result.unknown.length > 5 ? ", ..." : ""}`);
+		if (result.rejected.length > 0) logger.warn(`${result.rejected.length} value${result.rejected.length === 1 ? "" : "s"} rejected: ${result.rejected.slice(0, 5).join("; ")}`);
+		if (result.skipped.length > 0) logger.warn(`${result.skipped.length} non-text value${result.skipped.length === 1 ? "" : "s"} left unchanged: ${result.skipped.slice(0, 5).join(", ")}`);
+	}
+	return result;
+}
+//#endregion
+//#region src/utils/detector.ts
+/**
+* Automatically inspects package.json dependencies and configuration files
+* to detect the active framework in the target project.
+*/
+function detectFramework(root) {
+	const pkgPath = path.join(root, "package.json");
+	if (fs.existsSync(pkgPath)) try {
+		const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+		const allDeps = {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+		if ("nuxt" in allDeps) return {
+			framework: "nuxt",
+			confidence: "high",
+			matchedRule: "package.json dependencies (nuxt)"
+		};
+		if ("@sveltejs/kit" in allDeps) return {
+			framework: "sveltekit",
+			confidence: "high",
+			matchedRule: "package.json dependencies (@sveltejs/kit)"
+		};
+		if ("astro" in allDeps) return {
+			framework: "astro",
+			confidence: "high",
+			matchedRule: "package.json dependencies (astro)"
+		};
+		if ("next" in allDeps) return {
+			framework: "next",
+			confidence: "high",
+			matchedRule: "package.json dependencies (next)"
+		};
+		if ("@nestjs/core" in allDeps || "@nestjs/common" in allDeps) return {
+			framework: "nestjs",
+			confidence: "high",
+			matchedRule: "package.json dependencies (@nestjs/core)"
+		};
+		if ("fastify" in allDeps) return {
+			framework: "fastify",
+			confidence: "high",
+			matchedRule: "package.json dependencies (fastify)"
+		};
+		if ("koa" in allDeps) return {
+			framework: "koa",
+			confidence: "high",
+			matchedRule: "package.json dependencies (koa)"
+		};
+		if ("express" in allDeps) return {
+			framework: "express",
+			confidence: "high",
+			matchedRule: "package.json dependencies (express)"
+		};
+		if ("elysia" in allDeps) return {
+			framework: "elysia",
+			confidence: "high",
+			matchedRule: "package.json dependencies (elysia)"
+		};
+		if ("hono" in allDeps) return {
+			framework: "hono",
+			confidence: "high",
+			matchedRule: "package.json dependencies (hono)"
+		};
+		if ("vue" in allDeps && !("react" in allDeps)) return {
+			framework: "vue",
+			confidence: "high",
+			matchedRule: "package.json dependencies (vue)"
 		};
-		if (quiet) console.log(JSON.stringify(empty, null, 2));
-		return empty;
-	}
-	let fixed = 0;
-	if (options.fix) {
-		fixed = await applyFixes(files, configuredLocales, defaultLocale);
-		if (fixed > 0 && !quiet) logger.success(`Inserted ${fixed} missing key${fixed === 1 ? "" : "s"} marked ${TODO_PREFIX.trim()}`);
-	}
-	const analysis = await analyzeProject({
-		root,
-		config,
-		src: options.src && options.src.length > 0 ? options.src : void 0,
-		runtime: true
-	});
-	const byFile = /* @__PURE__ */ new Map();
-	const dictionaryFiles = new Set(analysis.files);
-	for (const issue of analysis.issues) {
-		if (issue.level === "info") continue;
-		const rel = path.relative(root, issue.file);
-		let diag = byFile.get(rel);
-		if (!diag) {
-			diag = {
-				file: rel,
-				errors: [],
-				warnings: [],
-				annotations: []
-			};
-			byFile.set(rel, diag);
-		}
-		if (dictionaryFiles.has(issue.file) && issue.dictionary && !diag.name) diag.name = issue.dictionary;
-		addIssue(diag, issue);
-	}
-	const diagnostics = [...byFile.values()];
-	const totalIssues = diagnostics.reduce((n, d) => n + d.errors.length, 0);
-	const totalWarnings = diagnostics.reduce((n, d) => n + d.warnings.length, 0);
-	const reported = diagnostics.filter((d) => d.errors.length > 0 || d.warnings.length > 0);
-	const result = {
-		success: totalIssues === 0,
-		diagnostics: reported,
-		totalIssues,
-		totalWarnings,
-		fixed
+		if ("react" in allDeps || "vite" in allDeps) return {
+			framework: "react",
+			confidence: "high",
+			matchedRule: "package.json dependencies (react/vite)"
+		};
+	} catch {}
+	if (fs.existsSync(path.join(root, "next.config.js")) || fs.existsSync(path.join(root, "next.config.mjs")) || fs.existsSync(path.join(root, "next.config.ts"))) return {
+		framework: "next",
+		confidence: "medium",
+		matchedRule: "next.config file presence"
 	};
-	if (options.github) for (const d of reported) for (const a of d.annotations) {
-		const location = `file=${d.file}${a.line ? `,line=${a.line}` : ""}`;
-		console.log(`::${a.level} ${location},title=dialex::${escapeAnnotation(a.message)}`);
-	}
-	if (quiet) console.log(JSON.stringify(result, null, 2));
-	else if (reported.length > 0) {
-		logger.log("");
-		if (totalIssues > 0) logger.error(`Found ${totalIssues} issue${totalIssues === 1 ? "" : "s"} across ${reported.filter((d) => d.errors.length > 0).length} file${reported.length === 1 ? "" : "s"}:`);
-		logger.log("");
-		for (const d of reported) {
-			logger.log(`  ${pc.underline(pc.bold(d.file))} ${d.name ? pc.dim(`(${d.name})`) : ""}:`);
-			for (const a of d.annotations) {
-				const where = a.line ? pc.dim(`:${a.line}`) : "";
-				const mark = a.level === "error" ? pc.red("✖") : pc.yellow("⚠");
-				logger.log(`    ${mark} ${a.message}${where}`);
-			}
-			logger.log("");
-		}
+	for (const [framework, base] of [
+		["nuxt", "nuxt.config"],
+		["sveltekit", "svelte.config"],
+		["astro", "astro.config"]
+	]) if ([
+		"js",
+		"mjs",
+		"ts"
+	].some((ext) => fs.existsSync(path.join(root, `${base}.${ext}`)))) return {
+		framework,
+		confidence: "medium",
+		matchedRule: `${base} file presence`
+	};
+	if (fs.existsSync(path.join(root, "vite.config.js")) || fs.existsSync(path.join(root, "vite.config.mjs")) || fs.existsSync(path.join(root, "vite.config.ts"))) return {
+		framework: "react",
+		confidence: "medium",
+		matchedRule: "vite.config file presence"
+	};
+	return {
+		framework: "hono",
+		confidence: "fallback",
+		matchedRule: "default fallback"
+	};
+}
+//#endregion
+//#region src/utils/package-json.ts
+/** Version of this CLI, which the other Dialex packages share. Read from the nearest package.json. */
+function cliVersion() {
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 4; i++) {
+		try {
+			const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8"));
+			if (pkg.name === "@dialexjs/cli") return pkg.version;
+		} catch {}
+		dir = path.dirname(dir);
 	}
-	if (totalIssues > 0) {
-		if (options.exitOnError !== false) process.exit(1);
-		return result;
+}
+/** The install command for the package manager a project uses, judged by its lockfile. */
+function installCommand(root) {
+	const has = (file) => fs.existsSync(path.join(root, file));
+	if (has("bun.lock") || has("bun.lockb")) return "bun install";
+	if (has("pnpm-lock.yaml")) return "pnpm install";
+	if (has("yarn.lock")) return "yarn install";
+	return "npm install";
+}
+const sorted = (deps) => Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)));
+/**
+* Adds the packages a Dialex project needs: `dialexjs` as a dependency and the CLI as a dev
+* dependency (the `dx:generate` script runs it). Packages already listed anywhere are left alone.
+* Returns the names it added.
+*/
+function addRequiredPackages(pkg, version = cliVersion()) {
+	const range = version ? `^${version}` : "latest";
+	const listed = (name) => [
+		pkg.dependencies,
+		pkg.devDependencies,
+		pkg.peerDependencies
+	].some((deps) => deps && name in deps);
+	const added = [];
+	if (!listed("dialexjs")) {
+		pkg.dependencies = sorted({
+			...pkg.dependencies,
+			dialexjs: range
+		});
+		added.push("dialexjs");
 	}
-	if (!quiet) {
-		const warningNote = totalWarnings > 0 ? ` (${totalWarnings} warning${totalWarnings === 1 ? "" : "s"})` : "";
-		logger.success(`All ${files.length} dictionary file${files.length === 1 ? "" : "s"} passed checks with 0 issues${warningNote}!`);
+	if (!listed("@dialexjs/cli")) {
+		pkg.devDependencies = sorted({
+			...pkg.devDependencies,
+			"@dialexjs/cli": range
+		});
+		added.push("@dialexjs/cli");
 	}
-	return result;
+	return added;
 }
 //#endregion
-//#region src/commands/export.ts
-const escapeXml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-const csvCell = (value) => /[",\r\n]/.test(value) ? `"${value.replace(/"/g, "\"\"")}"` : value;
-async function runExport(options = {}) {
+//#region src/commands/init.ts
+async function runInit(options = {}) {
 	const root = options.cwd || process.cwd();
-	const format = options.format || "json";
-	if (![
-		"json",
-		"csv",
-		"xliff"
-	].includes(format)) throw new Error(`Unsupported format "${format}". Use json, csv, or xliff.`);
-	const outDir = path.resolve(root, options.out || "dialex-export");
-	const project = await loadProject(root, options.config);
-	const defaultLocale = project.config.defaultLocale || "en";
-	const table = /* @__PURE__ */ new Map();
-	const orderedKeys = /* @__PURE__ */ new Set();
-	let skippedFunctions = 0;
-	const localeSet = new Set(project.config.locales || []);
-	for (const { df } of project.dictionaries) listLocales(df).forEach((l) => localeSet.add(l));
-	let locales = Array.from(localeSet);
-	if (options.locale && options.locale.length > 0) locales = locales.filter((l) => options.locale.includes(l) || l === defaultLocale);
-	for (const locale of locales) table.set(locale, /* @__PURE__ */ new Map());
-	for (const { name, df } of project.dictionaries) for (const locale of listLocales(df)) {
-		if (!table.has(locale)) continue;
-		for (const leaf of listLeaves(df, locale)) if (leaf.kind === "string" && leaf.value !== void 0) {
-			const key = toKey(name, leaf.path);
-			table.get(locale).set(key, leaf.value);
-			orderedKeys.add(key);
-		} else if (locale === defaultLocale) skippedFunctions++;
-	}
-	fs.mkdirSync(outDir, { recursive: true });
-	const files = [];
-	const write = (name, content) => {
-		const file = path.join(outDir, name);
-		fs.writeFileSync(file, content, "utf-8");
-		files.push(path.relative(root, file));
-	};
-	if (format === "json") for (const [locale, values] of table) write(`${locale}.json`, JSON.stringify(Object.fromEntries(values), null, 2) + "\n");
-	else if (format === "csv") write("translations.csv", [["key", ...table.keys()].map(csvCell).join(","), ...[...orderedKeys].map((key) => [key, ...[...table.values()].map((v) => v.get(key) ?? "")].map(csvCell).join(","))].join("\n") + "\n");
-	else {
-		const source = table.get(defaultLocale);
-		for (const [locale, values] of table) {
-			if (locale === defaultLocale) continue;
-			const units = [...orderedKeys].map((key) => {
-				const src = source?.get(key) ?? "";
-				const target = values.get(key);
-				const targetXml = target === void 0 ? "" : `<target>${escapeXml(target)}</target>`;
-				return `      <trans-unit id="${escapeXml(key)}"><source>${escapeXml(src)}</source>${targetXml}</trans-unit>`;
+	const detected = detectFramework(root);
+	const isInteractive = !options.yes && process.stdin.isTTY;
+	let framework = options.framework || detected.framework;
+	let defaultLocale = options.defaultLocale || "en";
+	let localesInput = options.locales || "en,tr";
+	if (isInteractive) {
+		p.intro(pc.bgCyan(pc.black(" dialex init ")));
+		const frameworkOptions = [
+			{
+				value: "hono",
+				label: "Hono",
+				hint: detected.framework === "hono" ? "detected" : void 0
+			},
+			{
+				value: "express",
+				label: "Express",
+				hint: detected.framework === "express" ? "detected" : void 0
+			},
+			{
+				value: "fastify",
+				label: "Fastify",
+				hint: detected.framework === "fastify" ? "detected" : void 0
+			},
+			{
+				value: "koa",
+				label: "Koa",
+				hint: detected.framework === "koa" ? "detected" : void 0
+			},
+			{
+				value: "nestjs",
+				label: "NestJS",
+				hint: detected.framework === "nestjs" ? "detected" : void 0
+			},
+			{
+				value: "next",
+				label: "Next.js",
+				hint: detected.framework === "next" ? "detected" : void 0
+			},
+			{
+				value: "react",
+				label: "React / Vite",
+				hint: detected.framework === "react" ? "detected" : void 0
+			},
+			{
+				value: "elysia",
+				label: "Elysia",
+				hint: detected.framework === "elysia" ? "detected" : void 0
+			},
+			{
+				value: "sveltekit",
+				label: "SvelteKit",
+				hint: detected.framework === "sveltekit" ? "detected" : void 0
+			},
+			{
+				value: "astro",
+				label: "Astro",
+				hint: detected.framework === "astro" ? "detected" : void 0
+			},
+			{
+				value: "vue",
+				label: "Vue / Vite",
+				hint: detected.framework === "vue" ? "detected" : void 0
+			},
+			{
+				value: "nuxt",
+				label: "Nuxt",
+				hint: detected.framework === "nuxt" ? "detected" : void 0
+			}
+		];
+		const selectedFramework = await p.select({
+			message: `Framework detected as ${pc.bold(detected.framework)} (${detected.matchedRule}). Select framework:`,
+			options: frameworkOptions,
+			initialValue: detected.framework
+		});
+		if (p.isCancel(selectedFramework)) {
+			p.cancel("Operation cancelled.");
+			return;
+		}
+		framework = selectedFramework;
+		const inputDefault = await p.text({
+			message: "What is your default locale?",
+			initialValue: "en",
+			validate: (v) => !v || !v.trim() ? "Default locale cannot be empty" : void 0
+		});
+		if (p.isCancel(inputDefault)) {
+			p.cancel("Operation cancelled.");
+			return;
+		}
+		defaultLocale = inputDefault.trim();
+		const inputLocales = await p.text({
+			message: "Comma-separated list of supported locales:",
+			initialValue: `${defaultLocale},tr`,
+			validate: (v) => !v || !v.trim() ? "Locales list cannot be empty" : void 0
+		});
+		if (p.isCancel(inputLocales)) {
+			p.cancel("Operation cancelled.");
+			return;
+		}
+		localesInput = inputLocales.trim();
+		if (options.ai === void 0 && options.noAi === void 0) {
+			const confirmAi = await p.confirm({
+				message: "Configure AI agent support (Claude/Cursor skills, .mcp.json, AGENTS.md)?",
+				initialValue: true
 			});
-			write(`${locale}.xlf`, `<?xml version="1.0" encoding="UTF-8"?>
-<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
-  <file original="dialex" source-language="${escapeXml(defaultLocale)}" target-language="${escapeXml(locale)}" datatype="plaintext">
-    <body>
-${units.join("\n")}
-    </body>
-  </file>
-</xliff>
+			if (!p.isCancel(confirmAi)) options.ai = confirmAi;
+		}
+	} else logger.info(`Auto-detected framework: ${pc.bold(framework)} (${detected.matchedRule})`);
+	const localeList = Array.from(/* @__PURE__ */ new Set([defaultLocale, ...localesInput.split(",").map((s) => s.trim()).filter(Boolean)]));
+	const configPath = fs.existsSync(path.join(root, "dialex.config.ts")) ? path.join(root, "dialex.config.ts") : fs.existsSync(path.join(root, "i18n.config.ts")) ? path.join(root, "i18n.config.ts") : path.join(root, "dialex.config.ts");
+	const configFileName = path.basename(configPath);
+	try {
+		if (fs.existsSync(configPath)) {
+			const mod = await loadFile(configPath);
+			if (mod && mod.exports.default) {
+				if (mod.exports.default.$args && mod.exports.default.$args[0]) {
+					mod.exports.default.$args[0].defaultLocale = defaultLocale;
+					mod.exports.default.$args[0].locales = localeList;
+				}
+				await writeFile(mod, configPath);
+				logger.success(`Updated ${pc.bold(configFileName)} via Magicast`);
+			}
+		} else {
+			const mod = parseModule(`import { defineConfig } from "dialexjs";
+
+export default defineConfig({});
 `);
+			mod.exports.default.$args[0].defaultLocale = defaultLocale;
+			mod.exports.default.$args[0].locales = localeList;
+			await writeFile(mod, configPath);
+			logger.success(`Created ${pc.bold(configFileName)} via Magicast`);
 		}
+	} catch (err) {
+		logger.warn(`Magicast config update notice: ${err.message || String(err)}`);
+		const fallback = `import { defineConfig } from "dialexjs";
+
+export default defineConfig({
+  defaultLocale: "${defaultLocale}",
+  locales: [${localeList.map((l) => `"${l}"`).join(", ")}],
+});
+`;
+		fs.writeFileSync(configPath, fallback, "utf-8");
 	}
-	const quiet = options.json === true;
-	const result = {
-		success: true,
-		files,
-		keys: orderedKeys.size,
-		skippedFunctions,
-		skippedFiles: project.unsupported
-	};
-	if (quiet) console.log(JSON.stringify(result, null, 2));
-	else {
-		logger.success(`Exported ${orderedKeys.size} key${orderedKeys.size === 1 ? "" : "s"} to ${files.length} ${format} file${files.length === 1 ? "" : "s"} in ${path.relative(root, outDir) || "."}`);
-		if (skippedFunctions > 0) logger.warn(`${skippedFunctions} function value${skippedFunctions === 1 ? "" : "s"} skipped (not translatable as text)`);
-		for (const file of project.unsupported) logger.warn(`Skipped ${file}: unsupported dictionary shape`);
-	}
-	return result;
-}
-//#endregion
-//#region src/commands/import.ts
-const unescapeXml = (value) => value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&apos;/g, "'").replace(/&amp;/g, "&");
-function parseCsv(text) {
-	const rows = [];
-	let row = [];
-	let cell = "";
-	let quoted = false;
-	for (let i = 0; i < text.length; i++) {
-		const ch = text[i];
-		if (quoted) {
-			if (ch === "\"" && text[i + 1] === "\"") {
-				cell += "\"";
-				i++;
-			} else if (ch === "\"") quoted = false;
-			else cell += ch;
-		} else if (ch === "\"") quoted = true;
-		else if (ch === ",") {
-			row.push(cell);
-			cell = "";
-		} else if (ch === "\n" || ch === "\r") {
-			if (ch === "\r" && text[i + 1] === "\n") i++;
-			row.push(cell);
-			rows.push(row);
-			row = [];
-			cell = "";
-		} else cell += ch;
+	if (framework === "nuxt") {
+		const nuxtConfig = [
+			"nuxt.config.ts",
+			"nuxt.config.js",
+			"nuxt.config.mjs"
+		].map((f) => path.join(root, f)).find((f) => fs.existsSync(f));
+		if (nuxtConfig) try {
+			const nMod = await loadFile(nuxtConfig);
+			addNuxtModule(nMod, "dialexjs/nuxt", "dialex", {});
+			await writeFile(nMod, nuxtConfig);
+			logger.success(`Registered dialexjs/nuxt in ${pc.bold(path.basename(nuxtConfig))} via Magicast`);
+		} catch {
+			logger.warn("Could not update the Nuxt config; add the dialexjs/nuxt module manually.");
+		}
 	}
-	if (cell !== "" || row.length > 0) {
-		row.push(cell);
-		rows.push(row);
+	const targetDir = fs.existsSync(path.join(root, "src")) ? path.join(root, "src") : root;
+	const dictPath = path.join(targetDir, "home.content.ts");
+	if (!fs.existsSync(dictPath)) {
+		const dictContent = `import { defineDictionary } from "dialexjs";
+
+export default defineDictionary("home", {
+${localeList.map((loc) => `  ${loc}: {
+    title: "Welcome to Dialex (${loc})!",
+    description: "Type-safe internationalization.",
+    greeting: (name: string) => "Hello, " + name + "!",
+  },`).join("\n")}
+});
+`;
+		fs.writeFileSync(dictPath, dictContent, "utf-8");
+		logger.success(`Created starter dictionary at ${pc.bold(path.relative(root, dictPath))}`);
+	} else logger.info("home.content.ts already exists, skipping creation.");
+	generateDictionaries(root);
+	logger.success("Generated types and standalone dictionary registry!");
+	const pkgPath = path.join(root, "package.json");
+	if (fs.existsSync(pkgPath)) try {
+		const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+		const added = addRequiredPackages(pkg);
+		pkg.scripts = pkg.scripts || {};
+		const addScript = !pkg.scripts["dx:generate"];
+		if (addScript) pkg.scripts["dx:generate"] = "dx generate";
+		if (added.length > 0 || addScript) fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+		if (added.length > 0) {
+			logger.success(`Added ${added.join(" and ")} to package.json`);
+			logger.info(`Run ${pc.bold(installCommand(root))} to install them.`);
+		}
+		if (addScript) logger.success("Added \"dx:generate\" script to package.json");
+	} catch {
+		logger.warn("Could not update package.json; add dialexjs and @dialexjs/cli manually.");
 	}
-	return rows.filter((r) => r.some((c) => c !== ""));
-}
-function parseEntries(content, format, fallbackLocale) {
-	const entries = [];
-	if (format === "json") {
-		const data = JSON.parse(content);
-		if (Object.keys(data).length > 0 && Object.values(data).every((v) => v && typeof v === "object" && !Array.isArray(v))) {
-			for (const [locale, values] of Object.entries(data)) for (const [key, value] of Object.entries(values)) if (typeof value === "string") entries.push({
-				locale,
-				key,
-				value
-			});
-		} else {
-			if (!fallbackLocale) throw new Error("Cannot infer the locale; pass --locale.");
-			for (const [key, value] of Object.entries(data)) if (typeof value === "string") entries.push({
-				locale: fallbackLocale,
-				key,
-				value
-			});
+	else logger.warn("No package.json found; install dialexjs and @dialexjs/cli in your project.");
+	if (options.ai === true || options.yes && options.ai !== false && options.noAi !== true) try {
+		const skillDir = path.join(root, ".agents/skills/dialex");
+		fs.mkdirSync(skillDir, { recursive: true });
+		fs.writeFileSync(path.join(skillDir, "SKILL.md"), `---
+name: dialex
+description: Guide for internationalizing JavaScript and TypeScript apps with Dialex. Use when adding translations, creating content dictionaries, configuring locales, or using Dialex with frameworks like Next.js, React, Express, Hono, Fastify, SvelteKit, and Nuxt.
+---
+
+# Dialex Internationalization
+
+Dialex is a high-performance, type-safe internationalization toolchain for JavaScript and TypeScript.
+
+## Core Concepts
+- Dictionaries are defined with \`defineDictionary("name", { ... })\` in \`*.content.ts\` files.
+- Keys must match across all locales.
+- ICU message syntax is supported for plurals and selects.
+- Parity is validated at compile time with \`dialex check\`.
+
+## Useful Commands
+- \`dialex check --json\`: Check dictionary parity and references.
+- \`dialex check --fix\`: Automatically insert missing keys marked with [TODO].
+- \`dialex generate\`: Rebuild standalone dictionary bundle and types.
+- \`dialex translate --locale <locale>\`: Automatically translate missing keys.
+`, "utf-8");
+		const mcpConfigPath = path.join(root, ".mcp.json");
+		let mcpConfig = {};
+		if (fs.existsSync(mcpConfigPath)) try {
+			mcpConfig = JSON.parse(fs.readFileSync(mcpConfigPath, "utf-8"));
+		} catch {
+			mcpConfig = {};
 		}
-	} else if (format === "csv") {
-		const [header, ...rows] = parseCsv(content);
-		if (!header || header[0] !== "key") throw new Error("CSV must start with a \"key\" column.");
-		for (const row of rows) header.slice(1).forEach((locale, i) => {
-			const value = row[i + 1];
-			if (value !== void 0 && value !== "") entries.push({
-				locale,
-				key: row[0],
-				value
-			});
-		});
-	} else {
-		const locale = /target-language="([^"]*)"/.exec(content)?.[1] ?? fallbackLocale;
-		if (!locale) throw new Error("Cannot infer the locale; pass --locale.");
-		for (const match of content.matchAll(/<trans-unit\b[^>]*\bid="([^"]*)"[^>]*>([\s\S]*?)<\/trans-unit>/g)) {
-			const target = /<target\b[^>]*>([\s\S]*?)<\/target>/.exec(match[2])?.[1];
-			if (target !== void 0 && target !== "") entries.push({
-				locale,
-				key: unescapeXml(match[1]),
-				value: unescapeXml(target)
-			});
+		mcpConfig.mcpServers = mcpConfig.mcpServers || {};
+		mcpConfig.mcpServers.dialex = mcpConfig.mcpServers.dialex || {
+			command: "npx",
+			args: ["@dialexjs/mcp"]
+		};
+		fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf-8");
+		const agentsMdPath = path.join(root, "AGENTS.md");
+		const dialexAgentSnippet = `
+## Internationalization (Dialex)
+
+This project uses [Dialex](https://github.com/awaiden/dialex) for type-safe internationalization.
+- Dictionaries are in \`*.content.ts\` files using \`defineDictionary\`.
+- Run \`dialex check --json\` to verify parity.
+- Run \`dialex check --fix\` to insert missing keys marked with \`[TODO]\`.
+- Run \`dx generate\` (alias of \`dialex\`) or \`npm run dx:generate\` to compile dictionary bundles and update types.
+`;
+		if (!fs.existsSync(agentsMdPath)) fs.writeFileSync(agentsMdPath, dialexAgentSnippet.trimStart(), "utf-8");
+		else {
+			const existing = fs.readFileSync(agentsMdPath, "utf-8");
+			if (!existing.includes("Dialex")) fs.writeFileSync(agentsMdPath, existing.trimEnd() + "\n" + dialexAgentSnippet, "utf-8");
 		}
+		logger.success("Configured AI assistant support (.agents/skills, .mcp.json, AGENTS.md)");
+	} catch (err) {
+		logger.warn(`Could not finish AI configuration: ${err.message || String(err)}`);
 	}
-	return entries;
+	logger.log("");
+	logger.info(pc.bold(`Quick start for ${framework.toUpperCase()}:`));
+	switch (framework) {
+		case "hono":
+			logger.log(`
+import { Hono } from "hono";
+import { dialex } from "dialexjs/hono";
+import dictionaries from "./src/dialex.generated.js";
+
+const app = new Hono();
+app.use("*", dialex({ dictionaries }));
+
+app.get("/", (c) => {
+  const dict = c.var.getDictionary("home");
+  return c.json({ title: dict.title });
+});
+`);
+			break;
+		case "fastify":
+			logger.log(`
+import Fastify from "fastify";
+import { dialexPlugin } from "dialexjs/fastify";
+import dictionaries from "./src/dialex.generated.js";
+
+const app = Fastify();
+await app.register(dialexPlugin, { dictionaries });
+
+app.get("/", (req) => {
+  const dict = req.getDictionary("home");
+  return { title: dict.title };
+});
+`);
+			break;
+		case "express":
+			logger.log(`
+import express from "express";
+import { dialex } from "dialexjs/express";
+import dictionaries from "./src/dialex.generated.js";
+
+const app = express();
+app.use(dialex({ dictionaries }));
+
+app.get("/", (req, res) => {
+  const dict = req.getDictionary("home");
+  res.json({ title: dict.title });
+});
+`);
+			break;
+		case "koa":
+			logger.log(`
+import Koa from "koa";
+import { dialex } from "dialexjs/koa";
+import dictionaries from "./src/dialex.generated.js";
+
+const app = new Koa();
+app.use(dialex({ dictionaries }));
+
+app.use((ctx) => {
+  const dict = ctx.getDictionary("home");
+  ctx.body = { title: dict.title };
+});
+`);
+			break;
+		case "nestjs":
+			logger.log(`
+import { Module } from "@nestjs/common";
+import { DialexModule } from "dialexjs/nestjs";
+import dictionaries from "./src/dialex.generated.js";
+
+@Module({
+  imports: [DialexModule.forRoot({ dictionaries })],
+})
+export class AppModule {}
+`);
+			break;
+		case "next":
+			logger.log(`
+// src/dialex.ts
+import { createDialexServer } from "dialexjs/server";
+import { dialex } from "./dialex.generated";
+
+export const { getDictionary, getT } = createDialexServer(dialex);
+
+// app/[locale]/page.tsx (Server Component)
+import { getDictionary } from "../../dialex";
+
+export default async function Page({ params }: { params: Promise<{ locale: string }> }) {
+  const { locale = "en" } = await params;
+  const dict = getDictionary("home", locale);
+  return <h1>{dict.title}</h1>;
 }
-function inferFormat(file) {
-	const ext = path.extname(file).toLowerCase();
-	if (ext === ".json") return "json";
-	if (ext === ".csv") return "csv";
-	if (ext === ".xlf" || ext === ".xliff") return "xliff";
-	throw new Error(`Cannot infer format from "${ext}". Pass --format json|csv|xliff.`);
+
+// For client components, render the provider inside a "use client" file:
+//   "use client";
+//   import { DialexProvider } from "dialexjs/react";
+//   import { dialex } from "./dialex.generated";
+//   export const Providers = ({ children }) => <DialexProvider {...dialex}>{children}</DialexProvider>;
+`);
+			break;
+		case "react":
+			logger.log(`
+// src/main.tsx
+import { createRoot } from "react-dom/client";
+import { DialexProvider } from "dialexjs/react";
+import { dialex } from "./dialex.generated";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <DialexProvider {...dialex}>
+    <App />
+  </DialexProvider>,
+);
+
+// In components: const dict = useDictionary("home")
+`);
+			break;
+		case "elysia":
+			logger.log(`
+import { Elysia } from "elysia";
+import { dialex } from "dialexjs/elysia";
+import dictionaries from "./src/dialex.generated.js";
+
+new Elysia()
+  .use(dialex({ dictionaries }))
+  .get("/", ({ getDictionary }) => ({ title: getDictionary("home").title }))
+  .listen(3000);
+`);
+			break;
+		case "sveltekit":
+			logger.log(`
+// src/hooks.server.ts
+import { dialexHandle } from "dialexjs/sveltekit";
+import dictionaries from "./dialex.generated.js";
+
+export const handle = dialexHandle({ dictionaries });
+
+// src/app.html: <html lang="%dialex.lang%">
+// In load functions: locals.getDictionary("home")
+`);
+			break;
+		case "astro":
+			logger.log(`
+// src/middleware.ts
+import { dialex } from "dialexjs/astro";
+import dictionaries from "./dialex.generated.js";
+
+export const onRequest = dialex({ dictionaries });
+
+// In pages: Astro.locals.getDictionary("home")
+`);
+			break;
+		case "vue":
+			logger.log(`
+// src/main.ts
+import { createApp } from "vue";
+import { createDialex } from "dialexjs/vue";
+import { dialex } from "./dialex.generated";
+import App from "./App.vue";
+
+createApp(App).use(createDialex({ ...dialex })).mount("#app");
+
+// In components: const dict = useDictionary("home")
+`);
+			break;
+		case "nuxt":
+			logger.log(`
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["dialexjs/nuxt"],
+});
+
+// In components: const dict = useDictionary("home")
+`);
+			break;
+		default: logger.log(`
+Import dictionaries and register your framework middleware to begin!
+Run \`npm run dx:generate\` whenever you add new dictionary files.
+`);
+	}
+	logger.info("Keep dialex.generated.ts current: run `dx generate --watch` while you develop, or use the Dialex VS Code extension, which regenerates on save.");
+	if (isInteractive) p.outro(pc.green("✔ dialex is configured and ready to go!"));
 }
+//#endregion
+//#region src/commands/lock.ts
 /**
-* Why `value` must not replace the current text, if it is an ICU message that is invalid or uses
-* different arguments than the same key in another locale.
+* Records the current translations as up to date with the current source text, so later edits to
+* the source can be noticed. Translations that are already out of date are left alone unless
+* `--all` is given. Run it once when you adopt the lock file, and after reviewing stale ones.
 */
-function icuProblem(df, defaultLocale, locale, keyPath, value) {
-	if (!value.includes("{")) return void 0;
-	let signature;
-	try {
-		signature = argumentSignature(parseMessage(value));
-	} catch (error) {
-		return `invalid ICU: ${error.message}`;
-	}
-	const locales = listLocales(df);
-	for (const other of [defaultLocale, ...locales.filter((l) => l !== defaultLocale)]) {
-		if (other === locale) continue;
-		const reference = getString(df, other, keyPath);
-		if (!reference?.includes("{")) continue;
-		try {
-			const expected = argumentSignature(parseMessage(reference));
-			return expected === signature ? void 0 : `arguments differ from "${other}": expected ${expected || "none"}, found ${signature || "none"}`;
-		} catch {
-			continue;
-		}
-	}
-}
-async function runImport(options) {
+async function runLock(options = {}) {
 	const root = options.cwd || process.cwd();
-	const file = path.resolve(root, options.file);
-	const format = options.format || inferFormat(file);
-	const fallbackLocale = options.locale ?? path.basename(file, path.extname(file));
-	const entries = parseEntries(fs.readFileSync(file, "utf-8"), format, options.locale ?? fallbackLocale);
 	const project = await loadProject(root, options.config);
-	const byName = new Map(project.dictionaries.map((d) => [d.name, d]));
-	const quiet = options.json === true;
+	const source = options.source ?? project.config.translate?.sourceLocale ?? project.config.defaultLocale ?? "en";
+	const { lock } = lockFor(root, source);
 	const result = {
 		success: true,
-		created: 0,
-		updated: 0,
-		skipped: [],
-		rejected: [],
-		unknown: [],
-		errors: []
+		sourceLocale: source,
+		recorded: 0,
+		stale: []
 	};
-	const touched = /* @__PURE__ */ new Set();
-	for (const { locale, key, value } of entries) {
-		const [name, ...keyPath] = key.split(".");
-		const dict = byName.get(name);
-		if (!dict || keyPath.length === 0) {
-			result.unknown.push(key);
-			continue;
-		}
-		if (!listLocales(dict.df).some((l) => hasPath(dict.df, l, keyPath)) && !options.allowNew) {
-			result.unknown.push(key);
-			continue;
-		}
-		const problem = icuProblem(dict.df, project.config.defaultLocale ?? "en", locale, keyPath, value);
-		if (problem) {
-			result.rejected.push(`${locale}:${key} (${problem})`);
-			continue;
-		}
-		const outcome = setString(dict.df, locale, keyPath, value);
-		if (outcome === "skipped") result.skipped.push(`${locale}:${key}`);
-		else {
-			result[outcome]++;
-			touched.add(dict.rel);
+	for (const dict of project.dictionaries) {
+		const sourceText = new Map(listLeaves(dict.df, source).filter((leaf) => leaf.kind === "string" && leaf.value !== void 0).map((leaf) => [leaf.path.join("."), leaf.value]));
+		for (const locale of listLocales(dict.df)) {
+			if (locale === source) continue;
+			for (const leaf of listLeaves(dict.df, locale)) {
+				if (leaf.kind !== "string" || leaf.value === void 0) continue;
+				if (leaf.value.startsWith("[TODO] ")) continue;
+				const text = sourceText.get(leaf.path.join("."));
+				if (text === void 0) continue;
+				const key = toKey(dict.name, leaf.path);
+				const known = lock.locales[locale]?.[key] !== void 0;
+				if (known && isStale(lock, locale, key, text)) {
+					if (!options.all) {
+						result.stale.push(`${locale}:${key}`);
+						continue;
+					}
+				} else if (known) continue;
+				record(lock, locale, key, text);
+				result.recorded++;
+			}
 		}
 	}
-	for (const dict of project.dictionaries) if (touched.has(dict.rel)) await saveDictionaryFile(dict.df);
-	if (result.rejected.length > 0) result.success = false;
-	if (quiet) console.log(JSON.stringify(result, null, 2));
+	if (result.recorded > 0 || !fs.existsSync(lockPath(root))) writeLock(root, lock);
+	if (options.json) console.log(JSON.stringify(result, null, 2));
 	else {
-		logger.success(`Imported ${result.created + result.updated} value${result.created + result.updated === 1 ? "" : "s"} (${result.created} added, ${result.updated} updated)`);
-		if (result.unknown.length > 0) logger.warn(`${result.unknown.length} unknown key${result.unknown.length === 1 ? "" : "s"} ignored (use --allow-new to add): ${result.unknown.slice(0, 5).join(", ")}${result.unknown.length > 5 ? ", ..." : ""}`);
-		if (result.rejected.length > 0) logger.warn(`${result.rejected.length} value${result.rejected.length === 1 ? "" : "s"} rejected: ${result.rejected.slice(0, 5).join("; ")}`);
-		if (result.skipped.length > 0) logger.warn(`${result.skipped.length} non-text value${result.skipped.length === 1 ? "" : "s"} left unchanged: ${result.skipped.slice(0, 5).join(", ")}`);
+		logger.success(`Recorded ${result.recorded} translation${result.recorded === 1 ? "" : "s"} in ${path.basename(LOCK_FILE)} (source "${source}")`);
+		if (result.stale.length > 0) {
+			logger.warn(`${result.stale.length} out of date and left as they are: ${result.stale.slice(0, 5).join(", ")}${result.stale.length > 5 ? ", ..." : ""}`);
+			logger.log(`  ${pc.dim("Re-translate them with")} dialex translate --stale${pc.dim(", or accept them with")} dialex lock --all`);
+		}
 	}
 	return result;
 }
@@ -1019,6 +1172,8 @@ async function runTranslate(options = {}) {
 	const everyLocale = new Set(project.config.locales ?? []);
 	for (const { df } of project.dictionaries) listLocales(df).forEach((l) => everyLocale.add(l));
 	const targets = (options.locale?.length ? options.locale : [...everyLocale]).filter((l) => l !== source);
+	const { lock, replaced } = lockFor(root, source);
+	if (replaced && !options.json) logger.warn(`dialex.lock.json was recorded from another source locale; starting a new one from "${source}".`);
 	const tasks = [];
 	for (const dict of project.dictionaries) {
 		const sourceLeaves = listLeaves(dict.df, source).filter((leaf) => leaf.kind === "string" && leaf.value !== void 0);
@@ -1026,13 +1181,17 @@ async function runTranslate(options = {}) {
 			const existing = new Map(listLeaves(dict.df, locale).map((leaf) => [leaf.path.join("\0"), leaf]));
 			for (const leaf of sourceLeaves) {
 				const current = existing.get(leaf.path.join("\0"));
-				if (!current || current.kind === "string" && current.value?.startsWith("[TODO] ")) tasks.push({
+				const key = toKey(dict.name, leaf.path);
+				const placeholder = !current || current.kind === "string" && current.value?.startsWith("[TODO] ");
+				const stale = !placeholder && options.stale === true && current?.kind === "string" && isStale(lock, locale, key, leaf.value);
+				if (placeholder || stale) tasks.push({
 					dict,
 					path: leaf.path,
 					file: dict.rel,
 					locale,
-					key: toKey(dict.name, leaf.path),
-					source: leaf.value
+					key,
+					source: leaf.value,
+					...stale ? { stale: true } : {}
 				});
 			}
 		}
@@ -1054,7 +1213,7 @@ async function runTranslate(options = {}) {
 		if (quiet) console.log(JSON.stringify(result, null, 2));
 		else {
 			logger.info(`Would translate ${tasks.length} string${tasks.length === 1 ? "" : "s"} from "${source}":`);
-			for (const t of tasks) logger.log(`  ${pc.dim(t.locale)} ${t.key}  ${pc.dim(JSON.stringify(t.source))}`);
+			for (const t of tasks) logger.log(`  ${pc.dim(t.locale)} ${t.key}  ${pc.dim(JSON.stringify(t.source))}${t.stale ? pc.yellow("  (out of date)") : ""}`);
 		}
 		return result;
 	}
@@ -1088,11 +1247,13 @@ async function runTranslate(options = {}) {
 				continue;
 			}
 			task.translated = translated;
+			record(lock, locale, task.key, task.source);
 			result.translated++;
 			touched.add(task.dict);
 		}
 	}
 	for (const dict of touched) await saveDictionaryFile(dict.df);
+	if (result.translated > 0) writeLock(root, lock);
 	if (result.rejected.length > 0) result.success = false;
 	if (quiet) console.log(JSON.stringify(result, null, 2));
 	else {
@@ -1104,14 +1265,14 @@ async function runTranslate(options = {}) {
 //#endregion
 //#region src/index.ts
 const program = new Command();
-program.name("dialex").description("Dialex CLI - High-performance, type-safe internationalization compiler and tooling").version("0.3.0");
+program.name("dialex").description("Dialex CLI - High-performance, type-safe internationalization compiler and tooling").version(version);
 program.command("generate").alias("gen").description("Generate standalone dictionary bundle and TypeScript declarations").option("-w, --watch", "Watch dictionary files for changes").option("-o, --output <path>", "Custom output file path for generated dictionaries").option("-c, --config <path>", "Custom config path").option("--json", "Print machine-readable JSON").action(async (opts) => {
 	await runGenerate(opts);
 });
 program.command("init").description("Initialize Dialex in the current project").option("-f, --framework <framework>", "Target framework (hono, express, fastify, koa, nestjs, next, react)").option("-d, --default-locale <locale>", "Default locale (e.g. en)").option("-l, --locales <locales>", "Comma-separated supported locales (e.g. en,tr)").option("-y, --yes", "Skip prompts and use defaults").option("--ai", "Configure AI agent support (.agents/skills, .mcp.json, AGENTS.md)").option("--no-ai", "Skip AI agent configuration").action(async (opts) => {
 	await runInit(opts);
 });
-program.command("check").alias("lint").description("Verify dictionary key parity and locale completeness").option("-c, --config <path>", "Custom config path").option("--json", "Print machine-readable JSON").option("--github", "Print GitHub Actions annotations").option("--fix", "Insert missing keys marked with [TODO]").option("--src <globs...>", "Source globs to scan for dictionary references").action(async (opts) => {
+program.command("check").alias("lint").description("Verify dictionary key parity and locale completeness").option("-c, --config <path>", "Custom config path").option("--json", "Print machine-readable JSON").option("--github", "Print GitHub Actions annotations").option("--fix", "Insert missing keys marked with [TODO]").option("--fail-on-stale", "Treat translations whose source text changed as errors").option("--src <globs...>", "Source globs to scan for dictionary references").action(async (opts) => {
 	await runCheck(opts);
 });
 program.command("export").description("Export dictionary strings for translators (json, csv, or xliff)").option("-f, --format <format>", "Output format: json, csv, xliff", "json").option("-o, --out <dir>", "Output directory", "dialex-export").option("-l, --locale <locales...>", "Limit to these locales").option("-c, --config <path>", "Custom config path").option("--json", "Print machine-readable JSON").action(async (opts) => {
@@ -1123,7 +1284,7 @@ program.command("import <file>").description("Write translated strings from a js
 		...opts
 	});
 });
-program.command("translate").description("Fill missing translations with the provider configured in dialex.config.ts").option("-l, --locale <locales...>", "Target locales (default: all configured)").option("-s, --source <locale>", "Source locale (default: translate.sourceLocale or defaultLocale)").option("--dry-run", "List what would be translated without calling the provider").option("-c, --config <path>", "Custom config path").option("--json", "Print machine-readable JSON").action(async (opts) => {
+program.command("translate").description("Fill missing translations with the provider configured in dialex.config.ts").option("-l, --locale <locales...>", "Target locales (default: all configured)").option("-s, --source <locale>", "Source locale (default: translate.sourceLocale or defaultLocale)").option("--dry-run", "List what would be translated without calling the provider").option("--stale", "Also re-translate strings whose source text changed since they were translated").option("-c, --config <path>", "Custom config path").option("--json", "Print machine-readable JSON").action(async (opts) => {
 	try {
 		await runTranslate(opts);
 	} catch (err) {
@@ -1135,6 +1296,14 @@ program.command("translate").description("Fill missing translations with the pro
 		process.exit(1);
 	}
 });
+program.command("lock").description("Record translations as up to date with the current source text (dialex.lock.json)").option("-s, --source <locale>", "Locale the translations were made from").option("--all", "Also accept translations that are already out of date").option("--json", "Print machine-readable JSON").option("-c, --config <path>", "Custom config path").action(async (opts) => {
+	try {
+		await runLock(opts);
+	} catch (err) {
+		logger.error(err.message || String(err));
+		process.exit(1);
+	}
+});
 program.parse();
 //#endregion
 export {};