@x18n/cli 0.0.2 → 0.0.5

package/dist/cli.d.mts

@@ -0,0 +1,4 @@
+import { CAC } from "cac";
+//#region src/cli.d.ts
+export declare function createCli(): CAC;
+//#endregion

package/dist/cli.mjs

@@ -0,0 +1,705 @@
+import { a as openWorkspace, c as readInput, d as stdinArg, f as useColor, i as exitCodeOf, l as runPlan, n as displayPath, o as out, p as wireDiagnostics, r as errorInfo, s as printJson, t as cwd, u as singleProject } from "./context-Za_ea1Nk.mjs";
+import { createRequire } from "node:module";
+import { PluginFileSchema, X18nError, isJsonObject, parseMessageBatch, placeholderProblems, renderPrompt, toWireRange, validate } from "@x18n/core";
+import process from "node:process";
+import cac from "cac";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { configFileNames, findConfigFile, loadWorkspace, migrateI18nAlly } from "@x18n/node";
+import { extractItems, findCandidates, toPlanFile } from "@x18n/builtins/extractors";
+import { existsSync } from "node:fs";
+import { namespaceFromPath } from "@x18n/builtins/finders";
+import { parse, stringify } from "yaml";
+//#region package.json
+var version = "0.0.5";
+//#endregion
+//#region src/commands/change.ts
+async function project(options) {
+	return singleProject(await openWorkspace(options));
+}
+async function set(key, options) {
+	if (options.value === void 0) throw new X18nError("X18N4008", "pass --value <text> (or --value - to read stdin)");
+	const loaded = await project(options);
+	const value = options.value === "\0stdin" ? (await readInput(stdinArg)).replace(/\r?\n$/, "") : String(options.value);
+	const locale = options.locale ?? loaded.project.sourceLocale;
+	await runPlan("set", loaded, loaded.project.plan([{
+		type: "set",
+		key: loaded.project.parseKey(key),
+		locale,
+		value
+	}]), options);
+}
+async function apply(source, options) {
+	const loaded = await project(options);
+	const p = loaded.project;
+	let data;
+	try {
+		data = JSON.parse(await readInput(source));
+	} catch (error) {
+		throw new X18nError("X18N4008", `${source} is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const ops = parseMessageBatch(p, data);
+	const rejected = placeholderProblems(p, ops);
+	if (rejected.length > 0 && !options.force) {
+		if (options.json) {
+			printJson("apply", {
+				applied: false,
+				rejected
+			}, [], [new X18nError("X18N4007", `${rejected.length} values`).toJSON()]);
+			return 1;
+		}
+		for (const r of rejected) out(`rejected ${r.locale} ${r.key}: ${[r.missing.length ? `missing ${r.missing.join(", ")}` : "", r.extra.length ? `unexpected ${r.extra.join(", ")}` : ""].filter(Boolean).join("; ")}`);
+		out(`${rejected.length} values have placeholder problems; nothing was written. Fix them or pass --force.`);
+		return 1;
+	}
+	await runPlan("apply", loaded, p.plan(ops), options);
+	return 0;
+}
+async function rename(from, to, options) {
+	const loaded = await project(options);
+	const p = loaded.project;
+	const op = {
+		type: "rename",
+		from: p.parseKey(from),
+		to: p.parseKey(to),
+		usages: options.usages !== false
+	};
+	await runPlan("rename", loaded, p.plan([op]), options);
+}
+async function remove(key, options) {
+	const loaded = await project(options);
+	const locales = options.locale === void 0 ? "all" : [options.locale].flat();
+	await runPlan("delete", loaded, loaded.project.plan([{
+		type: "delete",
+		key: loaded.project.parseKey(key),
+		locales
+	}]), options);
+}
+async function fill(options) {
+	const loaded = await project(options);
+	const p = loaded.project;
+	const targets = options.locale === void 0 ? p.locales.filter((l) => l !== p.sourceLocale) : [options.locale].flat();
+	const ops = [];
+	for (const locale of targets) for (const key of p.keys({ missing: locale })) {
+		if (p.message(key, locale) !== void 0) continue;
+		ops.push({
+			type: "set",
+			key,
+			locale,
+			value: options.copySource ? p.message(key, p.sourceLocale)?.value ?? "" : ""
+		});
+	}
+	await runPlan("fill", loaded, p.plan(ops), options);
+}
+async function format(options) {
+	const loaded = await project(options);
+	await runPlan("format", loaded, loaded.project.plan([{ type: "format" }]), options);
+}
+//#endregion
+//#region src/commands/check.ts
+function list(value) {
+	return value === void 0 ? [] : [value].flat().flatMap((item) => String(item).split(",")).map((item) => item.trim()).filter(Boolean);
+}
+function filterDiagnostics(diagnostics, options) {
+	const locales = list(options.locale);
+	const only = list(options.only);
+	const skip = list(options.skip);
+	return diagnostics.filter((d) => locales.length === 0 || d.locale === void 0 || locales.includes(d.locale) || d.code === "missing-translation" && locales.some((l) => d.message.includes(l))).filter((d) => only.length === 0 || only.includes(d.code)).filter((d) => !skip.includes(d.code)).map((d) => options.strict && d.severity === "warning" ? {
+		...d,
+		severity: "error"
+	} : d);
+}
+function reportInputs(workspace, options) {
+	return workspace.projects.map((loaded) => {
+		const analysis = loaded.project.analyze();
+		const diagnostics = filterDiagnostics(analysis.diagnostics, options);
+		return {
+			project: loaded.name,
+			text: (path) => loaded.project.text(path),
+			diagnostics,
+			coverage: analysis.coverage,
+			summary: {
+				errors: diagnostics.filter((d) => d.severity === "error").length,
+				warnings: diagnostics.filter((d) => d.severity === "warning").length,
+				infos: diagnostics.filter((d) => d.severity === "info" || d.severity === "hint").length,
+				files: new Set(diagnostics.flatMap((d) => d.location ? [d.location.path] : [])).size
+			}
+		};
+	});
+}
+/** History costs a git walk, so it loads only when `stale-translation` runs. */
+function needsHistory(loaded, options) {
+	const setting = loaded.project.config.checks["stale-translation"];
+	const level = typeof setting === "string" ? setting : setting?.[0];
+	const only = list(options.only);
+	return level !== "off" && (only.length === 0 || only.includes("stale-translation")) && !list(options.skip).includes("stale-translation");
+}
+async function report(workspace, options) {
+	const inputs = reportInputs(workspace, options);
+	const reporterIds = list(options.reporter);
+	const ids = reporterIds.length ? reporterIds : [options.json ? "json" : "pretty"];
+	const outputs = list(options.output);
+	const available = workspace.projects[0]?.project.reporters ?? /* @__PURE__ */ new Map();
+	const roots = new Map(workspace.projects.map((p) => [p.name, p.root]));
+	for (const [i, id] of ids.entries()) {
+		const reporter = available.get(id);
+		if (!reporter) throw new X18nError("X18N0001", `unknown reporter "${id}" (${[...available.keys()].join(", ")})`);
+		const text = await reporter.report(inputs, {
+			color: !outputs[i] && useColor(options) && id === "pretty",
+			displayPath: (path, project) => displayPath(roots.get(project) ?? "", path)
+		});
+		if (outputs[i]) await writeFile(outputs[i], text);
+		else if (text) process.stdout.write(text);
+	}
+	const errors = inputs.reduce((sum, input) => sum + input.summary.errors, 0);
+	const warnings = inputs.reduce((sum, input) => sum + input.summary.warnings, 0);
+	const tooManyWarnings = options.maxWarnings !== void 0 && warnings > Number(options.maxWarnings);
+	return errors > 0 || tooManyWarnings ? 1 : 0;
+}
+async function check(options) {
+	const workspace = await openWorkspace(options);
+	await Promise.all(workspace.projects.filter((loaded) => needsHistory(loaded, options)).map(async (loaded) => {
+		await loaded.project.loadHistory({ watch: options.watch });
+		await loaded.host.flush();
+	}));
+	const code = await report(workspace, options);
+	if (!options.watch) return code;
+	const rerun = async () => {
+		if (process.stdout.isTTY) process.stdout.write("\x1Bc");
+		out(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] File change detected. Checking...\n`);
+		await report(workspace, options);
+	};
+	for (const loaded of workspace.projects) {
+		loaded.project.watch();
+		loaded.project.onChange(() => void rerun());
+	}
+	out("\nWatching for file changes.");
+	return new Promise(() => {});
+}
+//#endregion
+//#region src/commands/extract.ts
+function isPlanItem(value) {
+	if (!isJsonObject(value) || !isJsonObject(value.range)) return false;
+	return [
+		"path",
+		"original",
+		"key",
+		"value",
+		"replacement"
+	].every((field) => typeof value[field] === "string") && typeof value.range.start === "number" && typeof value.range.end === "number" && Array.isArray(value.imports) && value.imports.every((line) => typeof line === "string");
+}
+async function readPlan(file) {
+	const data = JSON.parse(await readFile(file, "utf8"));
+	if (!isJsonObject(data) || !Array.isArray(data.items) || !data.items.every(isPlanItem)) throw new X18nError("X18N4008", `${file} is not an extraction plan`);
+	return data.items;
+}
+/** One question per string in a TTY: extract with the proposed key, a typed key, or skip. */
+async function review(candidates, root) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	const picked = [];
+	try {
+		for (const candidate of candidates) {
+			process.stderr.write(`\n${displayPath(root, candidate.path)}:${candidate.line}  ${JSON.stringify(candidate.text)}\n  → ${candidate.replacement}\n`);
+			const reply = (await rl.question(`Extract as "${candidate.key}"? [Y/n/key/q] `)).trim();
+			if (reply === "q") break;
+			if (reply === "n") continue;
+			picked.push(reply && reply !== "y" ? {
+				...candidate,
+				key: reply,
+				replacement: candidate.replacement.replace(candidate.key, reply)
+			} : candidate);
+		}
+	} finally {
+		rl.close();
+	}
+	return picked;
+}
+async function extract(files, options) {
+	const loaded = singleProject(await openWorkspace(options));
+	const { project } = loaded;
+	if (options.apply) {
+		const items = extractItems(project, await readPlan(options.apply));
+		await runPlan("extract", loaded, project.plan([{
+			type: "extract",
+			items
+		}]), options);
+		return;
+	}
+	const candidates = findCandidates(project, { files });
+	if (options.plan) {
+		await writeFile(options.plan, `${JSON.stringify(toPlanFile(project, candidates), null, 2)}\n`);
+		if (options.json) printJson("extract", {
+			plan: options.plan,
+			items: candidates.length
+		});
+		else out(`Wrote ${candidates.length} strings to ${options.plan}. Edit keys and replacements, then run \`x18n extract --apply ${options.plan}\`.`);
+		return;
+	}
+	const interactive = !options.list && !options.yes && !options.json && process.stdin.isTTY;
+	if (options.list || !interactive && !options.yes) {
+		if (options.json) {
+			printJson("extract", { items: candidates.map((c) => ({
+				...c,
+				file: displayPath(loaded.root, c.path)
+			})) });
+			return;
+		}
+		for (const c of candidates) out(`${displayPath(loaded.root, c.path)}:${c.line}\t${c.kind}\t${JSON.stringify(c.text)}\t→ ${c.key}${c.reused ? " (existing)" : ""}`);
+		out(`${candidates.length} strings. Apply with \`x18n extract --yes\`, or review with \`x18n extract --plan plan.json\`.`);
+		return;
+	}
+	const chosen = interactive ? await review(candidates, loaded.root) : candidates;
+	if (chosen.length === 0) {
+		out("Nothing to extract.");
+		return;
+	}
+	await runPlan("extract", loaded, project.plan([{
+		type: "extract",
+		items: extractItems(project, chosen)
+	}]), options);
+}
+//#endregion
+//#region src/commands/look.ts
+function percent(coverage) {
+	return coverage.total === 0 ? 100 : Math.floor(coverage.translated / coverage.total * 1e3) / 10;
+}
+function summaryOf(loaded) {
+	const diagnostics = loaded.project.analyze().diagnostics;
+	return {
+		errors: diagnostics.filter((d) => d.severity === "error").length,
+		warnings: diagnostics.filter((d) => d.severity === "warning").length,
+		infos: diagnostics.filter((d) => d.severity === "info" || d.severity === "hint").length
+	};
+}
+function statusData(loaded) {
+	const { project } = loaded;
+	return {
+		name: loaded.name,
+		root: displayPath(loaded.root, ""),
+		sourceLocale: project.sourceLocale,
+		locales: project.analyze().coverage.map((c) => ({
+			locale: c.locale,
+			total: c.total,
+			translated: c.translated,
+			missing: c.missing.length,
+			empty: c.empty.length,
+			percent: percent(c)
+		})),
+		resources: project.resources.length,
+		keys: project.keys().length,
+		usages: project.usages().length,
+		summary: summaryOf(loaded)
+	};
+}
+async function status(options) {
+	const workspace = await openWorkspace(options);
+	if (options.json) {
+		printJson("status", { projects: workspace.projects.map(statusData) });
+		return;
+	}
+	for (const loaded of workspace.projects) {
+		const { project } = loaded;
+		const summary = summaryOf(loaded);
+		out(`${loaded.name} (${displayPath(loaded.root, "")})`);
+		out(`  ${project.resources.length} resources, ${project.keys().length} keys, ${project.usages().length} usages`);
+		for (const c of project.analyze().coverage) {
+			const label = `${c.locale}${c.locale === project.sourceLocale ? " (source)" : ""}`;
+			out(`  ${label.padEnd(16)} ${String(percent(c)).padStart(5)}%  ${c.translated}/${c.total}${c.missing.length ? `, ${c.missing.length} missing` : ""}${c.empty.length ? `, ${c.empty.length} empty` : ""}`);
+		}
+		out(`  ${summary.errors} errors, ${summary.warnings} warnings`);
+	}
+}
+/** One page of a list: `--limit` items from `--cursor`, plus the cursor of the next page. */
+function page(items, options) {
+	const start = Number(options.cursor ?? 0) || 0;
+	const end = options.limit ? start + Number(options.limit) : items.length;
+	return {
+		items: items.slice(start, end),
+		total: items.length,
+		nextCursor: end < items.length ? String(end) : void 0
+	};
+}
+async function keys(glob, options) {
+	const workspace = await openWorkspace(options);
+	const projects = workspace.projects.map((loaded) => {
+		const { project } = loaded;
+		const { items, total, nextCursor } = page(project.keys({
+			glob,
+			missing: options.missing,
+			unused: options.unused,
+			namespace: options.namespace
+		}), options);
+		const values = (key) => Object.fromEntries(project.locales.map((locale) => [locale, project.message(key, locale)?.value]));
+		return {
+			name: loaded.name,
+			total,
+			nextCursor,
+			keys: items.map((key) => options.values ? {
+				key,
+				values: values(key)
+			} : { key })
+		};
+	});
+	if (options.json) {
+		printJson("keys", { projects });
+		return;
+	}
+	for (const p of projects) {
+		if (workspace.projects.length > 1) out(`# ${p.name}`);
+		for (const item of p.keys) out("values" in item ? `${item.key}\t${JSON.stringify(item.values)}` : item.key);
+		if (p.nextCursor) out(`… ${p.total - Number(p.nextCursor)} more (--cursor ${p.nextCursor})`);
+	}
+}
+function locate(loaded, path, start, end) {
+	const range = toWireRange(loaded.project.text(path), start, end);
+	return {
+		file: displayPath(loaded.root, path),
+		line: range.line,
+		column: range.column
+	};
+}
+async function get(input, options) {
+	const workspace = await openWorkspace(options);
+	const projects = workspace.projects.flatMap((loaded) => {
+		const { project } = loaded;
+		const info = project.get(project.parseKey(input));
+		if (!info) return [];
+		const resourceOf = (id) => project.resources.find((r) => r.id === id)?.path ?? id;
+		return [{
+			name: loaded.name,
+			key: info.key,
+			namespace: info.namespace,
+			messages: info.messages.map((m) => ({
+				locale: m.locale,
+				value: m.value,
+				...locate(loaded, resourceOf(m.resource), m.range?.key.start ?? 0, m.range?.key.end ?? 0)
+			})),
+			missing: info.missing,
+			usages: info.usages.map((u) => ({
+				possible: u.possible,
+				raw: u.usage.raw,
+				...locate(loaded, u.usage.path, u.usage.range.start, u.usage.range.end)
+			})),
+			diagnostics: wireDiagnostics(loaded, info.diagnostics)
+		}];
+	});
+	if (options.json) {
+		printJson("get", { projects });
+		return;
+	}
+	if (projects.length === 0) out(`"${input}" is not defined.`);
+	for (const p of projects) {
+		out(`${p.key}${workspace.projects.length > 1 ? ` (${p.name})` : ""}`);
+		for (const m of p.messages) out(`  ${m.locale.padEnd(8)} ${JSON.stringify(m.value)}  ${m.file}:${m.line}:${m.column}`);
+		if (p.missing.length) out(`  missing in ${p.missing.join(", ")}`);
+		out(`  ${p.usages.length} usages`);
+		for (const u of p.usages) out(`    ${u.file}:${u.line}:${u.column}${u.possible ? " (possible)" : ""}`);
+		for (const d of p.diagnostics) out(`  ${d.severity} ${d.code}: ${d.message}`);
+	}
+}
+async function usages(input, options) {
+	const projects = (await openWorkspace(options)).projects.map((loaded) => {
+		const { project } = loaded;
+		const { items, total, nextCursor } = page(project.usages({
+			key: input === void 0 ? void 0 : project.parseKey(input),
+			path: options.file
+		}), options);
+		return {
+			name: loaded.name,
+			total,
+			nextCursor,
+			usages: items.map((m) => ({
+				key: m.usage.key,
+				raw: m.usage.raw,
+				possible: m.possible,
+				dynamic: m.usage.dynamic,
+				...locate(loaded, m.usage.path, m.usage.range.start, m.usage.range.end)
+			}))
+		};
+	});
+	if (options.json) {
+		printJson("usages", { projects });
+		return;
+	}
+	for (const p of projects) for (const u of p.usages) out(`${u.file}:${u.line}:${u.column}\t${u.key ?? u.raw}${u.possible ? " (possible)" : ""}`);
+}
+async function locales(options) {
+	const projects = (await openWorkspace(options)).projects.map((loaded) => ({
+		name: loaded.name,
+		sourceLocale: loaded.project.sourceLocale,
+		locales: loaded.project.locales.map((code) => ({
+			...loaded.project.localeInfo(code),
+			resources: loaded.project.resources.filter((r) => r.locale === code).map((r) => displayPath(loaded.root, r.path))
+		}))
+	}));
+	if (options.json) {
+		printJson("locales", { projects });
+		return;
+	}
+	for (const p of projects) for (const l of p.locales) out(`${l.code.padEnd(10)} ${(l.displayName ?? "").padEnd(28)} ${l.resources.join(", ")}`);
+}
+async function doctor(options) {
+	const projects = (await openWorkspace(options)).projects.map((loaded) => ({
+		...loaded.project.explain(),
+		root: displayPath(loaded.root, ""),
+		configFile: loaded.configFile && displayPath(loaded.configFile, "")
+	}));
+	if (options.json) {
+		printJson("doctor", { projects });
+		return;
+	}
+	for (const e of projects) {
+		out(`# ${e.name} (${e.root})`);
+		out(`config: ${e.configFile ?? "none (detection only)"}`);
+		out(`presets:`);
+		const applied = e.presets.filter((p) => p.reason === "detected" || p.reason === "listed");
+		for (const p of applied) out(`  ✓ ${p.name} (${p.reason})`);
+		if (applied.length === 0) out("  none");
+		if (e.presets.length > applied.length) out(`  ${e.presets.length - applied.length} others not applied (--json lists them)`);
+		out("finders:");
+		for (const f of e.finders) out(`  ${f.id}: ${f.resources.length} resources${f.resources.length ? `\n    ${f.resources.slice(0, 20).join("\n    ")}` : ""}`);
+		out("formats:");
+		for (const f of e.formats.filter((f) => f.resources > 0)) out(`  ${f.id} (${f.extensions.join(", ")}): ${f.resources} resources`);
+		out("scanners:");
+		for (const s of e.scanners) out(`  ${s.id} (${s.extensions.join(", ") || "none"}): ${s.files} files`);
+		if (e.conflicts.length) out(`conflicts:\n${e.conflicts.map((c) => `  .${c.extension}: ${c.winner} wins over ${c.loser}`).join("\n")}`);
+		if (e.errors.length) out(`errors:\n${e.errors.map((err) => `  ${err.code} ${err.message}`).join("\n")}`);
+		out("config origins:");
+		for (const [key, origin] of Object.entries(e.config.origins)) out(`  ${key}: ${origin}`);
+	}
+}
+//#endregion
+//#region src/commands/migrate.ts
+async function migrate(source, options) {
+	if (source !== "i18n-ally") throw new X18nError("X18N0001", `unknown migration source "${source}" (i18n-ally)`);
+	const root = resolve(options.root ?? cwd());
+	const result = await migrateI18nAlly(root, { format: options.format });
+	const existing = findConfigFile(root);
+	if (existing && !options.force && !options.dryRun && result.files.length > 0) throw new X18nError("X18N0001", `${existing} already exists (pass --force to replace it)`);
+	if (!options.dryRun) for (const file of result.files) {
+		const path = join(root, file.path);
+		await mkdir(dirname(path), { recursive: true });
+		if (file.path === ".x18n/reviews.yml" && existsSync(path)) continue;
+		await writeFile(path, file.content);
+	}
+	if (options.json) {
+		printJson("migrate", {
+			...result,
+			written: !options.dryRun
+		});
+		return;
+	}
+	for (const file of result.files) out(options.dryRun ? `--- ${file.path}\n${file.content}` : `wrote ${file.path}`);
+	for (const note of result.notes) out(`note: ${note}`);
+	if (result.removable.length) out(`These i18n-ally settings can be removed now:\n${result.removable.map((key) => `  ${key}`).join("\n")}`);
+}
+//#endregion
+//#region src/commands/prompt.ts
+async function prompt(kind, options) {
+	if (kind !== "translate" && kind !== "review") throw new X18nError("X18N0001", `unknown prompt "${kind}" (translate, review)`);
+	const locale = kind === "translate" ? options.to : options.locale ?? options.to;
+	if (!locale) throw new X18nError("X18N0001", kind === "translate" ? "pass --to <locale>" : "pass --locale <locale>");
+	const { project, host } = singleProject(await openWorkspace(options));
+	if (options.stale) {
+		await project.loadHistory();
+		await host.flush();
+	}
+	const data = project.prompt(kind, locale, {
+		keys: options.keys,
+		namespace: options.namespace,
+		limit: options.limit === void 0 ? void 0 : Number(options.limit),
+		cursor: options.cursor,
+		context: options.context,
+		stale: options.stale
+	});
+	if (options.json || options.format === "json") printJson(`prompt ${kind}`, data);
+	else out(renderPrompt(data));
+}
+//#endregion
+//#region src/commands/setup.ts
+async function schema(name, options) {
+	const which = name ?? "config";
+	if (which !== "config" && which !== "plugin") throw new X18nError("X18N0001", `unknown schema "${which}" (config, plugin)`);
+	const require = createRequire(import.meta.url);
+	const text = await readFile(require.resolve(`@x18n/core/schema/${which}.json`), "utf8");
+	if (options.json) printJson("schema", {
+		name: which,
+		schema: JSON.parse(text)
+	});
+	else out(text);
+}
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** The folders and file name that name `namespace`, in the style of `namespace.fromPath`. */
+function namespaceSpan(parts, namespace, fromPath) {
+	for (let start = 0; start < parts.length; start++) for (let end = start + 1; end <= parts.length; end++) if (namespaceFromPath(parts.slice(start, end).join("/"), fromPath) === namespace) return {
+		start,
+		end
+	};
+}
+/** The resource pattern that matches a found file: `public/locales/en/common.json` → `public/locales/{locale}/{namespaces}.{ext}`. */
+function patternOf(resource, fromPath) {
+	const parts = resource.path.replace(/\.[^./]+$/, "").split("/");
+	const span = resource.namespace === void 0 ? void 0 : namespaceSpan(parts, resource.namespace, fromPath);
+	if (span) parts.splice(span.start, span.end - span.start, "{namespaces}");
+	return `${parts.join("/")}.{ext}`.replace(new RegExp(`(^|[/._-])${escapeRegExp(resource.locale)}(?=[/._-])`), "$1{locale}");
+}
+async function init(options) {
+	const root = resolve(options.root ?? cwd());
+	const existing = findConfigFile(root);
+	if (existing && !options.force) throw new X18nError("X18N0001", `${existing} already exists (pass --force to replace it)`);
+	const { project } = (await loadWorkspace({
+		cwd: root,
+		cache: false
+	})).projects[0];
+	const detected = project.explain().presets.filter((p) => p.reason === "detected" && p.name !== "general").map((p) => p.name);
+	const resources = [...new Set(project.resources.filter((r) => !r.block).map((r) => patternOf(r, project.config.namespace.fromPath)))];
+	const config = {
+		sourceLocale: project.sourceLocale,
+		resources: resources.map((pattern) => ({ pattern }))
+	};
+	const format = options.format ?? "ts";
+	let file;
+	let content;
+	if (format === "yml" || format === "yaml") {
+		file = join(root, "x18n.config.yml");
+		content = `# yaml-language-server: $schema=https://x18n.antfu.dev/schema/config.json\n${stringify(config)}`;
+	} else if (format === "json") {
+		file = join(root, "x18n.config.json");
+		content = `${JSON.stringify({
+			$schema: "https://x18n.antfu.dev/schema/config.json",
+			...config
+		}, null, 2)}\n`;
+	} else {
+		file = join(root, "x18n.config.ts");
+		const body = JSON.stringify(config, null, 2).replace(/"(\w+)":/g, "$1:").replace(/"/g, "'");
+		content = `import { defineConfig } from '@x18n/core'\n\n// Detected presets: ${detected.join(", ") || "none"}. They apply automatically.\nexport default defineConfig(${body})\n`;
+	}
+	if (!configFileNames.some((name) => file.endsWith(name))) throw new X18nError("X18N0001", `unknown format "${format}" (ts, yml, json)`);
+	await writeFile(file, content);
+	if (options.json) printJson("init", {
+		file,
+		presets: detected,
+		config
+	});
+	else out(`Wrote ${file}\nDetected presets: ${detected.join(", ") || "none"}\nLocales: ${project.locales.join(", ")}`);
+}
+const literal = (value) => JSON.stringify(value, null, 2).replace(/"([a-z_$][\w$]*)":/gi, "$1:");
+/** The TS plugin equivalent of a YAML plugin, using the same built-in factories. */
+function ejectPlugin(data) {
+	const lines = [];
+	const configLines = [];
+	if (data.config) configLines.push(`    Object.assign(config, ${literal(data.config).replace(/\n/g, "\n    ")})`);
+	if (data.scanners?.calls || data.scanners?.regex) {
+		configLines.push(`    config.usage = {`, `      ...config.usage,`);
+		if (data.scanners.calls) configLines.push(`      calls: [...config.usage.calls, ...${literal(data.scanners.calls).replace(/\n/g, "\n      ")}],`);
+		if (data.scanners.regex) configLines.push(`      regex: [...config.usage.regex, ...${literal(data.scanners.regex).replace(/\n/g, "\n      ")}],`);
+		configLines.push(`    }`);
+	}
+	const fields = [`  name: ${literal(data.name)},`];
+	if (configLines.length) fields.push(`  config(config) {`, ...configLines, `  },`);
+	if (data.derivedKeys) fields.push(`  derivedKeys: ${literal(data.derivedKeys)},`);
+	if (data.placeholders) fields.push(`  placeholders: ${literal(data.placeholders)}.map(placeholderFromShape),`);
+	if (data.normalizeKey) {
+		const rules = data.normalizeKey.map((rule) => `.replace(new RegExp(${literal(rule.replace.pattern)}, 'g'), ${literal(rule.replace.with)})`).join("");
+		fields.push(`  normalizeKey: raw => raw${rules},`);
+	}
+	if (data.localeInfo) fields.push(`  localeInfo: code => (${literal(data.localeInfo)} as Record<string, { flag?: string, displayName?: string }>)[code],`);
+	const imports = ["definePlugin", ...data.detect ? ["definePreset"] : []];
+	lines.push(`import { ${imports.join(", ")} } from '@x18n/core'`);
+	if (data.placeholders) lines.push(`import { placeholderFromShape } from '@x18n/builtins/placeholders'`);
+	if (data.scopes) lines.push(`import { regexScopes } from '@x18n/builtins/scanners'`);
+	lines.push("", `const plugin = definePlugin({`, ...fields, `})`, "");
+	const plugins = `[plugin${data.scopes ? `, regexScopes(${literal(data.scopes.regex)})` : ""}]`;
+	if (data.detect) {
+		const any = data.detect.dependencies?.any;
+		lines.push(`export default definePreset({`, `  name: ${literal(data.name)},`, ...data.exclusive ? [`  exclusive: true,`] : [], `  detect: ctx => ${any ? `ctx.hasAnyDependency(${literal(any)})` : "true"},`, `  plugins: ${plugins},`, `})`);
+	} else lines.push(data.scopes ? `export default ${plugins}` : "export default plugin");
+	return `${lines.join("\n")}\n`;
+}
+async function eject(file, options) {
+	const path = resolve(cwd(), file);
+	if (!existsSync(path)) throw new X18nError("X18N1001", path);
+	const result = validate(PluginFileSchema, parse(await readFile(path, "utf8")));
+	if (!result.success) throw new X18nError("X18N1004", result.issues.map((i) => `${i.path}: ${i.message}`).join("; "));
+	const code = ejectPlugin(result.output);
+	if (options.json) printJson("plugin eject", {
+		file: path,
+		code
+	});
+	else out(code);
+}
+//#endregion
+//#region src/cli.ts
+const uiCommands = () => import("./ui-Bp3xyqr_.mjs");
+/** Runs a command and turns errors into the JSON envelope or a printed hint, with the matching exit code. */
+function run(command, action) {
+	return async (...args) => {
+		const options = args.at(-1);
+		try {
+			const code = await action(...args);
+			process.exitCode = code ?? 0;
+		} catch (error) {
+			const info = errorInfo(error);
+			if (options.json) printJson(command, null, [], [info]);
+			else {
+				process.stderr.write(`error ${info.code}: ${info.message}\n`);
+				if (info.hint) process.stderr.write(`  ${info.hint}\n`);
+				if (!(error instanceof Error && "code" in error) && error instanceof Error && process.env.DEBUG) process.stderr.write(`${error.stack}\n`);
+			}
+			process.exitCode = exitCodeOf(error);
+		}
+	};
+}
+function createCli() {
+	const cli = cac("x18n");
+	cli.option("--root <dir>", "Project root (default: nearest config upward from the cwd)").option("--config <file>", "Explicit config file").option("--project <name>", "Pick one project in a monorepo").option("--json", "Print the JSON contract instead of human output").option("--no-cache", "Ignore the persistent cache").option("--yes", "Accept default answers for decisions");
+	cli.command("", "Show the status and the main commands").action(run("status", async (options) => {
+		await status(options);
+		if (!options.json) process.stdout.write("\nCommands: check, keys, get, usages, set, apply, rename, delete, fill, prompt translate, ui. Run `x18n --help` for all.\n");
+	}));
+	cli.command("status", "Locales with coverage, resources, keys and diagnostics").action(run("status", status));
+	cli.command("keys [glob]", "List keys").option("--missing <locale>", "Only keys missing or empty in a locale").option("--unused", "Only keys without usages").option("--namespace <ns>", "Only keys of a namespace").option("--values", "Include the value per locale").option("--limit <n>", "Page size").option("--cursor <cursor>", "Start of the page (from `nextCursor`)").action(run("keys", keys));
+	cli.command("get <key>", "Values, resources, usages and diagnostics of one key").action(run("get", get));
+	cli.command("usages [key]", "Usages of a key, or all usages").option("--file <path>", "Only usages in a file").option("--limit <n>", "Page size").option("--cursor <cursor>", "Start of the page").action(run("usages", usages));
+	cli.command("locales", "Locale codes as found, with display names and resources").action(run("locales", locales));
+	cli.command("doctor", "How the project was understood: presets, finders, formats, scanners, config origins").action(run("doctor", doctor));
+	cli.command("check", "Report invalid, untranslated and unused keys, like `tsc --noEmit`").option("--watch", "Re-check on change").option("--strict", "Turn every warning into an error").option("--locale <locale>", "Only report for these locales (repeatable)").option("--only <checks>", "Only these check ids (comma separated)").option("--skip <checks>", "Skip these check ids (comma separated)").option("--max-warnings <n>", "Fail when there are more warnings").option("--reporter <id>", "pretty, json, markdown, github or sarif (repeatable)").option("--output <file>", "Write the matching reporter output to a file (repeatable)").action(run("check", check));
+	cli.command("set <key>", "Set one value").option("--locale <locale>", "Locale (default: source locale)").option("--value <value>", "The value; `-` reads stdin").option("--dry-run", "Print the plan instead of writing").action(run("set", set));
+	cli.command("apply <file>", "Batch set from JSON `{ \"<locale>\": { \"<key>\": \"<value>\" } }`; `-` reads stdin").option("--force", "Write values with placeholder problems").option("--dry-run", "Print the plan instead of writing").action(run("apply", apply));
+	cli.command("rename <from> <to>", "Rename a key (or every key under a parent) in all locales and usages").option("--no-usages", "Keep code unchanged").option("--dry-run", "Print the plan instead of writing").action(run("rename", rename));
+	cli.command("delete <key>", "Delete a key (or every key under a parent) in all locales").option("--locale <locale>", "Only in these locales (repeatable)").option("--dry-run", "Print the plan instead of writing").action(run("delete", remove));
+	cli.command("fill", "Add missing keys with empty values").option("--locale <locale>", "Only these locales (repeatable)").option("--copy-source", "Use the source value instead of an empty string").option("--dry-run", "Print the plan instead of writing").action(run("fill", fill));
+	cli.command("format", "Re-write resources with the configured sort and indent").option("--dry-run", "Print the plan instead of writing").action(run("format", format));
+	cli.command("extract [...files]", "Find hard-coded strings and turn them into keys").option("--list", "Print candidates and proposed keys").option("--plan <file>", "Write the extraction plan to a file to edit").option("--apply <file>", "Apply an (edited) extraction plan").option("--dry-run", "Print the plan instead of writing").action(run("extract", extract));
+	cli.command("prompt <kind>", "Print a prompt for an agent or LLM: `prompt translate --to <locale>` or `prompt review --locale <locale>`").option("--to <locale>", "Target locale (translate)").option("--locale <locale>", "Locale to review").option("--keys <glob>", "Only keys matching a glob").option("--namespace <ns>", "Only keys of a namespace").option("--limit <n>", "Messages per prompt (default 50)").option("--cursor <cursor>", "Continue from `nextCursor`").option("--format <format>", "markdown (default) or json").option("--no-context", "Leave out code around usages").option("--stale", "Also translate stale translations (needs git history)").action(run("prompt", prompt));
+	cli.command("ui", "Start the UI: browse and edit messages in the browser, with HTTP MCP at /__mcp").option("--port <port>", "Port (default: a free one from 9999)").option("--host <host>", "Bind host (default: localhost)").option("--no-open", "Do not open the browser").option("--no-auth", "Skip authentication (CI and e2e only)").action(run("ui", async (options) => (await uiCommands()).ui(options)));
+	cli.command("build", "Write a static, read-only report of the UI").option("--out-dir <dir>", "Output directory (default: .x18n/report)").action(run("build", async (options) => (await uiCommands()).build(options)));
+	cli.command("mcp", "Serve the MCP tools over stdio").action(run("mcp", async (options) => (await uiCommands()).mcp(options)));
+	cli.command("init", "Detect the setup and write x18n.config.ts").option("--format <format>", "ts (default), yml or json").option("--force", "Replace an existing config").action(run("init", init));
+	cli.command("migrate <source>", "Convert i18n-ally settings: `migrate i18n-ally`").option("--format <format>", "ts (default), yml or json").option("--dry-run", "Print the files instead of writing").option("--force", "Replace an existing config").action(run("migrate", migrate));
+	cli.command("schema [name]", "Print a JSON Schema: config (default) or plugin").action(run("schema", schema));
+	cli.command("plugin <action> <file>", "Plugin tools: `plugin eject <file.yml>` prints the TS equivalent").action(run("plugin eject", async (action, file, options) => {
+		if (action !== "eject") throw new Error(`unknown plugin action "${action}"`);
+		await eject(file, options);
+	}));
+	cli.help();
+	cli.version(version);
+	return cli;
+}
+process.stdout.on("error", (error) => {
+	if (error.code === "EPIPE") process.exit(0);
+	throw error;
+});
+const argv = process.argv.map((arg) => arg === "-" ? stdinArg : arg);
+try {
+	createCli().parse(argv);
+} catch (error) {
+	process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 2;
+}
+//#endregion
+export { createCli };

package/dist/context-Za_ea1Nk.mjs

@@ -0,0 +1,148 @@
+import { X18nError, applyTextEdits, envelope, isX18nError, toWireDiagnostic } from "@x18n/core";
+import process from "node:process";
+import { Buffer } from "node:buffer";
+import { readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { loadWorkspace, stderrLogger } from "@x18n/node";
+//#region src/context.ts
+const cwd = () => process.cwd();
+function useColor(options) {
+	if (options.json || process.env.NO_COLOR) return false;
+	if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") return true;
+	return process.stdout.isTTY === true;
+}
+async function openWorkspace(options) {
+	return loadWorkspace({
+		cwd: options.root ?? cwd(),
+		configFile: options.config,
+		upward: options.root === void 0,
+		project: options.project,
+		cache: options.cache !== false,
+		logger: stderrLogger
+	});
+}
+/** Write commands work on one project; a monorepo needs `--project`. */
+function singleProject(workspace) {
+	if (workspace.projects.length !== 1) throw new X18nError("X18N0003", `pick one with --project (${workspace.projects.map((p) => p.name).join(", ")})`);
+	return workspace.projects[0];
+}
+function displayPath(root, path) {
+	return relative(cwd(), join(root, path)).replace(/\\/g, "/") || ".";
+}
+function out(text) {
+	process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+function printJson(command, data, diagnostics = [], errors = []) {
+	const value = envelope(command, data, diagnostics, errors);
+	out(JSON.stringify(value, null, 2));
+}
+function wireDiagnostics(loaded, diagnostics) {
+	return diagnostics.map((d) => toWireDiagnostic(loaded.name, d, (path) => loaded.project.text(path)));
+}
+/** Exit code for an error: 2 usage or config, 3 decision needed, 4 stale plan, 1 otherwise. */
+function exitCodeOf(error) {
+	if (!isX18nError(error)) return 2;
+	if (error.code === "X18N4003") return 3;
+	if (error.code === "X18N4004") return 4;
+	return /^X18N[01]/.test(error.code) ? 2 : 1;
+}
+function errorInfo(error) {
+	if (isX18nError(error)) return error.toJSON();
+	return {
+		code: "X18N0002",
+		message: error instanceof Error ? error.message : String(error),
+		hint: "",
+		docs: ""
+	};
+}
+/** Stands for a lone `-` argument (stdin). */
+const stdinArg = "\0stdin";
+async function readInput(source) {
+	if (source !== "-" && source !== "\0stdin") return readFile(source, "utf8");
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+	return Buffer.concat(chunks).toString("utf8");
+}
+/** Answers for the plan's decisions: defaults with `--yes`, a prompt in a TTY, else an error. */
+async function answer(plan, options) {
+	const answers = {};
+	if (plan.decisions.length === 0) return answers;
+	if (options.yes) {
+		for (const decision of plan.decisions) answers[decision.id] = decision.default;
+		return answers;
+	}
+	if (options.json || !process.stdin.isTTY) throw new X18nError("X18N4003", plan.decisions.map((d) => `${d.message} (${d.options.map((o) => o.id).join(" | ")})`).join(" "), plan.decisions.map((d) => d.id));
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		for (const decision of plan.decisions) {
+			process.stderr.write(`${decision.message}\n${decision.options.map((o, i) => `  ${i + 1}) ${o.label}`).join("\n")}\n`);
+			const reply = await rl.question(`Choose [1]: `);
+			const option = decision.options[Number(reply || "1") - 1] ?? decision.options[0];
+			answers[decision.id] = option.id;
+		}
+	} finally {
+		rl.close();
+	}
+	return answers;
+}
+/** Changes as a small line diff, for `--dry-run` and the summary after a write. */
+function formatPlan(project, root, plan) {
+	const lines = [];
+	for (const change of plan.changes) {
+		const path = displayPath(root, change.path);
+		if (change.type === "create") {
+			lines.push(`create ${path}`, ...change.content.split("\n").filter(Boolean).map((line) => `+ ${line}`));
+			continue;
+		}
+		if (change.type === "delete") {
+			lines.push(`delete ${path}`);
+			continue;
+		}
+		const before = project.text(change.path) ?? "";
+		const after = applyTextEdits(before, change.edits);
+		const a = before.split("\n");
+		const b = after.split("\n");
+		let start = 0;
+		while (start < a.length && start < b.length && a[start] === b[start]) start++;
+		let endA = a.length;
+		let endB = b.length;
+		while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+			endA--;
+			endB--;
+		}
+		lines.push(`edit ${path}`, ...a.slice(start, endA).map((line) => `- ${line}`), ...b.slice(start, endB).map((line) => `+ ${line}`));
+	}
+	for (const warning of plan.warnings) lines.push(`warning: ${warning}`);
+	return lines.length ? lines.join("\n") : "No changes.";
+}
+function planData(root, plan, applied) {
+	return {
+		applied,
+		keys: plan.keys,
+		warnings: plan.warnings,
+		decisions: plan.decisions,
+		changes: plan.changes.map((change) => ({
+			...change,
+			file: displayPath(root, change.path)
+		}))
+	};
+}
+/** Plans, asks, then applies (or prints with `--dry-run`). */
+async function runPlan(command, loaded, plan, options) {
+	if (options.dryRun) {
+		if (options.json) printJson(command, planData(loaded.root, plan, false));
+		else out(formatPlan(loaded.project, loaded.root, plan));
+		return;
+	}
+	const answers = await answer(plan, options);
+	const preview = formatPlan(loaded.project, loaded.root, plan);
+	await loaded.project.apply(plan, { answers });
+	if (options.json) printJson(command, planData(loaded.root, plan, true));
+	else out(preview);
+}
+//#endregion
+export { openWorkspace as a, readInput as c, stdinArg as d, useColor as f, exitCodeOf as i, runPlan as l, displayPath as n, out as o, wireDiagnostics as p, errorInfo as r, printJson as s, cwd as t, singleProject as u };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { Check, Format, LocaleFinder, Plugin, Preset, Reporter, Scanner, UserConfig, defineConfig, definePlugin, definePreset } from "@x18n/core";
+export { type Check, type Format, type LocaleFinder, type Plugin, type Preset, type Reporter, type Scanner, type UserConfig, defineConfig, definePlugin, definePreset };

