@x18n/core 0.1.6 → 0.1.7

package/dist/index.mjs

@@ -286,26 +286,51 @@ function fuzzyScore(query, text) {
 }
 //#endregion
 //#region src/keys.ts
-/** Canonical string form of a key: `ns:a.b.c`, or `a.b.c` without namespace. */
-function joinKey(namespace, path) {
-	const dotted = path.join(".");
-	return namespace === void 0 ? dotted : `${namespace}:${dotted}`;
+/** The text between path segments in a key string: the separator, or `.` when keys are literal. */
+function keyJoiner(separator) {
+	return separator === false ? "." : separator;
 }
-/** Splits a key string. `namespaced` is false for projects without namespaces, where `:` is part of the key. */
-function splitKey(key, namespaced = true) {
-	const index = namespaced ? key.indexOf(":") : -1;
-	const namespace = index === -1 ? void 0 : key.slice(0, index);
-	const rest = index === -1 ? key : key.slice(index + 1);
+/** Path segments of the part of a key after its namespace. With `false` the whole text is one segment. */
+function splitKeyPath(text, separator = ".") {
+	if (text === "") return [];
+	return separator === false ? [text] : text.split(separator);
+}
+/** Canonical string form of a key: `ns:a.b.c`, or `a.b.c` without namespace. `separator` joins the path (`.` by default). */
+function joinKey(namespace, path, separator = ".") {
+	const joined = path.join(keyJoiner(separator));
+	return namespace === void 0 ? joined : `${namespace}:${joined}`;
+}
+/**
+* Splits a key string. `namespaced` is false for projects without namespaces, where `:` is part of the key.
+* The namespace ends at the first `:`, so the rest of the key may hold more. With `separator: false` the path is one literal segment.
+*/
+function splitKey(key, namespaced = true, separator = ".") {
+	const { namespace, rest } = splitNamespace(key, namespaced);
 	return {
 		namespace,
-		path: rest === "" ? [] : rest.split(".")
+		path: splitKeyPath(rest, separator)
 	};
 }
-/** True when `key` is `prefix` itself or lies under it (`a.b` is under `a`). */
-function isKeyUnder(key, prefix) {
+/** The namespace of a key string and the text after it. */
+function splitNamespace(key, namespaced) {
+	const index = namespaced ? key.indexOf(":") : -1;
+	return index === -1 ? {
+		namespace: void 0,
+		rest: key
+	} : {
+		namespace: key.slice(0, index),
+		rest: key.slice(index + 1)
+	};
+}
+/** The key separator of a resource: its own (from its resource spec), else the config's. */
+function keySeparatorOf(resource, fallback) {
+	return resource.keySeparator ?? fallback;
+}
+/** True when `key` is `prefix` itself or lies under it (`a.b` is under `a`). A literal key (`separator: false`) has nothing under it but in its namespace. */
+function isKeyUnder(key, prefix, separator = ".") {
 	if (key === prefix) return true;
-	const sep = prefix.endsWith(":") ? "" : ".";
-	return key.startsWith(prefix + sep);
+	if (prefix.endsWith(":")) return key.startsWith(prefix);
+	return separator !== false && key.startsWith(prefix + separator);
 }
 /** Replaces the `from` prefix of `key` with `to`. */
 function replaceKeyPrefix(key, from, to) {
@@ -354,10 +379,10 @@ function globToRegExp(glob, separator = "/") {
 	}
 	return new RegExp(`^${out}$`);
 }
-/** Matcher over key globs: `*` stays inside a segment, `**` spans segments. */
-function keyMatcher(globs) {
+/** Matcher over key globs: `*` stays inside a segment, `**` spans segments. With literal keys (`separator: false`) `*` spans the whole key. */
+function keyMatcher(globs, separator = ".") {
 	if (globs.length === 0) return () => false;
-	const regexes = globs.map((glob) => globToRegExp(glob, "."));
+	const regexes = globs.map((glob) => globToRegExp(glob, separator === false ? "\0" : separator));
 	return (key) => regexes.some((re) => re.test(key));
 }
 /** Matcher over posix file paths. */
@@ -381,6 +406,7 @@ function createLibraryPlugin(options) {
 			};
 			if (options.resources) draft.resources = [...draft.resources, ...options.resources.filter((spec) => !draft.resources.some((r) => r.pattern === spec.pattern))];
 			if (options.keyStyle && draft.keyStyle === "auto" && !ctx.user.keyStyle) draft.keyStyle = options.keyStyle;
+			if (options.keySeparator !== void 0 && ctx.user.keySeparator === void 0) draft.keySeparator = options.keySeparator;
 			draft.usage = {
 				...draft.usage,
 				calls: [...draft.usage.calls, ...options.calls ?? []],
@@ -666,7 +692,8 @@ function uniqueById(items, kind) {
 function createRegistry(input, config) {
 	const plugins = sortByEnforce(input);
 	const formats = plugins.flatMap((plugin) => [...plugin.formats ?? [], ...plugin.lazyFormats ?? []]);
-	const scanners = plugins.flatMap((plugin) => [...plugin.scanners ?? [], ...plugin.lazyScanners ?? []]);
+	const lazyIds = /* @__PURE__ */ new Set();
+	const scanners = plugins.flatMap((plugin) => [...plugin.scanners ?? [], ...(plugin.lazyScanners ?? []).filter((entry) => !lazyIds.has(entry.id) && lazyIds.add(entry.id))]);
 	const finders = [...uniqueById(plugins.flatMap((plugin) => plugin.localeFinders ?? []), "Locale finder").values()];
 	const checks = uniqueById(plugins.flatMap((plugin) => plugin.checks ?? []), "Check");
 	const reporters = uniqueById(plugins.flatMap((plugin) => plugin.reporters ?? []), "Reporter");
@@ -802,6 +829,7 @@ const callSpec = v.strictObject({
 	keyPrefix: v.optional(argSource),
 	params: v.optional(paramsSource),
 	defaultValue: v.optional(v.array(argSource)),
+	description: v.optional(v.string()),
 	factory: v.optional(v.boolean()),
 	returns: v.optional(strings),
 	types: v.optional(strings)
@@ -810,12 +838,14 @@ const regexSpec = v.strictObject({
 	extensions: strings,
 	patterns: strings
 });
+const keySeparator = v.union([v.pipe(v.string(), v.minLength(1)), v.literal(false)]);
 const resourceSpec = v.strictObject({
 	pattern: v.string(),
 	format: v.optional(v.string()),
 	namespace: v.optional(v.string()),
 	locale: v.optional(v.string()),
-	execute: v.optional(v.boolean())
+	execute: v.optional(v.boolean()),
+	keySeparator: v.optional(keySeparator)
 });
 const pluginSpecifier = v.union([v.string(), v.tuple([v.string(), jsonObject])]);
 const extractTemplate = v.strictObject({
@@ -857,7 +887,7 @@ const glossaryEntry = v.strictObject({
 });
 const checkSetting = v.union([level, v.tuple([level, jsonObject])]);
 const namespaceOptions = v.strictObject({
-	separator: v.optional(v.string()),
+	separator: v.optional(v.union([v.pipe(v.string(), v.minLength(1)), v.literal(false)])),
 	default: v.optional(v.string()),
 	fallback: v.optional(strings),
 	byFile: v.optional(v.record(v.string(), v.string())),
@@ -889,6 +919,7 @@ const ConfigSchema = v.strictObject({
 		"nested",
 		"flat"
 	])),
+	keySeparator: v.optional(keySeparator),
 	namespace: v.optional(namespaceOptions),
 	usage: v.optional(v.strictObject({
 		include: v.optional(strings),
@@ -937,7 +968,8 @@ const PluginFileSchema = v.strictObject({
 			"auto",
 			"nested",
 			"flat"
-		]))
+		])),
+		keySeparator: v.optional(keySeparator)
 	})),
 	scanners: v.optional(v.strictObject({
 		calls: v.optional(v.array(callSpec)),
@@ -1137,46 +1169,55 @@ function innermost(scopes, range) {
 	for (const scope of scopes) if (scope.range.start <= range.start && scope.range.end >= range.end && (!best || scope.range.end - scope.range.start < best.range.end - best.range.start)) best = scope;
 	return best;
 }
+function joinPrefix(prefix, text, joiner) {
+	return text ? `${prefix}${joiner}${text}` : prefix;
+}
+/** The first prefix whose key exists. A prefix usage (`items.${id}`) ends in an empty segment, so its parent key decides. */
+function definedPrefix(prefixes, text, joiner, dynamicPrefix, exists) {
+	return prefixes.find((prefix) => {
+		const prefixed = joinPrefix(prefix, text, joiner);
+		return exists(dynamicPrefix && prefixed.endsWith(joiner) ? prefixed.slice(0, -joiner.length) : prefixed);
+	});
+}
 function createUsageResolver(config, namespaced, normalizers) {
 	const { separator, fallback } = config.namespace;
+	const joiner = keyJoiner(config.keySeparator);
+	const keyOf = (namespace, text) => namespace === void 0 ? text : `${namespace}:${text}`;
+	const normalize = (raw, ctx) => {
+		for (const normalizer of normalizers) {
+			const result = normalizer(raw, ctx);
+			if (result !== void 0) return result;
+		}
+		return raw;
+	};
 	const byFile = Object.entries(config.namespace.byFile).map(([glob, namespace]) => ({
 		matches: pathMatcher([glob]),
 		namespace
 	}));
 	return { resolve(candidate, scopes, path, scanner, has) {
 		const scope = innermost(scopes, candidate.range);
-		const ctx = { path };
-		let text = candidate.raw;
-		for (const normalize of normalizers) {
-			const result = normalize(text, ctx);
-			if (result !== void 0) {
-				text = result;
-				break;
-			}
-		}
+		let text = normalize(candidate.raw, { path });
 		const scopeNamespace = candidate.namespace ?? scope?.namespace ?? byFile.find((rule) => rule.matches(path))?.namespace;
 		let scopePrefix = candidate.keyPrefix ?? scope?.keyPrefix;
 		let namespace;
 		let explicit = false;
 		if (namespaced) {
-			const index = text.indexOf(separator);
+			const index = separator === false ? -1 : text.indexOf(separator);
 			explicit = index > 0;
 			if (explicit) {
 				namespace = text.slice(0, index);
-				text = text.slice(index + separator.length);
+				text = text.slice(index + (separator || "").length);
 			} else namespace = scopeNamespace ?? config.namespace.default;
 		}
 		if (scopePrefix && !explicit) {
-			const prefixed = text ? `${scopePrefix}.${text}` : scopePrefix;
-			const lookup = candidate.dynamic === "prefix" ? prefixed.replace(/\.$/, "") : prefixed;
-			if (candidate.keyPrefix || !scope?.optionalPrefix || has(joinKey(namespace, lookup.split(".")))) text = prefixed;
-			else scopePrefix = void 0;
+			const chosen = !candidate.keyPrefix && scope?.optionalPrefix ? definedPrefix([scopePrefix, ...scope.otherPrefixes ?? []], text, joiner, candidate.dynamic === "prefix", (lookup) => (scope.prefixInFallback ? [namespace, ...fallback] : [namespace]).some((ns) => has(keyOf(ns, lookup)))) : scopePrefix;
+			scopePrefix = chosen;
+			if (chosen) text = joinPrefix(chosen, text, joiner);
 		}
-		const keyPath = text === "" ? [] : text.split(".");
 		let key;
 		if (candidate.dynamic === "unknown") key = void 0;
-		else key = joinKey(namespace, keyPath);
-		if (key !== void 0 && namespaced && !explicit && candidate.dynamic === false && !has(key)) key = fallback.map((ns) => joinKey(ns, keyPath)).find(has) ?? key;
+		else key = keyOf(namespace, text);
+		if (key !== void 0 && namespaced && !explicit && candidate.dynamic === false && !has(key)) key = fallback.map((ns) => keyOf(ns, text)).find(has) ?? key;
 		return {
 			key,
 			raw: candidate.raw,
@@ -1185,6 +1226,7 @@ function createUsageResolver(config, namespaced, normalizers) {
 			expression: candidate.expression,
 			...candidate.params ? { params: candidate.params } : {},
 			...candidate.defaultValue === void 0 ? {} : { defaultValue: candidate.defaultValue },
+			...candidate.description === void 0 ? {} : { description: candidate.description },
 			scanner,
 			kind: candidate.kind,
 			dynamic: candidate.dynamic,
@@ -1425,8 +1467,8 @@ function runChecks(input) {
 function createAnalyzer(options) {
 	const { config, registry } = options;
 	let memo;
-	const ignored = keyMatcher(config.ignoreKeys);
-	const inUse = keyMatcher(config.usage.keysInUse);
+	const ignored = keyMatcher(config.ignoreKeys, config.keySeparator);
+	const inUse = keyMatcher(config.usage.keysInUse, config.keySeparator);
 	const placeholderCache = /* @__PURE__ */ new Map();
 	function analyze() {
 		const state = options.state();
@@ -1684,19 +1726,19 @@ function nodeAt(tree, path) {
 	return node;
 }
 /** True for flat files (`{ "a.b": "x" }`), false for nested ones, undefined when it cannot tell. */
-function isFlatTree(tree) {
+function isFlatTree(tree, separator) {
 	const entries = Object.entries(tree);
 	if (entries.length === 0) return void 0;
 	if (entries.some(([, value]) => !isMessageLeaf(value))) return false;
-	return entries.some(([key]) => key.includes(".")) ? true : void 0;
+	return entries.some(([key]) => key.includes(separator)) ? true : void 0;
 }
 /** The longest key prefix a tree shares with `path`. */
-function longestPrefix(tree, prefix, path) {
+function longestPrefix(tree, prefix, path, separator) {
 	let best = 0;
 	for (const [segment, child] of Object.entries(tree)) {
-		const next = [...prefix, ...segment.split(".")];
+		const next = [...prefix, ...splitKeyPath(segment, separator)];
 		best = Math.max(best, commonPrefix(next, path));
-		if (!isMessageLeaf(child)) best = Math.max(best, longestPrefix(child, next, path));
+		if (!isMessageLeaf(child)) best = Math.max(best, longestPrefix(child, next, path, separator));
 	}
 	return best;
 }
@@ -1755,6 +1797,7 @@ var PlanBuilder = class {
 			path: s.resource.path,
 			locale: s.resource.locale,
 			namespace: s.resource.namespace,
+			keySeparator: s.resource.keySeparator,
 			format,
 			state: s
 		};
@@ -1779,24 +1822,36 @@ var PlanBuilder = class {
 		return s;
 	}
 	keyId(key) {
-		const id = splitKey(key, this.state.namespaced);
+		const id = splitKey(key, this.state.namespaced, this.config.keySeparator);
 		return {
 			namespace: id.namespace,
 			path: [...id.path]
 		};
 	}
-	/** Key path relative to a resource, or undefined when the key does not belong there. */
+	separatorOf(target) {
+		return keySeparatorOf(target, this.config.keySeparator);
+	}
+	/**
+	* Key path relative to a resource, or undefined when the key does not belong there.
+	* A resource of literal keys (`keySeparator: false`) gets the whole rest of the key as one segment.
+	*/
 	relativePath(key, target) {
-		const { namespace, path } = this.keyId(key);
+		const { namespace, rest } = splitNamespace(key, this.state.namespaced);
+		const literal = this.separatorOf(target) === false;
+		const joiner = keyJoiner(this.config.keySeparator);
+		const split = (text) => splitKeyPath(text, literal ? false : joiner);
 		const fallback = this.config.namespace.default;
-		if (this.state.namespaced) return (namespace ?? fallback) === (target.namespace ?? fallback) ? path : void 0;
-		const prefix = target.namespace ? target.namespace.split(".") : [];
-		if (path.length <= prefix.length || prefix.some((segment, i) => path[i] !== segment)) return void 0;
-		return path.slice(prefix.length);
+		if (this.state.namespaced) return (namespace ?? fallback) === (target.namespace ?? fallback) ? split(rest) : void 0;
+		if (!target.namespace) return rest === "" ? void 0 : split(rest);
+		const prefix = target.namespace.split(".").join(joiner) + joiner;
+		if (rest.length <= prefix.length || !rest.startsWith(prefix)) return void 0;
+		return split(rest.slice(prefix.length));
 	}
 	storedPathFor(entry, relative) {
 		const stored = this.options.toStored(entry.target, relative);
-		return stored.length === relative.length && (isFlatTree(entry.tree) ?? this.config.keyStyle === "flat") ? [stored.join(".")] : stored;
+		const separator = this.separatorOf(entry.target);
+		if (separator === false) return stored;
+		return stored.length === relative.length && (isFlatTree(entry.tree, separator) ?? this.config.keyStyle === "flat") ? [stored.join(separator)] : stored;
 	}
 	createTarget(key, locale) {
 		const { resources, sourceLocale, namespaced } = this.state;
@@ -1816,6 +1871,7 @@ var PlanBuilder = class {
 					path: resolved,
 					locale,
 					namespace,
+					keySeparator: model?.resource.keySeparator,
 					format,
 					state: void 0
 				};
@@ -1835,6 +1891,7 @@ var PlanBuilder = class {
 			path,
 			locale,
 			namespace: namespace ?? model.resource.namespace,
+			keySeparator: model.resource.keySeparator,
 			format,
 			state: void 0
 		};
@@ -1854,7 +1911,7 @@ var PlanBuilder = class {
 			const prefix = s.resource.namespace && !this.state.namespaced ? path.slice(0, s.resource.namespace.split(".").length) : [];
 			return {
 				s,
-				best: longestPrefix(s.tree, prefix, path)
+				best: longestPrefix(s.tree, prefix, path, this.separatorOf(s.resource))
 			};
 		});
 		const top = Math.max(...scores.map((x) => x.best));
@@ -1966,8 +2023,9 @@ var PlanBuilder = class {
 				continue;
 			}
 			const entry = this.workFor(this.targetOf(s));
-			const flat = m.storedPath.length === 1 && m.storedPath[0].includes(".");
-			const next = flat ? [relative.join(".")] : this.options.toStored(s.resource, relative);
+			const separator = this.separatorOf(s.resource);
+			const flat = separator !== false && m.storedPath.length === 1 && m.storedPath[0].includes(separator);
+			const next = flat ? [relative.join(separator)] : this.options.toStored(s.resource, relative);
 			const sameParent = next.length === m.storedPath.length && next.slice(0, -1).every((segment, i) => segment === m.storedPath[i]);
 			const last = next.at(-1);
 			if (sameParent && m.range && (flat ? safeFlat : safeSegment).test(last)) {
@@ -1999,16 +2057,17 @@ var PlanBuilder = class {
 			const scope = usage.key.slice(0, usage.key.length - usage.raw.length);
 			if (next.startsWith(`${scope}.`)) return next.slice(scope.length);
 		}
-		const { namespace, path } = this.keyId(next);
-		let rest = path.join(".");
+		const { namespace, rest: text } = splitNamespace(next, this.state.namespaced);
+		let rest = text;
 		const separator = this.config.namespace.separator;
-		const explicit = this.state.namespaced && usage.raw.indexOf(separator) > 0;
+		const explicit = this.state.namespaced && separator !== false && usage.raw.indexOf(separator) > 0;
 		if (usage.scopePrefix && !explicit) {
-			if (!rest.startsWith(`${usage.scopePrefix}.`)) return void 0;
-			rest = rest.slice(usage.scopePrefix.length + 1);
+			const prefix = usage.scopePrefix + keyJoiner(this.config.keySeparator);
+			if (!rest.startsWith(prefix)) return void 0;
+			rest = rest.slice(prefix.length);
 		}
 		if (!this.state.namespaced) return rest;
-		if (explicit || namespace !== (usage.scopeNamespace ?? this.config.namespace.default)) return `${namespace}${separator}${rest}`;
+		if (explicit || namespace !== (usage.scopeNamespace ?? this.config.namespace.default)) return separator === false ? void 0 : `${namespace}${separator}${rest}`;
 		return rest;
 	}
 	editSource(path, edit) {
@@ -2053,7 +2112,7 @@ var PlanBuilder = class {
 		if (op.from === op.to) return;
 		const all = this.options.allKeys();
 		const isLeaf = this.options.messages(op.from) !== void 0;
-		const under = all.filter((key) => isKeyUnder(key, op.from));
+		const under = all.filter((key) => isKeyUnder(key, op.from, this.config.keySeparator));
 		const derived = all.filter((key) => this.options.basesOf(key).includes(op.from));
 		let keys;
 		if (op.type === "rename-prefix") keys = under;
@@ -2073,7 +2132,7 @@ var PlanBuilder = class {
 		this.rewritePrefixUsages(op.from, op.to);
 	}
 	delete(op) {
-		const keys = this.options.messages(op.key) ? [op.key] : this.options.allKeys().filter((key) => isKeyUnder(key, op.key));
+		const keys = this.options.messages(op.key) ? [op.key] : this.options.allKeys().filter((key) => isKeyUnder(key, op.key, this.config.keySeparator));
 		if (keys.length === 0) throw errors.X18N4006({ key: op.key });
 		for (const key of keys) {
 			this.touched.add(key);
@@ -2417,6 +2476,10 @@ function createPlanner(options) {
 }
 //#endregion
 //#region src/project/prompt.ts
+/** Related locales shown per message, at most. */
+const RELATED_LIMIT = 2;
+/** Characters of a description or a related value, at most; longer text is cut. */
+const TEXT_LIMIT = 300;
 function text(value) {
 	return value === void 0 || value === null ? void 0 : String(value);
 }
@@ -2451,10 +2514,36 @@ function reportedValues(project, diagnostics, to, check) {
 	}
 	return reported;
 }
+function clip(value) {
+	return value.length > TEXT_LIMIT ? `${value.slice(0, 299)}…` : value;
+}
+const subtagsOf = (code) => code.toLowerCase().split(/[-_]/);
+/**
+* The locales whose values help translate to `to`, nearest first: the fallback chain of `to`, then the other locales of
+* the same language, those that share more subtags with `to` first, then the shorter codes (`pt` and `pt-PT` for `pt-BR`,
+* `pt-BR` for `pt`). The source locale and `to` itself are never related.
+*/
+function relatedLocales(to, locales, sourceLocale, fallbacks) {
+	const target = subtagsOf(to);
+	const shared = (code) => {
+		const tags = subtagsOf(code);
+		let n = 0;
+		while (n < tags.length && tags[n] === target[n]) n++;
+		return n;
+	};
+	const chain = fallbackChain(fallbacks, to).filter((code) => code !== sourceLocale && code !== to);
+	const language = locales.filter((code) => code !== to && code !== sourceLocale && !chain.includes(code) && shared(code) > 0).sort((a, b) => shared(b) - shared(a) || subtagsOf(a).length - subtagsOf(b).length || a.localeCompare(b));
+	return [...chain, ...language];
+}
+/** The description of a key: from the source resource, else another locale's, else a usage's. */
+function descriptionOf(project, key, from) {
+	const trimmed = (project.message(key, from)?.description ?? project.locales.map((locale) => project.message(key, locale)?.description).find(Boolean) ?? project.usages({ key }).map(({ usage }) => usage.description).find(Boolean))?.replace(/\s+/g, " ").trim();
+	return trimmed ? clip(trimmed) : void 0;
+}
 /** Builds the parts of a translate or review prompt from project state. */
 function buildPrompt(project, kind, to, options, extra) {
 	const from = project.sourceLocale;
-	const match = typeof options.keys === "string" ? keyMatcher([options.keys]) : void 0;
+	const match = typeof options.keys === "string" ? keyMatcher([options.keys], extra.config.keySeparator) : void 0;
 	const list = Array.isArray(options.keys) ? new Set(options.keys) : void 0;
 	const analysis = project.analyze();
 	const outdated = new Set(analysis.coverage.find((c) => c.locale === to)?.outdated);
@@ -2475,12 +2564,24 @@ function buildPrompt(project, kind, to, options, extra) {
 	const end = start + page.length;
 	const syntaxes = project.placeholderSyntaxes;
 	const info = project.localeInfo(to);
+	const related = options.related === false ? [] : Array.isArray(options.related) ? options.related.filter((code) => code !== to && code !== from) : relatedLocales(to, project.locales, from, extra.fallbacks);
+	const relatedOf = (key, source) => related.flatMap((locale) => {
+		const value = text(project.message(key, locale)?.value);
+		return value && value !== source ? [{
+			locale,
+			value: clip(value)
+		}] : [];
+	}).slice(0, RELATED_LIMIT);
+	const relatedValues = new Map(page.map((key) => [key, relatedOf(key, text(project.message(key, from)?.value) ?? "")]));
+	const descriptions = new Map(page.map((key) => [key, descriptionOf(project, key, from)]));
 	const draft = {
 		rules: [],
 		notes: []
 	};
 	if (syntaxes.length > 0) draft.rules.push(`Keep every placeholder exactly as written (${syntaxes.map((s) => `\`${s.example ?? s.id}\``).join(", ")}); do not translate their names.`);
 	draft.rules.push("Keep markup tags and their attributes as they are.", "Match the tone and wording of the existing messages in the target locale.", "Do not translate glossary terms marked \"do not translate\".");
+	if ([...descriptions.values()].some(Boolean)) draft.rules.push("A description tells what a message means or where it appears: follow it, and do not translate it.");
+	if ([...relatedValues.values()].some((values) => values.length > 0)) draft.rules.push(`Values in related locales are references: keep what fits ${to}, and change the spelling, words and forms that differ.`);
 	if (reported.size > 0) draft.rules.push(`A message with a reported problem has a current ${to} value: fix the problem. When the current value is right as it is, such as a word that is the same in both languages, leave the key out of the results.`);
 	if (info.pluralCategories.length > 1) draft.notes.push(`${to} uses the plural categories ${info.pluralCategories.join(", ")}.`);
 	for (const hook of extra.hooks) hook(draft, {
@@ -2501,10 +2602,13 @@ function buildPrompt(project, kind, to, options, extra) {
 		const source = text(project.message(key, from)?.value) ?? "";
 		const translated = project.history(key, to);
 		const previous = translated && stale(key) ? text(project.valueAt(key, from, translated.updatedAt)) : void 0;
+		const values = relatedValues.get(key) ?? [];
 		return {
 			key,
 			source,
 			placeholders: [...new Set(syntaxes.flatMap((s) => s.find(source)).map((p) => p.text))],
+			description: descriptions.get(key),
+			related: values.length > 0 ? values : void 0,
 			existing: text(project.message(key, to)?.value) || void 0,
 			previousSource: previous === source ? void 0 : previous,
 			issues: reported.get(key)?.map((d) => ({
@@ -2553,6 +2657,8 @@ function renderItem(item, to) {
 		`- Source: ${JSON.stringify(item.source)}`
 	];
 	if (item.placeholders.length) out.push(`- Placeholders: ${item.placeholders.map((p) => `\`${p}\``).join(", ")}`);
+	if (item.description !== void 0) out.push(`- Description: ${JSON.stringify(item.description)}`);
+	for (const value of item.related ?? []) out.push(`- In ${value.locale}: ${JSON.stringify(value.value)}`);
 	if (item.previousSource !== void 0) out.push(`- Source when ${to} last changed: ${JSON.stringify(item.previousSource)}`);
 	if (item.existing !== void 0) out.push(`- Current ${to}: ${JSON.stringify(item.existing)}`);
 	for (const issue of item.issues ?? []) out.push(`- Reported: ${issue.message} (\`${issue.code}\`)`);
@@ -2584,6 +2690,80 @@ function renderPrompt(data) {
 	return out.join("\n");
 }
 //#endregion
+//#region src/project/unused.ts
+/**
+* True when a fully dynamic usage (`t(key)`) may reach `key`: the key lies in the usage's scope namespace and under its
+* scope key prefix. Undefined for a usage without a scope, which may reach any key.
+*/
+function scopeMatcher(usage, namespaced) {
+	const namespace = namespaced ? usage.scopeNamespace : void 0;
+	const prefix = usage.scopePrefix;
+	if (namespace === void 0 && !prefix) return void 0;
+	return (key) => {
+		const id = splitKey(key, namespaced);
+		if (namespace !== void 0 && id.namespace !== namespace) return false;
+		if (!prefix) return true;
+		const path = id.path.join(".");
+		return path === prefix || path.startsWith(`${prefix}.`);
+	};
+}
+function planUnusedDeletion(options, query = {}) {
+	const ignored = keyMatcher(options.ignoreKeys);
+	const match = query.glob ? keyMatcher([query.glob]) : void 0;
+	const candidates = [...options.unused].filter((key) => !ignored(key) && (match === void 0 || match(key)) && (query.namespace === void 0 || splitKey(key, options.namespaced).namespace === query.namespace)).sort();
+	const scoped = [];
+	const unscoped = [];
+	for (const usage of options.usages) {
+		if (usage.dynamic !== "unknown") continue;
+		const reaches = scopeMatcher(usage, options.namespaced);
+		if (reaches) scoped.push({
+			usage,
+			reaches
+		});
+		else unscoped.push(usage);
+	}
+	const keys = [];
+	const kept = [];
+	for (const key of candidates) {
+		const usages = scoped.filter((s) => s.reaches(key)).map((s) => s.usage);
+		if (usages.length > 0) {
+			kept.push({
+				key,
+				usages
+			});
+			continue;
+		}
+		keys.push({
+			key,
+			messages: options.locations(key).filter((node) => node.leaf).map((node) => ({
+				locale: node.locale,
+				path: node.path
+			}))
+		});
+	}
+	const plan = options.plan(keys.map(({ key }) => ({
+		type: "delete",
+		key,
+		locales: "all"
+	})));
+	if (unscoped.length === 0 || keys.length === 0) return {
+		plan,
+		keys,
+		kept
+	};
+	const files = [...new Set(unscoped.map((usage) => usage.path))].sort();
+	const shown = files.length > 5 ? `${files.slice(0, 5).join(", ")} and ${files.length - 5} more files` : files.join(", ");
+	const warning = `${unscoped.length} usage${unscoped.length === 1 ? " has" : "s have"} a fully dynamic key (in ${shown}) that may reach any key; list the keys they use in \`usage.keysInUse\` to keep them.`;
+	return {
+		plan: {
+			...plan,
+			warnings: [...plan.warnings, warning]
+		},
+		keys,
+		kept
+	};
+}
+//#endregion
 //#region src/project/project.ts
 const ioConcurrency = 64;
 async function forEachLimit(items, limit, fn) {
@@ -2725,7 +2905,8 @@ function createProject(options) {
 					format: candidate.format,
 					block: candidate.block,
 					readonly: candidate.readonly === true,
-					finder: finder.id
+					finder: finder.id,
+					keySeparator: candidate.keySeparator === config.keySeparator ? void 0 : candidate.keySeparator
 				});
 			}
 			finderResults.push({
@@ -2735,10 +2916,22 @@ function createProject(options) {
 		}
 		return out;
 	}
+	/** Namespace and key path of a stored path: each stored segment is split by the resource's key separator. */
+	function keyIdFor(resource, stored) {
+		const separator = keySeparatorOf(resource, config.keySeparator);
+		const logical = stored.flatMap((segment) => splitKeyPath(segment, separator));
+		if (namespaced) return {
+			namespace: resource.namespace ?? config.namespace.default,
+			path: logical
+		};
+		return {
+			namespace: void 0,
+			path: [...resource.namespace ? resource.namespace.split(".") : [], ...logical]
+		};
+	}
 	function keyFor(resource, stored) {
-		const logical = stored.flatMap((segment) => segment.split("."));
-		if (namespaced) return joinKey(resource.namespace ?? config.namespace.default, logical);
-		return joinKey(void 0, [...resource.namespace ? resource.namespace.split(".") : [], ...logical]);
+		const { namespace, path } = keyIdFor(resource, stored);
+		return joinKey(namespace, path, config.keySeparator);
 	}
 	/** Key path to stored path through the transforms that apply to a resource, last first. */
 	function storedPathOf(ctx) {
@@ -2756,7 +2949,8 @@ function createProject(options) {
 			format: format?.id ?? "unknown",
 			block: candidate.block,
 			readonly: candidate.readonly || !format || !format.edit && !format.serialize,
-			finder: candidate.finder
+			finder: candidate.finder,
+			...candidate.keySeparator === void 0 ? {} : { keySeparator: candidate.keySeparator }
 		};
 		const content = candidate.block ? text.slice(candidate.block.range.start, candidate.block.range.end) : text;
 		const offset = candidate.block?.range.start ?? 0;
@@ -2778,18 +2972,25 @@ function createProject(options) {
 			tree: {},
 			rawTree: {},
 			ranges: /* @__PURE__ */ new Map(),
+			descriptions: /* @__PURE__ */ new Map(),
 			error: errors.X18N2001({ path: candidate.path })
 		};
 		try {
 			const parsed = format.parse(content, ctx);
 			let tree = parsed.tree;
-			for (const transform of transforms) if (transform.applies?.(ctx) !== false) tree = transform.read(tree, ctx);
+			const descriptions = new Map(parsed.descriptions);
+			for (const transform of transforms) {
+				if (transform.applies?.(ctx) === false) continue;
+				tree = transform.read(tree, ctx);
+				for (const [id, description] of transform.describe?.(parsed.tree, ctx) ?? []) descriptions.set(id, description);
+			}
 			if (!isMessageTree(tree)) throw errors.X18N2003({ path: candidate.path });
 			return {
 				...base,
 				tree,
 				rawTree: parsed.tree,
 				ranges: parsed.ranges ?? /* @__PURE__ */ new Map(),
+				descriptions,
 				error: void 0
 			};
 		} catch (error) {
@@ -2803,6 +3004,7 @@ function createProject(options) {
 				tree: {},
 				rawTree: {},
 				ranges: /* @__PURE__ */ new Map(),
+				descriptions: /* @__PURE__ */ new Map(),
 				error: coded
 			};
 		}
@@ -2851,7 +3053,7 @@ function createProject(options) {
 			const id = candidate.block ? `${candidate.path}#${candidate.block.index}` : candidate.path;
 			const previous = resourceStates.get(id);
 			const content = candidate.block ? text.slice(candidate.block.range.start, candidate.block.range.end) : text;
-			if (previous && previous.hash === hashText(content) && previous.resource.locale === candidate.locale && previous.resource.namespace === candidate.namespace && previous.offset === (candidate.block?.range.start ?? 0)) next.set(id, previous);
+			if (previous && previous.hash === hashText(content) && previous.resource.locale === candidate.locale && previous.resource.namespace === candidate.namespace && previous.resource.keySeparator === candidate.keySeparator && previous.offset === (candidate.block?.range.start ?? 0)) next.set(id, previous);
 			else next.set(id, parseResource(candidate, text));
 		}
 		resourceStates.clear();
@@ -3002,24 +3204,17 @@ function createProject(options) {
 						messages.set(key, byLocale);
 						const list = byLocale.get(resource.locale) ?? [];
 						byLocale.set(resource.locale, list);
+						const description = state.descriptions.get(pathId(storedPath));
 						list.push({
 							key,
 							locale: resource.locale,
 							value: child,
 							resource: resource.id,
 							storedPath,
-							range
+							range,
+							...description === void 0 ? {} : { description }
 						});
-						if (!keyPaths.has(key)) {
-							const logical = path.flatMap((s) => s.split("."));
-							keyPaths.set(key, namespaced ? {
-								namespace: resource.namespace ?? config.namespace.default,
-								path: logical
-							} : {
-								namespace: void 0,
-								path: [...resource.namespace ? resource.namespace.split(".") : [], ...logical]
-							});
-						}
+						if (!keyPaths.has(key)) keyPaths.set(key, keyIdFor(resource, path));
 					} else {
 						parents.add(key);
 						visit(child, path);
@@ -3028,7 +3223,7 @@ function createProject(options) {
 			};
 			visit(state.tree, []);
 		}
-		for (const { namespace, path } of keyPaths.values()) for (let i = 1; i < path.length; i++) parents.add(joinKey(namespace, path.slice(0, i)));
+		for (const { namespace, path } of keyPaths.values()) for (let i = 1; i < path.length; i++) parents.add(joinKey(namespace, path.slice(0, i), config.keySeparator));
 		const derived = /* @__PURE__ */ new Map();
 		if (config.usage.derivedKeys.length > 0) for (const key of messages.keys()) for (const base of basesOf(key)) {
 			const list = derived.get(base) ?? [];
@@ -3116,7 +3311,7 @@ function createProject(options) {
 		}
 		if (query.prefix !== void 0) {
 			const prefix = query.prefix;
-			return [...usages.filter((usage) => inPath(usage) && usage.dynamic === false && usage.key !== void 0 && isKeyUnder(usage.key, prefix)).map((usage) => ({
+			return [...usages.filter((usage) => inPath(usage) && usage.dynamic === false && usage.key !== void 0 && isKeyUnder(usage.key, prefix, config.keySeparator)).map((usage) => ({
 				usage,
 				possible: false
 			})), ...prefixUsages.filter((usage) => inPath(usage) && usage.key !== void 0 && (usage.key.startsWith(prefix) || prefix.startsWith(usage.key))).map((usage) => ({
@@ -3168,7 +3363,7 @@ function createProject(options) {
 	});
 	function keys(query = {}) {
 		const { messages, keyPaths } = idx();
-		const match = query.glob ? keyMatcher([query.glob]) : void 0;
+		const match = query.glob ? keyMatcher([query.glob], config.keySeparator) : void 0;
 		let list = [...messages.keys()];
 		if (match) list = list.filter((key) => match(key));
 		if (query.namespace !== void 0) list = list.filter((key) => keyPaths.get(key)?.namespace === query.namespace);
@@ -3409,9 +3604,12 @@ function createProject(options) {
 		parseKey(input) {
 			const separator = config.namespace.separator;
 			if (!namespaced) return input;
-			if (input.indexOf(":") > 0) return input;
-			const custom = separator !== ":" ? input.indexOf(separator) : -1;
-			if (custom > 0) return `${input.slice(0, custom)}:${input.slice(custom + separator.length)}`;
+			const index = input.indexOf(":");
+			if (index > 0 && (separator !== false || [...resourceStates.values()].some((state) => state.resource.namespace === input.slice(0, index)))) return input;
+			if (separator !== ":" && separator !== false) {
+				const custom = input.indexOf(separator);
+				if (custom > 0) return `${input.slice(0, custom)}:${input.slice(custom + separator.length)}`;
+			}
 			return config.namespace.default ? `${config.namespace.default}:${input}` : input;
 		},
 		usages: usageMatches,
@@ -3453,6 +3651,7 @@ function createProject(options) {
 		},
 		prompt: (kind, locale, promptOptions = {}) => buildPrompt(project, kind, locale, promptOptions, {
 			config,
+			fallbacks,
 			hooks: registry.plugins.flatMap((plugin) => plugin.translatePrompt ? [plugin.translatePrompt] : [])
 		}),
 		explain,
@@ -3460,6 +3659,14 @@ function createProject(options) {
 		text: (path) => fileTexts.get(path) ?? files.get(path)?.text ?? (path === reviewFile ? reviewText : void 0),
 		owns: (path) => fileTexts.has(path) || files.has(path) || usageEligible(path),
 		plan: (ops) => planner.plan(ops),
+		planUnused: (query) => planUnusedDeletion({
+			unused: analyzer.analyze().unused,
+			usages: idx().usages,
+			namespaced,
+			ignoreKeys: config.ignoreKeys,
+			locations: (key) => project.locations(key),
+			plan: (ops) => planner.plan(ops)
+		}, query),
 		apply: (plan, applyOptions) => planner.apply(plan, applyOptions?.answers ?? {}),
 		update,
 		watch() {
@@ -3504,6 +3711,7 @@ function defaultDraft() {
 		resources: [],
 		formats: {},
 		keyStyle: "auto",
+		keySeparator: ".",
 		namespace: {
 			separator: ".",
 			default: void 0,
@@ -3593,6 +3801,10 @@ function applyLayer(draft, layer, origin, origins) {
 		draft.keyStyle = layer.keyStyle;
 		mark("keyStyle");
 	}
+	if (layer.keySeparator !== void 0) {
+		draft.keySeparator = layer.keySeparator;
+		mark("keySeparator");
+	}
 	if (layer.namespace !== void 0) {
 		draft.namespace = {
 			separator: layer.namespace.separator ?? draft.namespace.separator,
@@ -3828,4 +4040,4 @@ async function resolveConfig(options) {
 	};
 }
 //#endregion
-export { ConfigSchema, PluginFileSchema, ReviewFileSchema, applyMessageOps, applyTextEdits, buildTree, contractVersion, createLibraryPlugin, createLineIndex, createMemoryHost, createOverlayHost, createPlaceholderComparer, createProject, createRegistry, defineConfig, definePlugin, definePreset, diffText, envelope, errors, extensionOf, fuzzyScore, globToRegExp, hashText, isJsonObject, isKeyUnder, isMessageLeaf, isMessageTree, isPreset, isX18nError, joinKey, keyMatcher, localeSpellingKey, parseLocaleInfo, parseMessageBatch, pathId, pathMatcher, placeholderProblems, rangeContains, renderExplanation, renderPrompt, replaceKeyPrefix, resolveConfig, sortTree, splitKey, toErrorInfo, toWireDiagnostic, toWireRange, validate, walkLeaves };
+export { ConfigSchema, PluginFileSchema, ReviewFileSchema, applyMessageOps, applyTextEdits, buildTree, contractVersion, createLibraryPlugin, createLineIndex, createMemoryHost, createOverlayHost, createPlaceholderComparer, createProject, createRegistry, defineConfig, definePlugin, definePreset, diffText, envelope, errors, extensionOf, fuzzyScore, globToRegExp, hashText, isJsonObject, isKeyUnder, isMessageLeaf, isMessageTree, isPreset, isX18nError, joinKey, keyMatcher, localeSpellingKey, parseLocaleInfo, parseMessageBatch, pathId, pathMatcher, placeholderProblems, rangeContains, relatedLocales, renderExplanation, renderPrompt, replaceKeyPrefix, resolveConfig, sortTree, splitKey, toErrorInfo, toWireDiagnostic, toWireRange, validate, walkLeaves };