react-autolocale 0.2.0 → 0.3.0-beta.1

package/dist/cli.js

@@ -1,7 +1,467 @@
 #!/usr/bin/env node
-import { n as exportTranslations, t as OVERRIDES_FILE } from "./overrides-ZQ6meLck.js";
-import fs from "node:fs";
+import { F as toTranslator, I as getLanguage, M as TranslationError, N as createLocalTranslator, P as ollama, S as scanProject, a as findSite, b as manifestFile, c as hasRootSrc, d as OVERRIDES_FILE, f as exportTranslations, g as importLegacyCache, h as catalogFile, i as defaultInclude, j as writeJson, k as ensureBanner, l as resolveOutput, m as readOverrides, n as loadConfigFile, o as META_DIR, r as loadProject, s as defaultOutput, t as findConfigFile, u as toProjectPath, v as removeFromCatalogs, x as readManifest, y as translateMissing } from "./project-BazDFtnp.js";
+import { n as DEFAULT_MODELS, t as DEFAULT_KEY_ENV } from "./config-U-SpTtCW.js";
 import path from "node:path";
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import readline from "node:readline/promises";
+//#region src/core/env.ts
+/** Parses KEY=value lines (optional quotes, # comments, `export ` prefix). */
+function parseEnv(text) {
+	const out = {};
+	for (const raw of text.split(/\r?\n/)) {
+		const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(raw);
+		if (!m) continue;
+		let value = m[2];
+		const quoted = /^(['"])(.*)\1$/.exec(value);
+		value = quoted ? quoted[2] : value.replace(/\s+#.*$/, "");
+		out[m[1]] = value;
+	}
+	return out;
+}
+/** Loads .env.local and .env into process.env for the CLI. Variables already set always win. */
+function loadEnv(root) {
+	for (const name of [".env.local", ".env"]) {
+		const file = path.join(root, name);
+		if (!fs.existsSync(file)) continue;
+		for (const [key, value] of Object.entries(parseEnv(fs.readFileSync(file, "utf8")))) if (process.env[key] === void 0) process.env[key] = value;
+	}
+}
+//#endregion
+//#region src/core/providers.ts
+/**
+* Builds the configured engine. Called only by the `translate`/`generate`/`sync` commands; the Vite plugin never
+* loads this module. Throws a fatal TranslationError (before any request) when a key or package is missing.
+*/
+async function createProvider(project, log) {
+	const p = project.config.provider ?? { name: "local" };
+	if (typeof p === "function" || "translate" in p) return {
+		translator: toTranslator(p),
+		name: "custom",
+		chunkSize: 40
+	};
+	switch (p.name) {
+		case "local": return {
+			translator: createLocalTranslator(log),
+			name: "local",
+			chunkSize: 40
+		};
+		case "ollama": return {
+			translator: ollama({
+				model: p.model,
+				url: p.url
+			}),
+			name: `ollama:${p.model}`,
+			chunkSize: 20
+		};
+		case "openai": return {
+			translator: await openaiTranslator(project.root, p),
+			name: `openai:${p.model ?? DEFAULT_MODELS.openai}`,
+			chunkSize: 100
+		};
+		case "anthropic": return {
+			translator: await anthropicTranslator(project.root, p),
+			name: `anthropic:${p.model ?? DEFAULT_MODELS.anthropic}`,
+			chunkSize: 100
+		};
+		case "gemini": return {
+			translator: geminiTranslator(p),
+			name: `gemini:${p.model ?? DEFAULT_MODELS.gemini}`,
+			chunkSize: 100
+		};
+	}
+}
+function apiKey(provider, envName) {
+	const name = envName ?? DEFAULT_KEY_ENV[provider];
+	const key = process.env[name];
+	if (!key) throw new TranslationError(`${name} is not set. Add it to your environment or to .env in the project root (${name}=...), or run \`npx react-autolocale init\` again. No request was made.`, true);
+	return key;
+}
+/** Loads a provider SDK from the user's project first (that's where they install it), then from ours. */
+async function importFromProject(root, pkg) {
+	try {
+		const entry = createRequire(path.join(root, "package.json")).resolve(pkg);
+		return await import(pathToFileURL(entry).href);
+	} catch {}
+	try {
+		return await import(pkg);
+	} catch {
+		throw new TranslationError(`This provider needs the "${pkg}" package in your project: npm install -D ${pkg}`, true);
+	}
+}
+const BATCH = 25;
+const CONCURRENCY = 3;
+const TRANSLATIONS_SCHEMA = {
+	type: "object",
+	properties: { translations: {
+		type: "array",
+		items: { type: "string" }
+	} },
+	required: ["translations"],
+	additionalProperties: false
+};
+function systemPrompt(from, to) {
+	const name = (code) => `${getLanguage(code)?.english ?? code} (${code})`;
+	return [
+		`You translate user-interface text for a website from ${name(from)} to ${name(to)}.`,
+		`The user sends JSON {"items": [{"text", "element"?}]}; "element" is the HTML element or attribute the text appears in.`,
+		`Reply with {"translations": [...]}: exactly one translation per item, in the same order.`,
+		`Keep tokens such as X0X, X1X and {name} exactly as written. Keep labels as short as the original.`,
+		`Translate only; add no notes, quotes or explanations.`
+	].join("\n");
+}
+function userPrompt(texts, contexts) {
+	return JSON.stringify({ items: texts.map((text, i) => contexts[i] ? {
+		text,
+		element: contexts[i]
+	} : { text }) });
+}
+/** Parses {"translations": [...]} and checks there is one string per input. */
+function parseTranslations(raw, expected) {
+	try {
+		const out = JSON.parse(raw).translations;
+		return Array.isArray(out) && out.length === expected && out.every((t) => typeof t === "string") ? out : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Splits work into batches, runs a few at a time, and retries a batch one string at a time if the model
+* returns the wrong number of items. Provider SDKs handle timeouts and retries of transient HTTP errors.
+*/
+function batchedTranslator(call) {
+	const one = async (texts, contexts, from, to) => {
+		const parsed = parseTranslations(await call(texts, contexts, from, to), texts.length);
+		if (parsed) return parsed;
+		if (texts.length === 1) return [""];
+		const out = [];
+		for (let i = 0; i < texts.length; i++) out.push(...await one([texts[i]], [contexts[i] ?? ""], from, to));
+		return out;
+	};
+	return { async translate(texts, from, to, contexts = []) {
+		const batches = [];
+		for (let i = 0; i < texts.length; i += BATCH) batches.push(i);
+		const results = new Array(batches.length);
+		let next = 0;
+		const worker = async () => {
+			while (next < batches.length) {
+				const b = next++;
+				const start = batches[b];
+				results[b] = await one(texts.slice(start, start + BATCH), contexts.slice(start, start + BATCH), from, to);
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(CONCURRENCY, batches.length) }, worker));
+		return results.flat();
+	} };
+}
+/** Turns SDK errors into TranslationErrors; credential, permission and request errors stop the run. */
+function classify(err, sdk, label) {
+	const msg = err.message;
+	if (err instanceof sdk.AuthenticationError) throw new TranslationError(`${label}: the API key was rejected (${msg}).`, true);
+	if (err instanceof sdk.PermissionDeniedError) throw new TranslationError(`${label}: permission denied (${msg}).`, true);
+	if (err instanceof sdk.NotFoundError) throw new TranslationError(`${label}: not found; check the model name (${msg}).`, true);
+	if (err instanceof sdk.BadRequestError) throw new TranslationError(`${label}: request rejected (${msg}).`, true);
+	if (err instanceof sdk.RateLimitError) throw new TranslationError(`${label}: rate limit or quota reached after retries (${msg}). Run the command again later.`, true);
+	if (err instanceof sdk.APIError || err instanceof sdk.APIConnectionError) throw new TranslationError(`${label}: ${msg}`);
+	throw err;
+}
+async function openaiTranslator(root, p) {
+	const key = apiKey("openai", p.apiKeyEnv);
+	const OpenAI = (await importFromProject(root, "openai")).default;
+	const client = new OpenAI({
+		apiKey: key,
+		baseURL: p.baseURL,
+		timeout: 12e4,
+		maxRetries: 3
+	});
+	const model = p.model ?? DEFAULT_MODELS.openai;
+	return batchedTranslator(async (texts, contexts, from, to) => {
+		try {
+			return (await client.responses.create({
+				model,
+				instructions: systemPrompt(from, to),
+				input: userPrompt(texts, contexts),
+				text: { format: {
+					type: "json_schema",
+					name: "translations",
+					strict: true,
+					schema: { ...TRANSLATIONS_SCHEMA }
+				} }
+			})).output_text;
+		} catch (err) {
+			classify(err, OpenAI, "OpenAI");
+		}
+	});
+}
+/** Models that accept server-side refusal fallbacks (`fallbacks: "default"`). */
+const FALLBACK_MODELS = /* @__PURE__ */ new Set([
+	"claude-fable-5-1",
+	"claude-opus-5-5",
+	"claude-opus-5",
+	"claude-sonnet-5-5"
+]);
+async function anthropicTranslator(root, p) {
+	const key = apiKey("anthropic", p.apiKeyEnv);
+	const Anthropic = (await importFromProject(root, "@anthropic-ai/sdk")).default;
+	const client = new Anthropic({
+		apiKey: key,
+		timeout: 12e4,
+		maxRetries: 3
+	});
+	const model = p.model ?? DEFAULT_MODELS.anthropic;
+	const fallback = FALLBACK_MODELS.has(model);
+	return batchedTranslator(async (texts, contexts, from, to) => {
+		try {
+			const res = await client.beta.messages.create({
+				model,
+				max_tokens: 16e3,
+				...fallback ? {
+					betas: ["server-side-fallback-2026-07-01"],
+					fallbacks: "default"
+				} : {},
+				system: systemPrompt(from, to),
+				messages: [{
+					role: "user",
+					content: userPrompt(texts, contexts)
+				}],
+				output_config: {
+					effort: p.effort ?? "low",
+					format: {
+						type: "json_schema",
+						schema: { ...TRANSLATIONS_SCHEMA }
+					}
+				}
+			});
+			if (res.stop_reason === "refusal") throw new TranslationError("Claude declined to translate this batch.");
+			if (res.stop_reason === "max_tokens") return "";
+			return res.content.map((b) => b.type === "text" ? b.text : "").join("");
+		} catch (err) {
+			if (err instanceof TranslationError) throw err;
+			classify(err, Anthropic, "Anthropic");
+		}
+	});
+}
+/** Gemini's schema dialect (types in capitals) for {"translations": [string, ...]}. */
+const GEMINI_SCHEMA = {
+	type: "OBJECT",
+	properties: { translations: {
+		type: "ARRAY",
+		items: { type: "STRING" }
+	} },
+	required: ["translations"]
+};
+const GEMINI_RETRYABLE = /* @__PURE__ */ new Set([
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+const GEMINI_RETRIES = 3;
+/** The model stopped because of its safety rules, not because it finished. */
+const GEMINI_DECLINED = /* @__PURE__ */ new Set([
+	"SAFETY",
+	"BLOCKLIST",
+	"PROHIBITED_CONTENT",
+	"SPII",
+	"IMAGE_SAFETY",
+	"RECITATION"
+]);
+/** Maps an HTTP failure to a TranslationError. Credential, permission and request errors stop the run. */
+function geminiError(status, data) {
+	const msg = String(data?.error?.message ?? `HTTP ${status}`).replace(/[.\s]+$/, "");
+	if (status === 401 || status === 403 || /API key not valid|API_KEY_INVALID/i.test(msg)) return new TranslationError(`Gemini: the API key was rejected or lacks permission (${msg})`, true);
+	if (status === 404) return new TranslationError(`Gemini: model not found; check the model name (${msg})`, true);
+	if (status === 400) return new TranslationError(`Gemini: request rejected (${msg})`, true);
+	if (status === 429) return new TranslationError(`Gemini: rate limit or quota reached after retries (${msg}). Run the command again later`, true);
+	return new TranslationError(`Gemini: ${msg}`);
+}
+function geminiTranslator(p, deps = {}) {
+	const key = apiKey("gemini", p.apiKeyEnv);
+	const model = p.model ?? DEFAULT_MODELS.gemini;
+	const url = `${(p.baseURL ?? "https://generativelanguage.googleapis.com/v1beta").replace(/\/+$/, "")}/models/${encodeURIComponent(model)}:generateContent`;
+	const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+	const backoff = (attempt) => Math.min(3e4, 1e3 * 2 ** attempt + Math.random() * 500);
+	return batchedTranslator(async (texts, contexts, from, to) => {
+		const body = JSON.stringify({
+			systemInstruction: { parts: [{ text: systemPrompt(from, to) }] },
+			contents: [{
+				role: "user",
+				parts: [{ text: userPrompt(texts, contexts) }]
+			}],
+			generationConfig: {
+				temperature: 0,
+				responseMimeType: "application/json",
+				responseSchema: GEMINI_SCHEMA
+			}
+		});
+		for (let attempt = 0;; attempt++) {
+			let res;
+			try {
+				res = await fetch(url, {
+					method: "POST",
+					headers: {
+						"content-type": "application/json",
+						"x-goog-api-key": key
+					},
+					body,
+					signal: AbortSignal.timeout(12e4)
+				});
+			} catch (err) {
+				if (attempt >= GEMINI_RETRIES) throw new TranslationError(`Gemini: could not reach the API (${err.message})`);
+				await sleep(backoff(attempt));
+				continue;
+			}
+			if (GEMINI_RETRYABLE.has(res.status) && attempt < GEMINI_RETRIES) {
+				const wait = Number(res.headers.get("retry-after"));
+				await sleep(Number.isFinite(wait) && wait > 0 ? Math.min(wait, 60) * 1e3 : backoff(attempt));
+				continue;
+			}
+			const data = await res.json().catch(() => ({}));
+			if (!res.ok) throw geminiError(res.status, data);
+			if (data.promptFeedback?.blockReason) throw new TranslationError(`Gemini declined to translate this batch (${data.promptFeedback.blockReason})`);
+			const candidate = data.candidates?.[0];
+			if (!candidate || candidate.finishReason === "MAX_TOKENS") return "";
+			if (GEMINI_DECLINED.has(candidate.finishReason)) throw new TranslationError(`Gemini declined to translate this batch (${candidate.finishReason})`);
+			return (candidate.content?.parts ?? []).map((part) => part.text ?? "").join("");
+		}
+	});
+}
+//#endregion
+//#region src/cli/commands.ts
+const ok = (out, msg) => out.log(`✓ ${msg}`);
+const note = (out, msg) => out.log(`! ${msg}`);
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+/** `scan`: extract strings and update the manifest + source catalog. No translation, no network. */
+function runScan(project, out) {
+	const report = scanProject(project);
+	ok(out, `Scanned ${plural(report.fileCount, "source file")}`);
+	ok(out, `Found ${plural(report.added.length, "new string")} (${report.active.length} in use)`);
+	if (report.removed.length) note(out, `${plural(report.removed.length, "string")} no longer in the source; translations kept (remove them with \`npx react-autolocale clean\`).`);
+	if (report.previousSource) note(out, `The source language changed from ${report.previousSource} to ${project.site.original}. Existing translations were made from ${report.previousSource}.`);
+	if (report.previousOutput) migrateOutput(project, report.previousOutput, out);
+	return report;
+}
+/**
+* The catalogs moved (a new `output`, or the default changed). Old files are never moved or deleted: target
+* catalogs missing at the new location are copied over, and the old folder is left for the developer to remove.
+*/
+function migrateOutput(project, previous, out) {
+	const oldDir = path.resolve(project.root, previous);
+	if (!fs.existsSync(oldDir) || oldDir === project.output) return;
+	const copied = [];
+	for (const lang of project.site.languages) {
+		const from = path.join(oldDir, `${lang}.json`);
+		const to = catalogFile(project, lang);
+		if (fs.existsSync(from) && !fs.existsSync(to)) fs.copyFileSync(from, to), copied.push(lang);
+	}
+	note(out, `Catalogs were previously in ${previous}/ and are now written to ${project.outputRel}/.` + (copied.length ? ` Copied ${copied.join(", ")} catalogs to the new folder.` : "") + ` The old folder was left untouched: check the new one, then delete ${previous}/ yourself (or set output: "${previous}" in auto-locale.config.ts to keep using it).`);
+}
+/** `translate`: fill missing catalog entries with the configured provider. */
+async function runTranslate(project, flags, out) {
+	const manifest = fs.existsSync(manifestFile(project)) ? readManifest(project) : null;
+	if (!manifest) throw new Error("No manifest yet. Run `npx react-autolocale generate` (or `scan` first).");
+	const langs = flags.langs ?? project.site.languages;
+	const unknown = langs.filter((l) => !project.site.languages.includes(l));
+	if (unknown.length) throw new Error(`--lang ${unknown.join(",")} is not a target language (targets: ${project.site.languages.join(", ")}).`);
+	const imported = importLegacyCache(project);
+	if (imported) ok(out, `Imported ${plural(imported, "translation")} made by an older version (node_modules/.cache/react-autolocale, left in place)`);
+	loadEnv(project.root);
+	let provider;
+	try {
+		provider = await createProvider(project, out.log);
+	} catch (err) {
+		if (err instanceof TranslationError) throw new Error(err.message);
+		throw err;
+	}
+	if (provider.name === "local") out.log("Using the local models (CPU). Downloaded once into ~/.cache/react-autolocale and reused by every project: about 110 MB per English->X language (OPUS-MT), 870 MB for other pairs (NLLB-200), plus a 470 MB engine if your project has no @huggingface/transformers.");
+	else out.log(`Using ${provider.name}.`);
+	let interrupted = false;
+	const onSigint = () => {
+		interrupted = true;
+		out.log("\nStopping after the current batch (press Ctrl+C again to quit now)...");
+		process.once("SIGINT", () => process.exit(130));
+	};
+	process.once("SIGINT", onSigint);
+	let report;
+	try {
+		report = await translateMissing(project, manifest, {
+			translator: provider.translator,
+			providerName: provider.name,
+			overrides: readOverrides(project.root),
+			langs,
+			chunkSize: provider.chunkSize,
+			shouldStop: () => interrupted,
+			log: (m) => out.log(`  ${m}`)
+		});
+	} finally {
+		process.removeListener("SIGINT", onSigint);
+	}
+	if (!report.stopped) try {
+		await ensureBanner({
+			output: project.output,
+			langs: [project.site.original, ...project.site.languages],
+			getTranslator: () => provider.translator
+		});
+	} catch (err) {
+		note(out, `Language-suggestion banner not translated (${err.message}); it shows in English.`);
+	}
+	printTranslateReport(project, report, out);
+	return report;
+}
+function printTranslateReport(project, report, out) {
+	const langs = Object.entries(report.langs);
+	const sum = (k) => langs.reduce((n, [, r]) => n + r[k], 0);
+	const failedTotal = langs.reduce((n, [, r]) => n + r.failed.length, 0);
+	ok(out, `Kept ${plural(sum("kept"), "existing translation")}${sum("reused") ? `, reused ${sum("reused")} from the cache/glossary` : ""}`);
+	if (sum("overridden")) ok(out, `${plural(sum("overridden"), "string")} handled by react-autolocale.overrides.json`);
+	ok(out, `Translated ${plural(sum("translated"), "string")}${sum("translated") ? ` (${langs.map(([l, r]) => `${l} ${r.translated}`).join(", ")})` : ""}`);
+	ok(out, `Updated ${plural(langs.length, "locale catalog")} in ${project.outputRel}/`);
+	for (const [lang, r] of langs) {
+		if (!r.failed.length) continue;
+		out.log(`✗ ${lang}: ${plural(r.failed.length, "string")} failed (shown in ${project.site.original} until fixed)`);
+		for (const f of r.failed.slice(0, 5)) out.log(`    ${f.id} "${f.text.slice(0, 60)}": ${f.reason}`);
+		if (r.failed.length > 5) out.log(`    ...and ${r.failed.length - 5} more`);
+	}
+	if (report.stopped) out.log(`✗ Stopped: ${report.stopped}. Everything finished so far was saved.`);
+	if (failedTotal || report.stopped) out.log("Retry the remaining strings with: npx react-autolocale translate");
+}
+/** `generate` / `sync`: scan, then translate what is missing. Both are incremental. */
+async function runGenerate(project, flags, out) {
+	out.log("React Auto Locale\n");
+	const scan = runScan(project, out);
+	const translate = await runTranslate(project, flags, out);
+	out.log("\nNo source files modified.");
+	return {
+		scan,
+		translate
+	};
+}
+/** `clean`: list messages no longer in the source and, once confirmed, remove them from the catalogs. */
+async function runClean(project, flags, prompt, out) {
+	const { manifest } = scanProject(project);
+	const unused = Object.entries(manifest.messages).filter(([, m]) => m.status === "unused");
+	if (!unused.length) {
+		ok(out, "Nothing to clean: every catalog entry is still used.");
+		return 0;
+	}
+	out.log(`${plural(unused.length, "string")} no longer appear in the source:`);
+	for (const [id, m] of unused.slice(0, 20)) out.log(`  ${id} "${m.text.slice(0, 70)}"`);
+	if (unused.length > 20) out.log(`  ...and ${unused.length - 20} more`);
+	if (!(flags.yes || await prompt.confirm("Remove them and their translations from every catalog?", false))) {
+		out.log(prompt.interactive ? "Nothing removed." : "Nothing removed. Run `npx react-autolocale clean --yes` to remove them.");
+		return 0;
+	}
+	const ids = unused.map(([id]) => id);
+	const removed = removeFromCatalogs(project, ids);
+	for (const id of ids) delete manifest.messages[id];
+	writeJson(manifestFile(project), manifest);
+	ok(out, `Removed ${plural(ids.length, "string")} (${plural(removed, "catalog entry")}).`);
+	return ids.length;
+}
+//#endregion
 //#region src/cli/viteConfig.ts
 const IMPORT_LINE = `import reactAutolocale from "react-autolocale/vite";`;
 /** Adds the react-autolocale plugin to a vite.config source string. Returns null if it can't be done safely. */
@@ -27,19 +487,351 @@ function patchViteConfig(source) {
 	};
 }
 //#endregion
+//#region src/cli/init.ts
+const VITE_CONFIGS = [
+	"vite.config.ts",
+	"vite.config.mts",
+	"vite.config.js",
+	"vite.config.mjs"
+];
+const SDK = {
+	openai: "openai",
+	anthropic: "@anthropic-ai/sdk"
+};
+function detect(root) {
+	let deps = {};
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+		deps = {
+			...pkg.dependencies,
+			...pkg.devDependencies
+		};
+	} catch {}
+	const lock = (f) => fs.existsSync(path.join(root, f));
+	const output = resolveOutput(root);
+	let autoScale = null;
+	let wrapped = false;
+	try {
+		const site = findSite(root, defaultInclude(root), { required: false });
+		wrapped = !!site;
+		if (site?.original) autoScale = {
+			original: site.original,
+			languages: site.languages
+		};
+	} catch {}
+	return {
+		react: "react" in deps,
+		viteConfig: VITE_CONFIGS.find((f) => fs.existsSync(path.join(root, f))),
+		typescript: fs.existsSync(path.join(root, "tsconfig.json")),
+		packageManager: lock("pnpm-lock.yaml") ? "pnpm" : lock("yarn.lock") ? "yarn" : lock("bun.lockb") || lock("bun.lock") ? "bun" : "npm",
+		configFile: findConfigFile(root),
+		hasSrc: hasRootSrc(root),
+		existingCatalogs: fs.existsSync(output) ? fs.readdirSync(output).filter((f) => f.endsWith(".json")) : [],
+		autoScale,
+		wrapped
+	};
+}
+const langName = (code) => getLanguage(code)?.english ?? code;
+function parseLocales(input) {
+	const codes = [...new Set(input.split(/[\s,]+/).map((c) => c.trim().toLowerCase()).filter(Boolean))];
+	return {
+		ok: codes.filter((c) => getLanguage(c)),
+		bad: codes.filter((c) => !getLanguage(c))
+	};
+}
+/** Writes auto-locale.config.ts. `output` is written only when it differs from the automatic default. */
+function configSource(cfg, root) {
+	const lines = [`  sourceLocale: ${JSON.stringify(cfg.sourceLocale)},`, `  locales: ${JSON.stringify(cfg.locales)},`];
+	const p = cfg.provider;
+	const fields = Object.entries(p).map(([k, v]) => `${k}: ${JSON.stringify(v)}`);
+	lines.push(`  provider: { ${fields.join(", ")} },`);
+	const auto = defaultOutput(root);
+	if (cfg.output && path.resolve(root, cfg.output) !== path.resolve(root, auto)) lines.push(`  output: ${JSON.stringify(cfg.output)},`);
+	else lines.push(`  // Catalogs are written to ${auto}/ by default. To choose another folder:`, `  // output: "./${auto}",`);
+	return `import { defineConfig } from "react-autolocale/config";\n\nexport default defineConfig({\n${lines.join("\n")}\n});\n`;
+}
+/** Adds lines to .gitignore that are not already there; never rewrites what exists. */
+function ensureGitignore(root, entries) {
+	const file = path.join(root, ".gitignore");
+	const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+	const have = new Set(current.split(/\r?\n/).map((l) => l.trim()));
+	const add = entries.filter((e) => !have.has(e) && !have.has("/" + e));
+	if (add.length) fs.writeFileSync(file, current + (current && !current.endsWith("\n") ? "\n" : "") + add.join("\n") + "\n");
+	return add;
+}
+/** Appends KEY=value to .env unless KEY is already defined there. The value is never printed. */
+function saveKeyToEnv(root, name, value) {
+	const file = path.join(root, ".env");
+	const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+	if (name in parseEnv(current)) return false;
+	fs.writeFileSync(file, current + (current && !current.endsWith("\n") ? "\n" : "") + `${name}=${value}\n`, { mode: 384 });
+	return true;
+}
+function keyIsAvailable(root, name) {
+	if (process.env[name]) return true;
+	return [".env.local", ".env"].some((f) => {
+		const file = path.join(root, f);
+		return fs.existsSync(file) && !!parseEnv(fs.readFileSync(file, "utf8"))[name];
+	});
+}
+function sdkInstalled(root, pkg) {
+	try {
+		createRequire(path.join(root, "package.json")).resolve(pkg);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function runInit(root, flags, prompt, out) {
+	const d = detect(root);
+	const stack = [d.react ? "React" : null, d.viteConfig ? "Vite" : null].filter(Boolean).join(" + ") || "unknown (React + Vite expected)";
+	out.log("React Auto Locale setup\n");
+	out.log(`Detected project: ${stack}${d.typescript ? " (TypeScript)" : ""}, ${d.packageManager}`);
+	out.log(`Source directory: ${d.hasSrc ? "src/" : "not found"}`);
+	if (d.existingCatalogs.length) out.log(`Existing catalogs: ${toProjectPath(root, resolveOutput(root))}/ (${d.existingCatalogs.join(", ")})`);
+	let configFile = d.configFile;
+	let config;
+	if (configFile) {
+		const existing = await loadConfigFile(configFile, root);
+		const p = existing.provider;
+		const providerName = !p ? "local" : typeof p === "function" || "translate" in p ? "custom" : p.name;
+		out.log(`\n${path.basename(configFile)} already exists: source ${existing.sourceLocale ?? "?"}, locales ${(existing.locales ?? []).join(", ")}, provider ${providerName}.`);
+		if (!(flags.force || await prompt.confirm("Reconfigure it?", false))) {
+			out.log("Keeping it as is.");
+			config = existing;
+		}
+	}
+	if (!config) {
+		let source = (flags.source ?? await prompt.ask("\nSource language (the language your code is written in)", d.autoScale?.original ?? "en")).toLowerCase();
+		while (!getLanguage(source)) {
+			if (!prompt.interactive) throw new Error(`Unsupported source language "${source}".`);
+			source = (await prompt.ask(`"${source}" is not a supported code. Source language`, "en")).toLowerCase();
+		}
+		let targets = (flags.locales ?? []).filter((l) => l !== source);
+		if (!flags.locales) {
+			const suggested = d.autoScale?.languages.join(",") ?? "";
+			for (;;) {
+				const { ok, bad } = parseLocales(await prompt.ask("Target languages, comma-separated (e.g. fr,es,de)", suggested));
+				if (bad.length) out.log(`Unsupported: ${bad.join(", ")}.`);
+				targets = ok.filter((l) => l !== source);
+				if (targets.length && !bad.length) break;
+				if (!prompt.interactive) throw new Error("Pass target languages with --locales fr,es (no <AutoScale languages> found to reuse).");
+			}
+		} else {
+			const bad = flags.locales.filter((l) => !getLanguage(l));
+			if (bad.length) throw new Error(`Unsupported language code${bad.length > 1 ? "s" : ""}: ${bad.join(", ")}.`);
+		}
+		const name = flags.provider ?? await prompt.choose("How would you like to translate your application?", [
+			{
+				value: "local",
+				label: "Local model (OPUS-MT / NLLB-200)",
+				help: "Free and runs on your machine; no API key. Models are large (about 110 MB per English->X language, 870 MB for\nother pairs) and translating on the CPU uses RAM and time, so big apps or many languages can be slow.\nModels are cached in ~/.cache/react-autolocale and downloaded only when you run `translate` or `generate`,\nnever during init or builds."
+			},
+			{
+				value: "openai",
+				label: "Cloud AI: OpenAI",
+				help: "Uses a hosted AI model. No large downloads, and usually faster for big translation jobs. Needs an API key;\nprovider usage may be billed to your account."
+			},
+			{
+				value: "anthropic",
+				label: "Cloud AI: Anthropic Claude",
+				help: "Uses a hosted AI model. No large downloads, and usually faster for big translation jobs. Needs an API key;\nprovider usage may be billed to your account."
+			},
+			{
+				value: "gemini",
+				label: "Cloud AI: Google Gemini",
+				help: "Uses a hosted AI model. No large downloads, and usually faster for big translation jobs. Needs an API key;\nprovider usage may be billed to your account."
+			}
+		], "local");
+		let provider;
+		if (name === "openai" || name === "anthropic" || name === "gemini") provider = {
+			name,
+			model: flags.model ?? DEFAULT_MODELS[name],
+			apiKeyEnv: flags.apiKeyEnv ?? DEFAULT_KEY_ENV[name]
+		};
+		else if (name === "ollama") {
+			if (!flags.model) throw new Error("Ollama needs a model: --provider ollama --model llama3.1");
+			provider = {
+				name,
+				model: flags.model
+			};
+		} else if (name === "local") provider = { name };
+		else throw new Error(`Unknown provider "${name}". Choose local, openai, anthropic, gemini or ollama.`);
+		const auto = defaultOutput(root);
+		out.log(`\nGenerated output:\n  ${auto}/\nInternal metadata:\n  ${META_DIR}/`);
+		let output = flags.output ?? await prompt.ask("Catalog folder (press Enter to keep)", auto);
+		output = output.replace(/\/+$/, "");
+		config = {
+			sourceLocale: source,
+			locales: [source, ...targets],
+			provider,
+			...output !== auto ? { output } : {}
+		};
+		configFile = path.join(root, "auto-locale.config.ts");
+		fs.writeFileSync(configFile, configSource(config, root));
+		out.log(`\nWrote ${path.basename(configFile)}.`);
+	}
+	const provider = config.provider;
+	const ignore = [`${META_DIR}/cache.json`];
+	let modelNote = "";
+	if (provider && typeof provider === "object" && "name" in provider && (provider.name === "openai" || provider.name === "anthropic" || provider.name === "gemini")) {
+		const keyEnv = provider.apiKeyEnv ?? DEFAULT_KEY_ENV[provider.name];
+		ignore.push(".env", ".env.local");
+		if (keyIsAvailable(root, keyEnv)) out.log(`${keyEnv} is already set (value hidden).`);
+		else {
+			const key = await prompt.secret(`Paste your ${{
+				openai: "OpenAI",
+				anthropic: "Anthropic",
+				gemini: "Google Gemini"
+			}[provider.name]} API key to save it in .env (leave empty to do it later)`);
+			if (key) {
+				saveKeyToEnv(root, keyEnv, key);
+				out.log(`Saved ${keyEnv} to .env (value hidden).`);
+			} else out.log(`Add ${keyEnv}=... to .env (or your environment) before running translate. No request is made without it.`);
+		}
+		const pkg = provider.name === "gemini" ? null : SDK[provider.name];
+		if (pkg && !sdkInstalled(root, pkg)) {
+			const cmd = {
+				npm: [
+					"install",
+					"-D",
+					pkg
+				],
+				pnpm: [
+					"add",
+					"-D",
+					pkg
+				],
+				yarn: [
+					"add",
+					"-D",
+					pkg
+				],
+				bun: [
+					"add",
+					"-d",
+					pkg
+				]
+			}[d.packageManager];
+			if (await prompt.confirm(`Install ${pkg} (used only by the CLI, never bundled) now with ${d.packageManager}?`, false)) {
+				if (spawnSync(d.packageManager, cmd, {
+					cwd: root,
+					stdio: "inherit",
+					shell: process.platform === "win32"
+				}).status !== 0) out.log(`Installing failed. Run it yourself: ${d.packageManager} ${cmd.join(" ")}`);
+			} else out.log(`Install the provider SDK before translating: ${d.packageManager} ${cmd.join(" ")}`);
+		}
+	} else if (!provider || typeof provider === "object" && "name" in provider && provider.name === "local") modelNote = "Local models are not downloaded yet; the first `generate` downloads them.";
+	const added = ensureGitignore(root, ignore);
+	if (added.length) out.log(`Added to .gitignore: ${added.join(", ")}`);
+	if (d.viteConfig) {
+		const file = path.join(root, d.viteConfig);
+		const patched = patchViteConfig(fs.readFileSync(file, "utf8"));
+		if (!patched) out.log(`Could not edit ${d.viteConfig} automatically. Add:\n  import reactAutolocale from "react-autolocale/vite";\n  plugins: [reactAutolocale(), ...]`);
+		else if (patched.changed) fs.writeFileSync(file, patched.code), out.log(`Added the react-autolocale plugin to ${d.viteConfig}.`);
+	} else out.log("No vite.config found. Add the plugin yourself: plugins: [reactAutolocale()] from \"react-autolocale/vite\".");
+	const p = config.provider;
+	const providerLabel = !p ? "Local model" : typeof p === "function" || "translate" in p ? "Custom" : {
+		local: "Local model",
+		openai: "OpenAI",
+		anthropic: "Anthropic Claude",
+		gemini: "Google Gemini",
+		ollama: "Ollama"
+	}[p.name];
+	const out_ = toProjectPath(root, resolveOutput(root, config.output));
+	out.log(`\nReact Auto Locale initialized.\n`);
+	out.log(`Source language: ${langName(config.sourceLocale ?? "")}`);
+	out.log(`Target languages: ${(config.locales ?? []).filter((l) => l !== config.sourceLocale).map(langName).join(", ")}`);
+	out.log(`Provider: ${providerLabel}`);
+	out.log(`Generated output:\n  ${out_}/`);
+	out.log(`Internal metadata:\n  ${META_DIR}/`);
+	out.log(`Configuration:\n  ${path.basename(configFile)}`);
+	if (modelNote) out.log(modelNote);
+	if (!d.wrapped) out.log(`\nWrap your app once (for example in main.tsx):\n  import { AutoScale } from "react-autolocale";\n  <AutoScale><App /></AutoScale>`);
+	out.log(`\nNext:\n  npx react-autolocale generate`);
+	return {
+		config,
+		configFile
+	};
+}
+//#endregion
+//#region src/cli/prompt.ts
+function createPrompter(interactive) {
+	const open = () => readline.createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	const ask = async (question, fallback = "") => {
+		if (!interactive) return fallback;
+		const rl = open();
+		try {
+			return (await rl.question(`${question}${fallback ? ` (${fallback})` : ""}: `)).trim() || fallback;
+		} finally {
+			rl.close();
+		}
+	};
+	return {
+		interactive,
+		ask,
+		async secret(question) {
+			if (!interactive) return "";
+			const rl = open();
+			process.stdout.write(`${question}: `);
+			rl._writeToOutput = () => {};
+			try {
+				return (await rl.question("")).trim();
+			} finally {
+				rl.close();
+				process.stdout.write("\n");
+			}
+		},
+		async confirm(question, fallback) {
+			const answer = (await ask(`${question} ${fallback ? "[Y/n]" : "[y/N]"}`, "")).toLowerCase();
+			return answer ? answer.startsWith("y") : fallback;
+		},
+		async choose(question, options, fallback) {
+			if (!interactive) return fallback;
+			console.log(`\n${question}\n`);
+			options.forEach((o, i) => {
+				console.log(`  ${i + 1}) ${o.label}`);
+				if (o.help) console.log(o.help.replace(/^/gm, "     ") + "\n");
+			});
+			const def = String(options.findIndex((o) => o.value === fallback) + 1);
+			for (;;) {
+				const answer = await ask("Choose a number", def);
+				const picked = options[Number(answer) - 1];
+				if (picked) return picked.value;
+				console.log(`Please enter a number from 1 to ${options.length}.`);
+			}
+		}
+	};
+}
+//#endregion
 //#region src/cli/index.ts
 const HELP = `react-autolocale
 
 Usage:
+  react-autolocale init [--source en] [--locales fr,es] [--provider local|openai|anthropic|gemini|ollama]
+                        [--model <id>] [--api-key-env <NAME>] [--output <dir>] [--yes] [--force]
+      Sets up auto-locale.config.ts, the translation provider and the Vite plugin. Downloads nothing.
+  react-autolocale generate [--lang fr,es]
+      Scans the source, then translates new strings and writes the catalogs. Incremental.
+  react-autolocale sync [--lang fr,es]
+      Same as generate: run it after changing text in your components.
+  react-autolocale scan
+      Extracts strings and updates .auto-locale/manifest.json. No translation, no network.
+  react-autolocale translate [--lang fr,es]
+      Translates strings missing from the catalogs (retries anything that failed before).
+  react-autolocale clean [--yes]
+      Lists strings no longer in the source and removes their translations once confirmed.
   react-autolocale export
-      Writes the generated translations to ${OVERRIDES_FILE} so you can edit them.
-      Anything in that file always wins over machine translation. Run a build first.
-  react-autolocale init
-      Adds the plugin to your vite.config for you.
-  react-autolocale add switcher [--dir src/components]
-      Copies an editable <LanguageSwitcher /> into your project.
-  react-autolocale add banner [--dir src/components]
-      Copies an editable <LanguageBanner /> (suggests the visitor's browser language) into your project.
+      Copies the generated translations to ${OVERRIDES_FILE} so you can edit them.
+      Anything in that file always wins over machine translation.
+  react-autolocale add switcher|banner [--dir src/components]
+      Copies an editable <LanguageSwitcher /> or <LanguageBanner /> into your project.
+
+Options:
+  --root <dir>   Project root (default: the nearest folder with a package.json).
 `;
 const TSX = `import { useLanguage } from "react-autolocale";
 
@@ -83,32 +875,6 @@ function flag(args, name) {
 	const i = args.indexOf(name);
 	return i >= 0 ? args[i + 1] : void 0;
 }
-const VITE_CONFIGS = [
-	"vite.config.ts",
-	"vite.config.mts",
-	"vite.config.js",
-	"vite.config.mjs"
-];
-const NEXT_STEP = `
-Next, wrap your app once (for example in main.tsx):
-
-  import { AutoScale } from "react-autolocale";
-
-  <AutoScale original="en" languages={["fr", "es"]}>
-    <App />
-  </AutoScale>
-
-Then run your build.`;
-function init(root) {
-	const file = VITE_CONFIGS.map((f) => path.join(root, f)).find((f) => fs.existsSync(f));
-	if (!file) throw new Error("No vite.config found. This package works with Vite projects.");
-	const name = path.basename(file);
-	const patched = patchViteConfig(fs.readFileSync(file, "utf8"));
-	if (!patched) throw new Error(`Could not edit ${name} automatically. Add this yourself:\n  import reactAutolocale from "react-autolocale/vite";\n  plugins: [reactAutolocale(), ...]`);
-	if (patched.changed) fs.writeFileSync(file, patched.code);
-	console.log(patched.changed ? `Added the react-autolocale plugin to ${name}.` : `${name} already uses react-autolocale.`);
-	console.log(NEXT_STEP);
-}
 function addComponent(root, args, name) {
 	const dir = path.resolve(root, flag(args, "--dir") ?? (fs.existsSync(path.join(root, "src")) ? "src/components" : "components"));
 	const ts = fs.existsSync(path.join(root, "tsconfig.json"));
@@ -118,21 +884,83 @@ function addComponent(root, args, name) {
 	fs.writeFileSync(file, name === "LanguageBanner" ? BANNER_TSX : ts ? TSX : JSX);
 	console.log(`Created ${path.relative(root, file)}\nImport it anywhere: import { ${name} } from "./components/${name}";`);
 }
-try {
-	const [cmd, what, ...rest] = process.argv.slice(2);
-	if (cmd === "init") init(process.cwd());
-	else if (cmd === "export") {
-		const { file, languages } = exportTranslations(process.cwd());
-		console.log(`Wrote ${path.relative(process.cwd(), file)}: ${Object.entries(languages).map(([l, n]) => `${l} ${n}`).join(", ")} strings.`);
-		console.log("Edit any value, commit the file, and rebuild. Your edits always win over machine translation.");
-	} else if (cmd === "add" && what === "switcher") addComponent(process.cwd(), rest, "LanguageSwitcher");
-	else if (cmd === "add" && what === "banner") addComponent(process.cwd(), rest, "LanguageBanner");
-	else {
-		console.log(HELP);
-		if (cmd) process.exitCode = 1;
-	}
-} catch (err) {
+/** --name value / --flag pairs. */
+function parseArgs(argv) {
+	const positional = [];
+	const flags = {};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (!a.startsWith("--")) positional.push(a);
+		else if (argv[i + 1] !== void 0 && !argv[i + 1].startsWith("--")) flags[a.slice(2)] = argv[++i];
+		else flags[a.slice(2)] = true;
+	}
+	return {
+		positional,
+		flags
+	};
+}
+/** The project the user means: --root, else the nearest folder (from cwd up) with a package.json. */
+function findRoot(explicit) {
+	if (explicit) return path.resolve(explicit);
+	for (let dir = process.cwd();; dir = path.dirname(dir)) {
+		if (fs.existsSync(path.join(dir, "package.json"))) return dir;
+		if (path.dirname(dir) === dir) return process.cwd();
+	}
+}
+const list = (v) => typeof v === "string" ? v.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+const str = (v) => typeof v === "string" ? v : void 0;
+async function main() {
+	const { positional, flags } = parseArgs(process.argv.slice(2));
+	const [cmd, what] = positional;
+	const root = findRoot(str(flags.root));
+	const out = { log: (m) => console.log(m) };
+	const interactive = !!process.stdin.isTTY && !flags.yes;
+	switch (cmd) {
+		case "init":
+			await runInit(root, {
+				source: str(flags.source),
+				locales: list(flags.locales),
+				provider: str(flags.provider),
+				model: str(flags.model),
+				apiKeyEnv: str(flags["api-key-env"]),
+				output: str(flags.output),
+				force: !!flags.force
+			}, createPrompter(interactive), out);
+			return;
+		case "scan":
+			out.log("React Auto Locale\n");
+			runScan(await loadProject(root, out), out);
+			out.log("\nNo source files modified.");
+			return;
+		case "translate": {
+			const report = await runTranslate(await loadProject(root, out), { langs: list(flags.lang) }, out);
+			if (report && (report.stopped || Object.values(report.langs).some((r) => r.failed.length))) process.exitCode = 1;
+			return;
+		}
+		case "generate":
+		case "sync": {
+			const { translate } = await runGenerate(await loadProject(root, out), { langs: list(flags.lang) }, out);
+			if (translate && (translate.stopped || Object.values(translate.langs).some((r) => r.failed.length))) process.exitCode = 1;
+			return;
+		}
+		case "clean":
+			await runClean(await loadProject(root, out), { yes: !!flags.yes }, createPrompter(!!process.stdin.isTTY && !flags.yes), out);
+			return;
+		case "export": {
+			const { file, languages } = exportTranslations(await loadProject(root, out));
+			out.log(`Wrote ${path.relative(root, file)}: ${Object.entries(languages).map(([l, n]) => `${l} ${n}`).join(", ")} strings.`);
+			out.log("Edit any value, commit the file, and rebuild. Your edits always win over machine translation.");
+			return;
+		}
+		case "add":
+			if (what === "switcher") return addComponent(root, process.argv.slice(2), "LanguageSwitcher");
+			if (what === "banner") return addComponent(root, process.argv.slice(2), "LanguageBanner");
+	}
+	console.log(HELP);
+	if (cmd && cmd !== "help" && cmd !== "--help") process.exitCode = 1;
+}
+main().catch((err) => {
 	console.error(`react-autolocale: ${err.message}`);
 	process.exit(1);
-}
+});
 //#endregion