@x18n/cli 0.0.0-stage → 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './dist/cli.mjs'

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,672 @@
+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 { parse, stringify } from "yaml";
+//#region package.json
+var version = "0.0.0";
+//#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
+			}
+		};
+	});
+}
+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);
+	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 info = project.localeInfo(c.locale);
+			const label = `${c.locale}${c.locale === project.sourceLocale ? " (source)" : ""}`;
+			out(`  ${info.flag ?? "  "} ${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.flag ?? "  "} ${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:`);
+		for (const p of e.presets) out(`  ${p.reason === "detected" || p.reason === "listed" ? "✓" : "·"} ${p.name} (${p.reason})`);
+		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 } = singleProject(await openWorkspace(options));
+	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
+	});
+	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);
+}
+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 explanation = project.explain();
+	const detected = explanation.presets.filter((p) => p.reason === "detected" && p.name !== "general").map((p) => p.name);
+	const resources = explanation.config.resources.length > 0 ? explanation.config.resources.map((r) => r.pattern) : [...new Set(project.resources.map((r) => r.path.replace(new RegExp(`(^|/)${r.locale}(?=[./])`), "$1{locale}").replace(/\.[^.]+$/, ".{ext}")))];
+	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").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,6 +1,54 @@
 {
   "name": "@x18n/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "0.0.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antfu/x18n.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/antfu/x18n/issues",
+  "keywords": [
+    "i18n",
+    "cli",
+    "locale",
+    "translation"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./presets": "./dist/presets.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "bin": {
+    "x18n": "./bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@x18n/builtins": "0.0.0",
+    "@x18n/core": "0.0.0",
+    "@x18n/node": "0.0.0",
+    "@x18n/ui": "0.0.0",
+    "cac": "^7.1.0",
+    "devframe": "^1.2.5",
+    "yaml": "^2.9.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/skills/x18n/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: x18n
+description: Maintain the i18n files of a project with the x18n CLI - find missing, unused and broken keys, add and rename keys, translate missing messages, and extract hard-coded strings. Use when the task touches locale files (JSON, YAML, Vue i18n blocks) or translation keys in code, instead of editing locale files by hand.
+---
+
+# x18n
+
+x18n reads the project's i18n setup (locale files, translate calls in code) and changes it safely. Use the `x18n` CLI instead of editing locale files directly: it keeps formatting, key style, file choice and placeholders correct, and every command has stable JSON output.
+
+## Rules
+
+- Do not edit locale files by hand. Use `x18n set`, `x18n apply`, `x18n rename` and `x18n delete`.
+- Before using a key in code, check whether it exists: `x18n get <key> --json`.
+- Never drop or rename placeholders (`{name}`, `{{count}}`, `%s`, `@:key`).
+- Pass `--json` and read the envelope `{ "x18n": 1, "command", "data", "diagnostics", "errors" }`. Never parse the human output.
+- Prefer `--dry-run` first for renames and deletes, and read the plan.
+
+## Exit codes
+
+- `0` success
+- `1` `x18n check` found errors, or `x18n apply` rejected values
+- `2` usage or config error
+- `3` a decision is needed: re-run with `--yes` to accept the defaults
+- `4` files changed during the command: run it again
+
+## Loops
+
+### Check the project
+
+```sh
+x18n check --json
+x18n status --json
+```
+
+### Add a key while coding
+
+```sh
+x18n get settings.title --json
+x18n set settings.title --value "Settings" --json
+x18n keys --missing de --json --limit 50
+```
+
+`x18n set` without `--locale` writes the source locale. Then use the key in code, for example `t('settings.title')`.
+
+### Translate missing messages
+
+```sh
+x18n prompt translate --to de --limit 50
+```
+
+Follow the prompt: write `{ "de": { "<key>": "<translation>" } }` to a file, then:
+
+```sh
+x18n apply translations.json --json
+x18n check --only placeholder-mismatch,invalid-syntax --locale de --json
+```
+
+`x18n apply` refuses values whose placeholders differ from the source and lists them in `data.rejected`; fix them and apply again. When the prompt reports more keys, continue with `x18n prompt translate --to de --cursor <nextCursor>`.
+
+### Review translations
+
+```sh
+x18n prompt review --locale de --limit 50
+```
+
+Fix wrong values with `x18n set <key> --locale de --value <text> --json` and list what you changed.
+
+### Clean up
+
+```sh
+x18n keys --unused --json
+x18n delete old.key --dry-run --json
+x18n delete old.key --json
+```
+
+### Rename keys
+
+```sh
+x18n rename home.title home.heading --dry-run --json
+x18n rename home.title home.heading --json
+x18n rename pages screens --json
+```
+
+A rename updates every locale and every usage in code. Renaming a parent (`pages`) moves every key under it. A rename to an existing key is refused (exit code 1).
+
+### Extract hard-coded strings
+
+```sh
+x18n extract --list --json
+x18n extract --plan extract-plan.json
+x18n extract --apply extract-plan.json --json
+```
+
+Edit the keys in the plan file before applying it.
+
+## Paging
+
+List commands take `--limit` and return `nextCursor`; pass it as `--cursor` to get the next page:
+
+```sh
+x18n keys --json --limit 100 --cursor 100
+```
+
+## Monorepos
+
+When `x18n status --json` lists several projects, pass `--project <name>` to write commands.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.