@x18n/builtins 0.0.2 → 0.0.3

package/dist/checks.d.mts

@@ -0,0 +1,19 @@
+import { Check, Plugin } from "@x18n/core";
+//#region src/checks/index.d.ts
+export declare const missingKey: Check;
+export declare const missingTranslation: Check;
+export declare const emptyTranslation: Check;
+export declare const keyConflict: Check;
+export declare const localeCodeConflict: Check;
+export declare const unusedKey: Check;
+export declare const placeholderMismatch: Check;
+export declare const invalidSyntax: Check;
+export declare const dynamicKey: Check;
+export declare const identicalToSource: Check;
+export declare const keyStyle: Check;
+export declare const hardString: Check;
+export declare const glossary: Check;
+export declare const allChecks: readonly Check[];
+/** Every built-in check with its `recommended` severity. */
+export declare function recommended(): Plugin;
+//#endregion

package/dist/checks.mjs

@@ -0,0 +1,329 @@
+import { shouldExtract } from "./extractors.mjs";
+import { createPlaceholderComparer, localeSpellingKey } from "@x18n/core";
+//#region src/checks/index.ts
+function list(items) {
+	return items.join(", ");
+}
+const missingKey = {
+	id: "missing-key",
+	defaultSeverity: "error",
+	description: "A usage whose key is not defined in the source locale.",
+	*run(ctx) {
+		for (const usage of ctx.undefinedUsages()) yield {
+			key: usage.key,
+			locale: ctx.sourceLocale,
+			location: {
+				path: usage.path,
+				range: usage.range
+			},
+			message: `"${usage.key}" is not defined in ${ctx.sourceLocale}.`,
+			fixes: [{
+				title: `Add "${usage.key}" to ${ctx.sourceLocale}`,
+				ops: [{
+					type: "set",
+					key: usage.key,
+					locale: ctx.sourceLocale,
+					value: ""
+				}]
+			}]
+		};
+	}
+};
+const missingTranslation = {
+	id: "missing-translation",
+	defaultSeverity: "warning",
+	description: "A source-locale key that target locales lack. One diagnostic per key, at the source entry.",
+	*run(ctx) {
+		const missing = /* @__PURE__ */ new Map();
+		for (const coverage of ctx.coverage()) {
+			if (coverage.locale === ctx.sourceLocale) continue;
+			for (const key of coverage.missing) {
+				const locales = missing.get(key) ?? [];
+				missing.set(key, locales);
+				locales.push(coverage.locale);
+			}
+		}
+		for (const [key, locales] of missing) {
+			const source = ctx.message(key, ctx.sourceLocale);
+			yield {
+				key,
+				locale: ctx.sourceLocale,
+				message: `"${key}" is missing in ${list(locales)}.`,
+				fixes: [{
+					title: `Add empty values in ${list(locales)}`,
+					ops: locales.map((locale) => ({
+						type: "set",
+						key,
+						locale,
+						value: ""
+					}))
+				}, ...source ? [{
+					title: "Copy the source value",
+					ops: locales.map((locale) => ({
+						type: "set",
+						key,
+						locale,
+						value: source.value
+					}))
+				}] : []]
+			};
+		}
+	}
+};
+const emptyTranslation = {
+	id: "empty-translation",
+	defaultSeverity: "warning",
+	description: "A message with an empty string value.",
+	*run(ctx) {
+		for (const message of ctx.messages()) if (message.value === "") yield {
+			key: message.key,
+			locale: message.locale,
+			message: `"${message.key}" is empty in ${message.locale}.`
+		};
+	}
+};
+const keyConflict = {
+	id: "key-conflict",
+	defaultSeverity: "error",
+	description: "A key that is both a leaf and a parent, or is duplicated across files of one locale.",
+	*run(ctx) {
+		const keys = new Set(ctx.keys());
+		for (const key of keys) {
+			const segments = key.split(".");
+			for (let i = 1; i < segments.length; i++) {
+				const parent = segments.slice(0, i).join(".");
+				if (keys.has(parent)) yield {
+					key: parent,
+					message: `"${parent}" is a message and also the parent of "${key}".`
+				};
+			}
+			for (const locale of ctx.locales) {
+				const copies = ctx.duplicates(key, locale);
+				if (copies.length > 1) {
+					const files = [...new Set(copies.map((m) => ctx.resources.find((r) => r.id === m.resource)?.path ?? m.resource))];
+					yield {
+						key,
+						locale,
+						message: `"${key}" is defined ${copies.length} times in ${locale} (${list(files)}).`
+					};
+				}
+			}
+		}
+	}
+};
+const localeCodeConflict = {
+	id: "locale-code-conflict",
+	defaultSeverity: "warning",
+	description: "Locale codes that differ only in spelling, such as zh_CN and zh-CN.",
+	*run(ctx) {
+		const groups = /* @__PURE__ */ new Map();
+		for (const locale of ctx.locales) {
+			const id = localeSpellingKey(locale);
+			const group = groups.get(id) ?? [];
+			groups.set(id, group);
+			group.push(locale);
+		}
+		for (const group of groups.values()) if (group.length > 1) {
+			const resource = ctx.resources.find((r) => r.locale === group[1]);
+			yield {
+				locale: group[1],
+				location: resource ? {
+					path: resource.path,
+					range: {
+						start: 0,
+						end: 0
+					}
+				} : void 0,
+				message: `Locale codes ${list(group)} differ only in spelling; they are separate locales.`
+			};
+		}
+	}
+};
+const unusedKey = {
+	id: "unused-key",
+	defaultSeverity: "warning",
+	description: "A key with no usage, after keysInUse, derived keys and dynamic prefixes.",
+	*run(ctx) {
+		if (!ctx.hasScanners) return;
+		for (const key of ctx.unused()) yield {
+			key,
+			message: `"${key}" is not used.`,
+			fixes: [{
+				title: `Delete "${key}" in every locale`,
+				ops: [{
+					type: "delete",
+					key,
+					locales: "all"
+				}]
+			}]
+		};
+	}
+};
+const placeholderMismatch = {
+	id: "placeholder-mismatch",
+	defaultSeverity: "error",
+	description: "Target value placeholders differ from the source value.",
+	*run(ctx) {
+		const compare = createPlaceholderComparer(ctx.placeholderSyntaxes, ctx.placeholders);
+		for (const key of ctx.keys()) {
+			const source = ctx.message(key, ctx.sourceLocale);
+			if (typeof source?.value !== "string") continue;
+			for (const locale of ctx.locales) {
+				if (locale === ctx.sourceLocale) continue;
+				const target = ctx.message(key, locale);
+				if (typeof target?.value !== "string" || target.value === "") continue;
+				const { missing, extra } = compare(source.value, target.value);
+				if (missing.length || extra.length) {
+					const parts = [missing.length ? `missing ${list(missing)}` : "", extra.length ? `unexpected ${list(extra)}` : ""].filter(Boolean);
+					yield {
+						key,
+						locale,
+						message: `"${key}" in ${locale} has different placeholders than ${ctx.sourceLocale}: ${parts.join("; ")}.`
+					};
+				}
+			}
+		}
+	}
+};
+const invalidSyntax = {
+	id: "invalid-syntax",
+	defaultSeverity: "error",
+	description: "Message syntax errors (ICU, linked messages, nesting).",
+	*run(ctx) {
+		const keys = new Set(ctx.keys());
+		const exists = (key) => keys.has(key) || ctx.keys().some((k) => k.startsWith(`${key}.`));
+		for (const message of ctx.messages()) {
+			if (typeof message.value !== "string") continue;
+			const errors = [...ctx.syntaxErrors(message.value)];
+			for (const placeholder of ctx.placeholders(message.value)) if (placeholder.syntax === "linked" && !exists(placeholder.name)) errors.push(`linked message "${placeholder.name}" does not exist`);
+			for (const error of errors) yield {
+				key: message.key,
+				locale: message.locale,
+				message: `"${message.key}" in ${message.locale}: ${error}.`
+			};
+		}
+	}
+};
+const dynamicKey = {
+	id: "dynamic-key",
+	defaultSeverity: "off",
+	description: "A fully dynamic key that no check can follow.",
+	*run(ctx) {
+		for (const usage of ctx.usages()) if (usage.dynamic === "unknown") yield {
+			location: {
+				path: usage.path,
+				range: usage.range
+			},
+			message: `Dynamic key "${usage.raw}" cannot be checked.`
+		};
+	}
+};
+const identicalToSource = {
+	id: "identical-to-source",
+	defaultSeverity: "off",
+	description: "A target value that equals the source value.",
+	*run(ctx) {
+		for (const message of ctx.messages()) {
+			if (message.locale === ctx.sourceLocale || typeof message.value !== "string" || message.value === "") continue;
+			if (ctx.message(message.key, ctx.sourceLocale)?.value === message.value) yield {
+				key: message.key,
+				locale: message.locale,
+				message: `"${message.key}" in ${message.locale} is the same as in ${ctx.sourceLocale}.`
+			};
+		}
+	}
+};
+const caseRules = {
+	camel: /^[a-z][a-zA-Z0-9]*$/,
+	snake: /^[a-z][a-z0-9_]*$/,
+	kebab: /^[a-z][a-z0-9-]*$/,
+	pascal: /^[A-Z][a-zA-Z0-9]*$/
+};
+const keyStyle = {
+	id: "key-style",
+	defaultSeverity: "off",
+	description: "A key that does not match a naming rule (options: case, pattern).",
+	*run(ctx) {
+		const rule = typeof ctx.options.case === "string" ? caseRules[ctx.options.case] : void 0;
+		const pattern = typeof ctx.options.pattern === "string" ? new RegExp(ctx.options.pattern) : void 0;
+		for (const key of ctx.keys()) {
+			const path = key.slice(key.indexOf(":") + 1);
+			if (rule && !path.split(".").every((segment) => rule.test(segment))) yield {
+				key,
+				message: `"${key}" is not ${String(ctx.options.case)} case.`
+			};
+			else if (pattern && !pattern.test(key)) yield {
+				key,
+				message: `"${key}" does not match ${pattern.source}.`
+			};
+		}
+	}
+};
+const hardString = {
+	id: "hard-string",
+	defaultSeverity: "info",
+	description: "A hard-coded string that should probably be a message. On with `extract.autoDetect`.",
+	*run(ctx) {
+		if (!ctx.config.extract.autoDetect && ctx.config.checks["hard-string"] === void 0) return;
+		for (const hard of ctx.hardStrings()) if (shouldExtract(hard.text, hard.kind)) yield {
+			location: {
+				path: hard.path,
+				range: hard.range
+			},
+			message: `Hard-coded string "${hard.text}".`
+		};
+	}
+};
+/** A term as a whole word, so "Home" does not match "Homepage". */
+function wordPattern(term) {
+	return new RegExp(`(?<![\\p{L}\\p{N}])${term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\p{L}\\p{N}])`, "iu");
+}
+function* glossaryDiagnostics(ctx, entry) {
+	const term = wordPattern(entry.term);
+	for (const key of ctx.keys()) {
+		const source = ctx.message(key, ctx.sourceLocale)?.value;
+		if (typeof source !== "string" || !term.test(source)) continue;
+		for (const locale of ctx.locales) {
+			const value = ctx.message(key, locale)?.value;
+			const expected = entry.doNotTranslate ? entry.term : entry.translations?.[locale];
+			if (locale === ctx.sourceLocale || typeof value !== "string" || value === "" || !expected) continue;
+			if (!wordPattern(expected).test(value)) yield {
+				key,
+				locale,
+				message: `"${key}" in ${locale} should use "${expected}" for "${entry.term}".`
+			};
+		}
+	}
+}
+const glossary = {
+	id: "glossary",
+	defaultSeverity: "off",
+	description: "A glossary term translated differently from the glossary.",
+	*run(ctx) {
+		for (const entry of ctx.config.glossary) yield* glossaryDiagnostics(ctx, entry);
+	}
+};
+const allChecks = [
+	missingKey,
+	invalidSyntax,
+	placeholderMismatch,
+	keyConflict,
+	missingTranslation,
+	emptyTranslation,
+	unusedKey,
+	localeCodeConflict,
+	dynamicKey,
+	identicalToSource,
+	keyStyle,
+	hardString,
+	glossary
+];
+/** Every built-in check with its `recommended` severity. */
+function recommended() {
+	return {
+		name: "x18n:checks",
+		checks: allChecks
+	};
+}
+//#endregion
+export { allChecks, dynamicKey, emptyTranslation, glossary, hardString, identicalToSource, invalidSyntax, keyConflict, keyStyle, localeCodeConflict, missingKey, missingTranslation, placeholderMismatch, recommended, unusedKey };