package/dist/index.mjs

@@ -0,0 +1 @@
+export { defineConfig, definePlugin, definePreset } from "@x18n/core";

package/dist/presets.d.mts

@@ -0,0 +1 @@
+export * from "@x18n/builtins/presets";

package/dist/presets.mjs

@@ -0,0 +1,2 @@
+export * from "@x18n/builtins/presets";
+export {};

package/dist/ui-Bp3xyqr_.mjs

@@ -0,0 +1,74 @@
+import { a as openWorkspace, o as out, s as printJson, t as cwd } from "./context-Za_ea1Nk.mjs";
+import process from "node:process";
+import { join, resolve } from "node:path";
+import { createX18nDevframe } from "@x18n/ui";
+import { createBuild } from "devframe/adapters/build";
+import { createDevServer } from "devframe/adapters/dev";
+import { createMcpServer } from "devframe/adapters/mcp";
+import { buildOtpAuthUrl, getTempAuthCodeInfo } from "devframe/node/auth";
+import { randomToken } from "devframe/utils/crypto-token";
+import { launchEditor } from "devframe/utils/launch-editor";
+//#region src/commands/ui.ts
+/** Starts the UI dev server and keeps running until interrupted. */
+async function ui(options) {
+	const workspace = await openWorkspace(options);
+	workspace.projects.forEach((p) => p.project.watch());
+	const editor = process.env.LAUNCH_EDITOR || process.env.VISUAL || process.env.EDITOR;
+	const definition = createX18nDevframe(workspace.projects, { openInEditor: editor ? async ({ project, path, line, column }) => launchEditor(`${join(project.root, path)}:${line}:${column}`, editor) : void 0 });
+	const mcpToken = randomToken();
+	const auth = options.auth !== false;
+	if (!auth) process.stderr.write("warning: --no-auth lets anything that reaches the port edit your files. Use it only in CI and e2e tests.\n");
+	const server = await createDevServer(definition, {
+		host: options.host ?? "localhost",
+		...options.port === void 0 ? {} : { port: Number(options.port) },
+		auth,
+		openBrowser: options.open !== false,
+		mcp: { authorization: mcpToken }
+	});
+	const url = `${server.origin}/`;
+	const code = auth ? getTempAuthCodeInfo().code : void 0;
+	const mcp = {
+		url: `${url}__mcp`,
+		token: mcpToken
+	};
+	if (options.json) printJson("ui", {
+		url,
+		code,
+		link: code && buildOtpAuthUrl(url, code),
+		mcp
+	});
+	else {
+		out(`x18n UI at ${url}`);
+		if (code) out(`  auth code  ${code}\n  or open    ${buildOtpAuthUrl(url, code)}`);
+		out(`  MCP        ${mcp.url}\n  MCP token  Authorization: Bearer ${mcp.token}`);
+	}
+	const stop = () => {
+		server.close().finally(() => process.exit(0));
+	};
+	process.once("SIGINT", stop);
+	process.once("SIGTERM", stop);
+}
+async function build(options) {
+	const workspace = await openWorkspace(options);
+	const outDir = resolve(cwd(), options.outDir ?? ".x18n/report");
+	const log = console.log;
+	console.log = console.error;
+	try {
+		await createBuild(createX18nDevframe(workspace.projects), { outDir });
+	} finally {
+		console.log = log;
+	}
+	if (options.json) printJson("build", { outDir });
+	else out(`Wrote the report to ${outDir}`);
+}
+/** MCP over stdio: stdout is the transport, so nothing else may print there. */
+async function mcp(options) {
+	const workspace = await openWorkspace(options);
+	workspace.projects.forEach((p) => p.project.watch());
+	await createMcpServer(createX18nDevframe(workspace.projects), {
+		transport: "stdio",
+		serverName: "x18n"
+	});
+}
+//#endregion
+export { build, mcp, ui };

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@x18n/cli",
   "type": "module",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "description": "Manage and view i18n files of any project, for humans and agents",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
   "funding": "https://github.com/sponsors/antfu",