package/dist/extractors.d.mts

@@ -0,0 +1,51 @@
+import { ExtractItem, ExtractTemplate, KeyString, Project, TextRange } from "@x18n/core";
+//#region src/extractors/index.d.ts
+export type Score = "must-include" | "should-include" | "none" | "should-exclude" | "must-exclude";
+export interface ExtractionRule {
+  readonly id: string;
+  readonly test: (text: string, kind: string) => Score;
+}
+/** Built-in rules, applied in order. A `must-*` wins at once; otherwise the last `should-*` decides. */
+export declare const rules: readonly ExtractionRule[];
+/** Folds rule scores the i18n-ally way (`shouldExtract`). */
+export declare function shouldExtract(text: string, kind: string, list?: readonly ExtractionRule[]): boolean;
+export type KeyCase = "camel" | "snake" | "kebab" | "dot";
+/** "Forgot password?" becomes `forgotPassword` (camel), `forgot_password`, `forgot-password` or `forgot.password`. */
+export declare function slugify(text: string, keyCase?: KeyCase, maxLength?: number): string;
+/** Fallback templates per kind, used after config and preset templates. */
+export declare const defaultTemplates: readonly ExtractTemplate[];
+export interface ExtractCandidate {
+  readonly path: string;
+  /** 1-based line, for display. */
+  readonly line: number;
+  readonly kind: string;
+  readonly text: string;
+  /** The text in the file at `range`, used to detect stale plans. */
+  readonly original: string;
+  readonly range: TextRange;
+  readonly attribute: string | undefined;
+  readonly key: KeyString;
+  /** True when an existing key with the same source value is reused. */
+  readonly reused: boolean;
+  /** The message to store: template arguments become placeholders. */
+  readonly value: string;
+  readonly replacement: string;
+  readonly imports: readonly string[];
+  /** Other templates that also apply, for surfaces that let users choose. */
+  readonly alternatives: readonly string[];
+}
+export interface FindOptions {
+  /** Only these files (globs). */
+  readonly files?: readonly string[] | undefined;
+}
+/** Hard strings worth extracting, with proposed keys, values and replacements. */
+export declare function findCandidates(project: Project, options?: FindOptions): ExtractCandidate[];
+export interface ExtractPlanFile {
+  readonly x18n: 1;
+  readonly project: string;
+  readonly items: readonly ExtractCandidate[];
+}
+export declare function toPlanFile(project: Project, candidates: readonly ExtractCandidate[]): ExtractPlanFile;
+/** Turns plan items (maybe edited by a human or agent) into edit items, after checking the files did not change. */
+export declare function extractItems(project: Project, items: readonly Pick<ExtractCandidate, "path" | "range" | "original" | "key" | "value" | "replacement" | "imports">[]): ExtractItem[];
+//#endregion