-  "homepage": "https://github.com/antfu/x18n#readme",
+  "homepage": "https://github.com/x18n-dev/x18n#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/antfu/x18n.git",
+    "url": "git+https://github.com/x18n-dev/x18n.git",
     "directory": "packages/cli"
   },
-  "bugs": "https://github.com/antfu/x18n/issues",
+  "bugs": "https://github.com/x18n-dev/x18n/issues",
   "keywords": [
     "i18n",
     "cli",
@@ -38,12 +38,12 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@x18n/builtins": "0.0.2",
-    "@x18n/core": "0.0.2",
-    "@x18n/node": "0.0.2",
-    "@x18n/ui": "0.0.2",
+    "@x18n/builtins": "0.0.5",
+    "@x18n/core": "0.0.5",
+    "@x18n/node": "0.0.5",
+    "@x18n/ui": "0.0.5",
     "cac": "^7.1.0",
-    "devframe": "^1.2.5",
+    "devframe": "^1.2.6",
     "yaml": "^2.9.1"
   },
   "scripts": {

package/skills/x18n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: x18n
-description: Set up and run x18n (`@x18n/cli`) to check and manage a project's translations. Use when the task touches locale files or translation keys - adding, renaming or deleting keys, finding missing or unused keys, translating missing messages, extracting hard-coded strings, keeping a glossary of terms - or when setting up x18n or migrating from i18n-ally.
+description: Manage a project's translations with x18n (`@x18n/cli`). Use when the task touches locale files or translation keys - adding, renaming or deleting keys, finding missing or unused keys, translating missing messages, reviewing translations, extracting hard-coded strings, keeping a glossary of terms.
 ---
 
 # x18n
@@ -17,7 +17,6 @@ You do the legwork; the user makes the **decisions** that shape the product. Bef
 - tone and formality per locale (German *du* or *Sie*, French *tu* or *vous*)
 - deleting keys that look unused, since keys built at runtime look unused too
 - renames that touch many files or move keys between namespaces
-- turning on checks, and making warnings fail CI with `--strict`
 
 Batch the questions into one message. Routine work needs no question: adding a key you use, translating a missing message, fixing a placeholder.
 
@@ -28,14 +27,51 @@ Batch the questions into one message. Routine work needs no question: adding a k
 - Keep every placeholder of the source message (`{name}`, `{{count}}`, `%{name}`, `:name`, `%s`, `@:key`).
 - Pass `--json` and read the envelope `{ "x18n": 1, "command", "data", "diagnostics", "errors" }`.
 - Run renames and deletes with `--dry-run` first, and read the plan.
+- Write every key as a full string literal. Do not build keys at runtime (see below).
 
-## Set up x18n
+## Avoid composed keys
 
-1. Run `npx @x18n/cli doctor` in the project root. Without a config, x18n uses the project's i18n-ally settings if it has any, and detects the i18n library and the locale files. Check the detected presets, the locale files and the source locale. **Done when** the doctor output names the library the project uses and lists every locale file.
-2. If the project has i18n-ally settings (`i18n-ally.*` keys in `.vscode/settings.json`), follow [references/migrate-i18n-ally.md](references/migrate-i18n-ally.md) instead of step 3.
-3. If detection is wrong or incomplete, run `x18n init` to write `x18n.config.ts`, then fix `resources`, `sourceLocale` or `presets` in it. `x18n init --format yml` writes YAML for projects without Node.js tooling. **Done when** `x18n doctor` shows the right result.
-4. Install the CLI as a dev dependency with the project's package manager (`pnpm add -D @x18n/cli`), and add a script such as `"i18n:check": "x18n check"`. Ask the user before you add it to CI.
-5. Run `x18n check --json` and report the summary to the user. **Done when** the user has the counts of errors and warnings per check, and has decided what to fix first.
+Do not build a key from parts, such as `` t(`foo.bar.${name}`) `` or `t('foo.bar.' + name)`. x18n and the compiler cannot see the full key, so:
+
+- `x18n keys --unused` reports the key as unused, and `x18n delete` can remove a message that the code needs
+- `x18n rename` does not update the usage
+- `x18n check` cannot find a missing message until the user hits it at runtime
+- translators cannot see the full key in context
+
+Write each key out in full and map the value to it:
+
+```ts
+// Avoid
+t(`status.${status}`)
+
+// Prefer: a lookup of full literal keys
+const labels = {
+  active: t('status.active'),
+  paused: t('status.paused'),
+} as const
+labels[status]
+```
+
+```ts
+// Avoid
+t(`plans.${plan}.title`)
+
+// Prefer: a switch, or a record of functions when the call must be lazy
+const planTitle = {
+  free: () => t('plans.free.title'),
+  pro: () => t('plans.pro.title'),
+}
+planTitle[plan]()
+```
+
+When the variable part is only a word inside a sentence, use a placeholder instead of a key part: `t('greeting', { name })` with the message `Hello, {name}`. When the text differs by count, use the library's plural syntax, not `t(count === 1 ? 'item.one' : 'item.many')`.
+
+If the user's code already composes keys, do not rewrite it unasked. Tell the user which keys are affected, and treat those keys as used when you clean up.
+
+## Set up and check
+
+- To set up x18n, or migrate from i18n-ally, use the `x18n-setup` skill.
+- To run `x18n check` and fix what it reports, use the `x18n-check` skill.
 
 Commands below use `x18n`; without the dev dependency, run them as `npx @x18n/cli <command>`.
 
@@ -65,13 +101,6 @@ Maintain it while you work:
 
 ## Loops
 
-### Check the project
-
-```sh
-x18n check --json
-x18n status --json
-```
-
 ### Add a key while coding
 
 ```sh
@@ -134,6 +163,16 @@ x18n extract --apply extract-plan.json --json
 
 Edit the keys in the plan file before you apply it. The proposed keys follow the project's style; ask the user when there is none yet.
 
+Tests, fixtures, mocks, stories, configs and type declarations are never scanned, in any language (`*.test.ts`, `*_test.go`, `test_*.py`, `*_spec.rb`, `*Test.java`, `vite.config.ts`, `tests/`, `spec/`, `e2e/`, ...). To keep strings that are not UI text out of the plan, drop them from the plan file, or add a control comment to the code:
+
+| Comment | Skips |
+| --- | --- |
+| `x18n-ignore-file` | the whole file, wherever the comment is |
+| `x18n-ignore-start` ... `x18n-ignore-end` | everything between them (to the end of the file when unclosed) |
+| `x18n-ignore` | strings on its line and on the next line |
+
+Use any comment syntax: `// x18n-ignore-file`, `<!-- x18n-ignore -->`. For strings that recur across files, use `extract.ignore` in the config instead.
+
 ## Output
 
 Exit codes:

package/skills/x18n-check/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: x18n-check
+description: Run `x18n check` and fix what it reports - missing keys and translations, placeholder mismatches, invalid message syntax, unused keys, glossary violations. Use when the user asks to check, lint or fix translations, when `x18n check` fails locally or in CI, or before opening a PR that touches locale files or translation keys.
+---
+
+# Check and fix translations
+
+`x18n check` reports broken, untranslated and unused messages, like `tsc --noEmit` for i18n. Run it, fix the routine problems, and bring the rest to the user. Change locale files only through the `x18n` CLI (`set`, `apply`, `rename`, `delete`), never by hand. The `x18n` skill covers those commands.
+
+If the project has no x18n setup yet, use the `x18n-setup` skill first.
+
+## Decisions belong to the user
+
+Before you act on one of these, stop and ask, with your recommendation and the facts you found. Batch the questions into one message.
+
+- deleting keys reported as unused, since keys built at runtime look unused too
+- a glossary term and its translation per locale
+- changing the severity of a check in the `checks` map of the config, such as `'unused-key': 'error'` or `glossary: 'warning'`
+- making warnings fail CI with `--strict` or `--max-warnings <n>`
+
+## Loop
+
+1. Run `x18n check --json`. Read `data.projects[].summary` for the counts and `diagnostics` for the problems. Group the diagnostics by `code` and `severity`. **Done when** you know the count per check, errors first.
+2. Fix the errors, check by check, with the table below. Re-run only that check to confirm: `x18n check --only placeholder-mismatch --json`. **Done when** the summary shows no errors, or each remaining error waits on a user decision.
+3. Fix the warnings you can fix without a decision, such as missing translations. **Done when** the remaining warnings each need a decision.
+4. Ask the user about the remaining diagnostics in one message: list them by check, with your recommendation for each. Apply what they decide.
+5. Run `x18n check --json` again and report the result. **Done when** `x18n check` exits with code 0, or every remaining diagnostic is one the user chose to keep.
+
+## Fixes per check
+
+| Check (`code`) | Fix |
+| --- | --- |
+| `missing-key` | A usage names a key the source locale lacks. If it is a typo, fix the usage to an existing key (`x18n keys` lists them). Else add it: `x18n set <key> --value <text> --json`. |
+| `missing-translation`, `empty-translation` | Translate: `x18n prompt translate --to <locale> --limit 50`, write the result to a file, then `x18n apply <file> --json`. Follow `nextCursor` when the prompt reports more keys. |
+| `placeholder-mismatch` | Rewrite the target value with every placeholder of the source: `x18n set <key> --locale <locale> --value <text> --json`. |
+| `invalid-syntax` | Fix the message syntax (ICU braces, linked messages) with `x18n set`. When a linked message does not exist, fix the link or add that key. |
+| `key-conflict` | A key is both a message and a parent, or is defined twice in one locale. Ask which one to keep, then `x18n rename` or `x18n delete` with `--dry-run` first. |
+| `unused-key` | Show the list from `x18n keys --unused --json` and delete only the keys the user confirms: `x18n delete <key> --dry-run --json`, then without `--dry-run`. Keys built at runtime go in `usage.keysInUse` in the config instead. |
+| `glossary` | Rewrite the message with the term from the glossary (`x18n doctor --json` lists it under `config.glossary`), with `x18n set`. |
+| `locale-code-conflict`, `dynamic-key`, `key-style`, `identical-to-source`, `hard-string` | Report them. Fix only when the user asks; `hard-string` is fixed with `x18n extract`, or silenced with an `x18n-ignore` control comment when the string is not UI text. |
+
+After a batch of fixes, check only what you touched: `x18n check --only placeholder-mismatch,invalid-syntax,glossary --locale de --json`.
+
+## CI
+
+`x18n check` exits with code 1 on errors, so CI fails on broken keys without more setup. Warnings do not fail it unless the project uses `--strict` or `--max-warnings <n>`. For pull request annotations, use `x18n check --reporter github --reporter pretty`. Change none of this without asking.

package/skills/x18n-setup/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: x18n-setup
+description: Set up x18n (`@x18n/cli`) in a project, or migrate it from i18n-ally. Use when a project has no x18n config yet, when x18n detects the wrong locale files or library, when the user asks to add, install or configure x18n, or when `.vscode/settings.json` has `i18n-ally.*` settings.
+---
+
+# Set up x18n
+
+x18n reads a project's i18n setup (locale files, translate calls in code) and often needs no config. Set it up by checking what it detects, and write a config only when detection needs help.
+
+## Decisions belong to the user
+
+Before you act on one of these, stop and ask, with your recommendation and the facts you found. Batch the questions into one message.
+
+- the source locale, and which locales the project supports
+- the config format: `x18n.config.ts`, or YAML for projects without Node.js tooling
+- what an i18n-ally migration drops (see the reference below)
+- adding `x18n check` to CI or to a git hook
+
+## Steps
+
+1. Run `npx @x18n/cli doctor` in the project root. Without a config, x18n uses the project's i18n-ally settings if it has any, and detects the i18n library and the locale files. Check the detected presets, the locale files and the source locale. **Done when** the doctor output names the library the project uses and lists every locale file.
+2. If the project has i18n-ally settings (`i18n-ally.*` keys in `.vscode/settings.json`), follow [references/migrate-i18n-ally.md](references/migrate-i18n-ally.md) instead of step 3.
+3. If detection is wrong or incomplete, run `x18n init` to write `x18n.config.ts`, then fix `resources`, `sourceLocale` or `presets` in it. `x18n init --format yml` writes YAML. **Done when** `x18n doctor` shows the right result.
+4. Install the CLI as a dev dependency with the project's package manager (`pnpm add -D @x18n/cli`), and add a script such as `"i18n:check": "x18n check"`. Ask the user before you add it to CI.
+5. Run `x18n check --json` and report the summary to the user: errors and warnings per check (`code` of each diagnostic) and coverage per locale. Do not fix anything in this skill. **Done when** the user has the counts and knows that the `x18n-check` skill fixes them.
+
+Without the dev dependency, run commands as `npx @x18n/cli <command>`. In a monorepo, `x18n status --json` lists every project; pass `--project <name>` to pick one.