package/dist/extractors.mjs

@@ -0,0 +1,269 @@
+import { X18nError, createLineIndex, pathMatcher } from "@x18n/core";
+//#region src/extractors/index.ts
+const textKinds = /* @__PURE__ */ new Set([
+	"jsx-text",
+	"vue-template-text",
+	"svelte-text",
+	"html-text"
+]);
+/** Built-in rules, applied in order. A `must-*` wins at once; otherwise the last `should-*` decides. */
+const rules = [
+	{
+		id: "letters",
+		test: (text) => /\p{L}/u.test(text) ? "none" : "must-exclude"
+	},
+	{
+		id: "digits",
+		test: (text) => /^[\d\s.,:%+-]+$/.test(text) ? "must-exclude" : "none"
+	},
+	{
+		id: "url",
+		test: (text) => /^(?:[a-z][\w+.-]*:\/\/|mailto:|#|\/\/)/i.test(text.trim()) ? "must-exclude" : "none"
+	},
+	{
+		id: "path",
+		test: (text) => /^(?:\.{0,2}\/|~\/|@\/)[\w./@-]*$/.test(text.trim()) || /^[\w-]+\.[a-z]{2,4}$/i.test(text.trim()) ? "must-exclude" : "none"
+	},
+	{
+		id: "translate-call",
+		test: (text) => /\$?t\(['"`]/.test(text) || text.includes("{{") ? "must-exclude" : "none"
+	},
+	{
+		id: "markup",
+		test: (text) => /^<[^>]+>$/.test(text.trim()) ? "must-exclude" : "none"
+	},
+	{
+		id: "non-ascii",
+		test: (text) => /\P{ASCII}/u.test(text) && /\p{L}/u.test(text) ? "must-include" : "none"
+	},
+	{
+		id: "sentence",
+		test: (text) => /\p{L}\s+\p{L}/u.test(text) ? "should-include" : "none"
+	},
+	{
+		id: "text-node",
+		test: (text, kind) => textKinds.has(kind) || kind.endsWith("attribute") ? "should-include" : "none"
+	},
+	{
+		id: "single-word",
+		test: (text, kind) => !textKinds.has(kind) && !kind.endsWith("attribute") && !/\s/.test(text.trim()) ? "should-exclude" : "none"
+	},
+	{
+		id: "attribute-token",
+		test: (text, kind) => kind.endsWith("attribute") && /^[a-z][\w-]*$/.test(text.trim()) ? "must-exclude" : "none"
+	},
+	{
+		id: "identifier",
+		test: (text) => /^[a-z]+(?:[A-Z][a-z\d]*)+$/.test(text) || /^[A-Z\d]+(?:_[A-Z\d]+)+$/.test(text) || /^[a-z\d]+(?:[-_.:][a-z\d]+)+$/.test(text) ? "should-exclude" : "none"
+	}
+];
+/** Folds rule scores the i18n-ally way (`shouldExtract`). */
+function shouldExtract(text, kind, list = rules) {
+	let result = "none";
+	for (const rule of list) {
+		const score = rule.test(text, kind);
+		if (score === "must-include") return true;
+		if (score === "must-exclude") return false;
+		if (score !== "none") result = score;
+	}
+	return result === "should-include";
+}
+/** Words of a text for slugs: letters and digits only. */
+function words(text) {
+	return text.normalize("NFKD").replace(/[\u0300-\u036F]/g, "").split(/[^\p{L}\d]+/u).filter(Boolean);
+}
+/** "Forgot password?" becomes `forgotPassword` (camel), `forgot_password`, `forgot-password` or `forgot.password`. */
+function slugify(text, keyCase = "camel", maxLength = 40) {
+	const parts = [];
+	let length = 0;
+	for (const word of words(text).map((w) => w.toLowerCase())) {
+		if (length + word.length > maxLength && parts.length > 0) break;
+		parts.push(word);
+		length += word.length + 1;
+	}
+	if (parts.length === 0) return "text";
+	switch (keyCase) {
+		case "snake": return parts.join("_");
+		case "kebab": return parts.join("-");
+		case "dot": return parts.join(".");
+		default: return parts.map((word, i) => i === 0 ? word : word[0].toUpperCase() + word.slice(1)).join("");
+	}
+}
+/** Fallback templates per kind, used after config and preset templates. */
+const defaultTemplates = [
+	{
+		template: "{t('{key}'{args})}",
+		kinds: ["jsx-text"]
+	},
+	{
+		template: "{attr}={t('{key}'{args})}",
+		kinds: ["jsx-attribute"]
+	},
+	{
+		template: "{{ $t('{key}'{args}) }}",
+		kinds: ["vue-template-text", "html-text"]
+	},
+	{
+		template: ":{attr}=\"$t('{key}'{args})\"",
+		kinds: ["vue-attribute"]
+	},
+	{
+		template: "{$t('{key}'{args})}",
+		kinds: ["svelte-text"]
+	},
+	{
+		template: "{attr}={$t('{key}'{args})}",
+		kinds: ["svelte-attribute"]
+	},
+	{ template: "t('{key}'{args})" }
+];
+function prefixFor(template, path) {
+	if (!template) return "";
+	const base = path.slice(path.lastIndexOf("/") + 1).replace(/\.[^.]+$/, "");
+	const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")).split("/").at(-1) : "";
+	return template.replace("{fileName}", slugify(base)).replace("{dirName}", slugify(dir)).replace("{component}", base.replace(/(?:^|[-_])(\w)/g, (_, c) => c.toUpperCase()));
+}
+function randomKey() {
+	return Math.random().toString(36).slice(2, 10);
+}
+var KeyAllocator = class {
+	project;
+	byValue = /* @__PURE__ */ new Map();
+	taken = /* @__PURE__ */ new Map();
+	constructor(project) {
+		this.project = project;
+		const options = project.config.extract;
+		for (const key of project.keys()) {
+			const value = project.message(key, project.sourceLocale)?.value;
+			if (typeof value === "string") {
+				this.taken.set(key, value);
+				if (options.reuseExisting !== false && !this.byValue.has(value)) this.byValue.set(value, key);
+			}
+		}
+	}
+	allocate(value, path, slugText) {
+		const options = this.project.config.extract;
+		const reused = this.byValue.get(value);
+		if (reused) return {
+			key: reused,
+			reused: this.taken.has(reused)
+		};
+		const strategy = options.keygen ?? "slug";
+		const prefix = prefixFor(options.keyPrefix, path);
+		let base;
+		if (strategy === "source") base = value;
+		else if (strategy === "random") base = randomKey();
+		else if (strategy === "empty") base = "";
+		else base = slugify(slugText, options.keyCase ?? "camel", options.keyMaxLength ?? 40);
+		const raw = prefix ? `${prefix}.${base}` : base;
+		let key = this.project.parseKey(raw);
+		for (let i = 2; this.taken.has(key) && this.taken.get(key) !== value; i++) key = this.project.parseKey(`${raw}${i}`);
+		this.taken.set(key, value);
+		this.byValue.set(value, key);
+		return {
+			key,
+			reused: false
+		};
+	}
+};
+function isIgnored(project, hard, text) {
+	const options = project.config.extract;
+	const matches = (rule) => {
+		const regex = /^\/(.+)\/([a-z]*)$/.exec(rule);
+		return regex ? new RegExp(regex[1], regex[2]).test(hard.text) : rule === hard.text;
+	};
+	if (options.ignore?.some(matches)) return true;
+	for (const [glob, list] of Object.entries(options.ignoreByFile ?? {})) if (pathMatcher([glob])(hard.path) && list.some(matches)) return true;
+	if (hard.attribute && options.ignoreAttributes?.includes(hard.attribute)) return true;
+	const index = createLineIndex(text);
+	const line = index.position(hard.range.start).line;
+	return index.line(line).includes("x18n-ignore") || line > 0 && index.line(line - 1).includes("x18n-ignore");
+}
+/** Placeholder shape of the project's first placeholder syntax, `{name}` by default. */
+function placeholderShape(project) {
+	const example = project.placeholderSyntaxes.find((s) => s.example?.includes("name"))?.example ?? "{name}";
+	return (name) => example.replace("name", name);
+}
+function templatesFor(project, kind, path) {
+	return [...project.extractTemplates, ...defaultTemplates].filter((t) => (!t.kinds || t.kinds.includes(kind)) && (!t.files || pathMatcher(t.files)(path))).map((t) => t.template);
+}
+function rawKeyFor(project, key) {
+	const ns = project.config.namespace.default;
+	return project.namespaced && ns && key.startsWith(`${ns}:`) ? key.slice(ns.length + 1) : key;
+}
+/**
+* Escapes a key for the quotes around `{key}` in a template, since `keygen: 'source'` keys hold any text:
+* backslashes inside a JS string, entities inside a double-quoted attribute (`:title="$t('{key}')"`).
+*/
+function quoteKey(before, key) {
+	const quote = before.at(-1);
+	const inAttribute = /="[^"]*$/.test(before);
+	let out = key;
+	if (quote === "'" || quote === "`" || quote === "\"" && !inAttribute) out = out.replace(quote === "`" ? /[\\`]|\$\{/g : new RegExp(`[\\\\${quote}]`, "g"), (c) => `\\${c}`);
+	return inAttribute ? out.replace(/&/g, "&amp;").replace(/"/g, "&quot;") : out;
+}
+function fillTemplate(template, values) {
+	return template.replace(/\{(key|attr|args)\}/g, (_, name, at) => name === "key" ? quoteKey(template.slice(0, at), values.key) : values[name]);
+}
+/** Hard strings worth extracting, with proposed keys, values and replacements. */
+function findCandidates(project, options = {}) {
+	const inFiles = options.files?.length ? pathMatcher(options.files) : void 0;
+	const keys = new KeyAllocator(project);
+	const shape = placeholderShape(project);
+	const out = [];
+	for (const hard of project.hardStrings()) {
+		if (inFiles && !inFiles(hard.path)) continue;
+		const text = project.text(hard.path);
+		if (text === void 0 || !shouldExtract(hard.text, hard.kind) || isIgnored(project, hard, text)) continue;
+		const value = hard.kind === "js-template" ? hard.text.replace(/\{(\d+)\}/g, (_, i) => shape(hard.args?.[Number(i)]?.name ?? `arg${i}`)) : hard.text;
+		const { key, reused } = keys.allocate(value, hard.path, hard.text.replace(/\{\d+\}/g, " "));
+		const templates = templatesFor(project, hard.kind, hard.path);
+		const chosen = templates[0];
+		const args = hard.args?.length ? `, { ${hard.args.map((a) => a.name === a.expression ? a.name : `${a.name}: ${a.expression}`).join(", ")} }` : "";
+		const template = project.extractTemplates.find((t) => t.template === chosen);
+		out.push({
+			path: hard.path,
+			line: createLineIndex(text).position(hard.range.start).line + 1,
+			kind: hard.kind,
+			text: hard.text,
+			original: text.slice(hard.range.start, hard.range.end),
+			range: hard.range,
+			attribute: hard.attribute,
+			key,
+			reused,
+			value,
+			replacement: fillTemplate(chosen, {
+				key: rawKeyFor(project, key),
+				attr: hard.attribute ?? "",
+				args
+			}),
+			imports: template?.imports ?? [],
+			alternatives: templates.slice(1)
+		});
+	}
+	return out;
+}
+function toPlanFile(project, candidates) {
+	return {
+		x18n: 1,
+		project: project.name,
+		items: candidates
+	};
+}
+/** Turns plan items (maybe edited by a human or agent) into edit items, after checking the files did not change. */
+function extractItems(project, items) {
+	return items.map((item) => {
+		const text = project.text(item.path);
+		if (text === void 0 || text.slice(item.range.start, item.range.end) !== item.original) throw new X18nError("X18N4004", `${item.path} changed since the plan was made`);
+		return {
+			path: item.path,
+			range: item.range,
+			key: project.parseKey(item.key),
+			value: item.value,
+			replacement: item.replacement,
+			imports: item.imports
+		};
+	});
+}
+//#endregion
+export { defaultTemplates, extractItems, findCandidates, rules, shouldExtract, slugify, toPlanFile };