@x18n/core 0.0.10 → 0.0.13

package/dist/index.d.mts

@@ -196,6 +196,8 @@ interface LocaleInfo {
   readonly displayName: string | undefined;
   readonly flag: string | undefined;
   readonly pluralCategories: readonly Intl.LDMLPluralRule[];
+  /** Categories of ordinal numbers (1st, 2nd), which differ from the cardinal ones. */
+  readonly ordinalCategories: readonly Intl.LDMLPluralRule[];
 }
 /** Embedded resource inside a file, for example a Vue `<i18n>` block. */
 interface ResourceBlock {
@@ -237,6 +239,8 @@ interface Usage {
   readonly path: string;
   /** Range of the key text only (inside the quotes): the range rename rewrites. */
   readonly range: TextRange;
+  /** Range of the whole call that holds the key (`t('a', { n })`), when the scanner knows it. */
+  readonly expression: TextRange | undefined;
   readonly scanner: string;
   readonly kind: UsageKind;
   /** `t(`pages.${id}.title`)` gives 'prefix' with key `pages`. */
@@ -479,6 +483,8 @@ interface ScanContext {
 interface UsageCandidate {
   readonly raw: string;
   readonly range: TextRange;
+  /** Range of the whole call that holds the key, when the scanner knows it. */
+  readonly expression?: TextRange | undefined;
   readonly kind: UsageKind;
   readonly dynamic: false | "prefix" | "unknown";
   readonly namespace?: string | undefined;
@@ -571,10 +577,19 @@ interface HistoryProvider {
   /** Calls `onChange` when the history changes outside resource files, for example on a commit. */
   readonly watch?: ((ctx: HistoryContext, onChange: () => void) => Disposable) | undefined;
 }
+/** A key that is one plural form of a base key, such as `item_one` of `item`. */
+interface PluralForm {
+  readonly type: Intl.PluralRuleType;
+  readonly category: Intl.LDMLPluralRule;
+  /** The sibling key of another category. */
+  readonly keyOf: (category: Intl.LDMLPluralRule) => KeyString;
+}
 interface CheckContext {
   readonly config: ResolvedConfig;
   readonly sourceLocale: LocaleCode;
   readonly locales: readonly LocaleCode[];
+  /** The locales a locale falls back to, nearest first. Empty for a locale without a fallback. */
+  readonly fallbacks: (locale: LocaleCode) => readonly LocaleCode[];
   readonly resources: readonly Resource[];
   /** Options from `[severity, options]` in config. */
   readonly options: JsonObject;
@@ -585,6 +600,8 @@ interface CheckContext {
   readonly message: (key: KeyString, locale: LocaleCode) => Message | undefined;
   /** Every resource message of a key in a locale, more than one when duplicated across files. */
   readonly duplicates: (key: KeyString, locale: LocaleCode) => readonly Message[];
+  /** The plural form a key is, from the `{plural}` and `{ordinal}` derived-key rules. */
+  readonly formOf: (key: KeyString) => PluralForm | undefined;
   readonly usages: () => Iterable<Usage>;
   readonly coverage: () => readonly LocaleCoverage[];
   readonly unused: () => readonly KeyString[];
@@ -783,12 +800,14 @@ interface ExtractOptions {
   readonly keyMaxLength?: number | undefined;
   /** Reuse a key when the same text exists as a source value. Default true. */
   readonly reuseExisting?: boolean | undefined;
-  /** Strings or `/regex/` never extracted. */
+  /** Strings never extracted: an exact string such as `Elk`, or a `/regex/flags` string such as `/^v\d+/i` that matches the text. */
   readonly ignore?: readonly string[] | undefined;
-  /** Ignored strings per file glob. */
+  /** Strings never extracted in the files of a glob, written as in `ignore`. */
   readonly ignoreByFile?: {
     readonly [glob: string]: readonly string[];
   } | undefined;
+  /** Attribute names whose values are text, on top of those whose last word is `title`, `label`, `text`, `placeholder`, `alt`, `content`, `description`, `message` and the like. Markup attributes outside this set are never extracted. */
+  readonly attributes?: readonly string[] | undefined;
   readonly ignoreAttributes?: readonly string[] | undefined;
   readonly ignoreCallees?: readonly string[] | undefined;
   readonly templates?: readonly (string | ExtractTemplate)[] | undefined;
@@ -802,7 +821,7 @@ interface UsageOptions {
   readonly ignoreCallees?: readonly string[] | undefined;
   /** Keys (globs) that count as used, for example keys built at runtime. */
   readonly keysInUse?: readonly string[] | undefined;
-  /** Rules like `{key}_plural`: when `{key}` is used the derived keys count as used. */
+  /** Rules like `{key}_plural`: when `{key}` is used the derived keys count as used. Rules apply repeatedly, so with `{key}_*` the key `a_b_c` derives from both `a_b` and `a`. `*` matches one key segment. `{plural}` and `{ordinal}` match a plural or ordinal category (`one`, `few`, `other`): each locale then needs the categories of its own language, and categories the language lacks are optional. */
   readonly derivedKeys?: readonly string[] | undefined;
 }
 interface WriteOptions {
@@ -832,6 +851,10 @@ interface SerializableConfig {
   /** Locale codes as written in paths. Filters the found locales. */
   readonly locales?: readonly string[] | undefined;
   readonly ignoreLocales?: readonly string[] | undefined;
+  /** Locale to the locale it falls back to, such as `{ 'en-GB': 'en' }`. A locale with a fallback holds only overrides: a key it lacks or leaves empty is not missing when the fallback chain has it. `'auto'` falls back to the nearest parent language that exists: `en-US` to `en`, `zh-Hant-TW` to `zh-Hant` or `zh`. */
+  readonly localeFallbacks?: "auto" | {
+    readonly [locale: string]: string;
+  } | undefined;
   /** `'auto'` detects built-in presets from the project's dependencies. */
   readonly presets?: "auto" | readonly PluginSpecifier[] | undefined;
   readonly plugins?: readonly PluginSpecifier[] | undefined;
@@ -892,6 +915,9 @@ interface ResolvedConfig {
   readonly sourceLocale: string;
   readonly locales: readonly string[] | undefined;
   readonly ignoreLocales: readonly string[];
+  readonly localeFallbacks: "auto" | {
+    readonly [locale: string]: string;
+  };
   readonly resources: readonly ResourceSpec[];
   readonly formats: {
     readonly [extension: string]: string;
@@ -1447,4 +1473,4 @@ export declare function rangeContains(range: TextRange, offset: number): boolean
 /** Fast non-cryptographic string hash (cyrb53), as hex. */
 export declare function hashText(text: string): string;
 //#endregion
-export type { Analysis, Answers, ApplyResult, ArgSource, Builtins, CacheStore, CallSpec, CapabilityConflict, Check, CheckContext, CheckIds, CheckLevel, CheckSetting, ConfigContext, ConfigDraft, ConfigOrigin, CreateProjectOptions, Decision, DecisionOption, DetectContext, Diagnostic, DiagnosticInput, Disposable, EditOp, Envelope, ErrorCode, ErrorInfo, ExtractItem, ExtractOptions, ExtractTemplate, Extractor, FileChange, FileEvent, FileScan, FinderContext, Fix, Format, FormatContext, GlobOptions, GlossaryEntry, HardString, HistoryConfigs, HistoryContext, HistoryOptions, HistoryProvider, HistorySettings, Host, JsonObject, JsonPrimitive, JsonValue, KeyContext, KeyId, KeyInfo, KeyQuery, KeyString, KeyTarget, LineIndex, LinePosition, LocaleCode, LocaleCoverage, LocaleFinder, LocaleInfo, Location, Logger, ManifestReader, MemoryHost, Message, MessageChange, MessageHistory, MessageLeaf, MessageOp, MessageTree, NamespaceFromPath, NamespaceOptions, NodeRange, OverlayHost, ParseResult, Placeholder, PlaceholderComparer, PlaceholderProblem, PlaceholderSyntax, Plan, Plugin, PluginConfigs, PluginFile, PluginOption, PluginRegistry, PluginSpecifier, Preset, PresetExplanation, PresetFactory, PresetOption, Project, ProjectChange, ProjectExplanation, PromptContext, PromptData, PromptDraft, PromptItem, PromptOptions, RegexScannerSpec, ReportInput, ReportSummary, Reporter, ReporterContext, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ScanContext, ScanResult, Scanner, SchemaIssue, Scope, SerializableConfig, Setup, Severity, SourceFile, TextEdit, TextRange, TreeLeaf, Usage, UsageCandidate, UsageContext, UsageKind, UsageMatch, UsageOptions, UsageQuery, UserConfig, WireDiagnostic, WireRange, WriteOptions, X18nError };
+export type { Analysis, Answers, ApplyResult, ArgSource, Builtins, CacheStore, CallSpec, CapabilityConflict, Check, CheckContext, CheckIds, CheckLevel, CheckSetting, ConfigContext, ConfigDraft, ConfigOrigin, CreateProjectOptions, Decision, DecisionOption, DetectContext, Diagnostic, DiagnosticInput, Disposable, EditOp, Envelope, ErrorCode, ErrorInfo, ExtractItem, ExtractOptions, ExtractTemplate, Extractor, FileChange, FileEvent, FileScan, FinderContext, Fix, Format, FormatContext, GlobOptions, GlossaryEntry, HardString, HistoryConfigs, HistoryContext, HistoryOptions, HistoryProvider, HistorySettings, Host, JsonObject, JsonPrimitive, JsonValue, KeyContext, KeyId, KeyInfo, KeyQuery, KeyString, KeyTarget, LineIndex, LinePosition, LocaleCode, LocaleCoverage, LocaleFinder, LocaleInfo, Location, Logger, ManifestReader, MemoryHost, Message, MessageChange, MessageHistory, MessageLeaf, MessageOp, MessageTree, NamespaceFromPath, NamespaceOptions, NodeRange, OverlayHost, ParseResult, Placeholder, PlaceholderComparer, PlaceholderProblem, PlaceholderSyntax, Plan, Plugin, PluginConfigs, PluginFile, PluginOption, PluginRegistry, PluginSpecifier, PluralForm, Preset, PresetExplanation, PresetFactory, PresetOption, Project, ProjectChange, ProjectExplanation, PromptContext, PromptData, PromptDraft, PromptItem, PromptOptions, RegexScannerSpec, ReportInput, ReportSummary, Reporter, ReporterContext, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ScanContext, ScanResult, Scanner, SchemaIssue, Scope, SerializableConfig, Setup, Severity, SourceFile, TextEdit, TextRange, TreeLeaf, Usage, UsageCandidate, UsageContext, UsageKind, UsageMatch, UsageOptions, UsageQuery, UserConfig, WireDiagnostic, WireRange, WriteOptions, X18nError };

package/dist/index.mjs

@@ -363,6 +363,28 @@ const defaultRegions = {
 	vi: "VN",
 	zh: "CN"
 };
+/** The fallback of each locale: from the config map, or for `'auto'` the nearest parent language among `locales`. The source locale has none. */
+function resolveFallbacks(setting, locales, sourceLocale) {
+	if (setting !== "auto") return Object.fromEntries(Object.entries(setting).filter(([locale]) => locale !== sourceLocale));
+	const fallbacks = {};
+	for (const locale of locales) {
+		if (locale === sourceLocale) continue;
+		for (let cut = locale.search(/[-_][^-_]*$/); cut > 0; cut = locale.slice(0, cut).search(/[-_][^-_]*$/)) {
+			const parent = locales.find((code) => code === locale.slice(0, cut));
+			if (parent) {
+				fallbacks[locale] = parent;
+				break;
+			}
+		}
+	}
+	return fallbacks;
+}
+/** The locales a locale falls back to, nearest first. Stops at a cycle. */
+function fallbackChain(fallbacks, locale) {
+	const chain = [];
+	for (let next = fallbacks[locale]; next !== void 0 && next !== locale && !chain.includes(next); next = fallbacks[next]) chain.push(next);
+	return chain;
+}
 const pluralOrder = [
 	"zero",
 	"one",
@@ -396,8 +418,10 @@ function parseLocaleInfo(code) {
 		region
 	].filter(Boolean).join("-");
 	const displayName = language ? safe(() => new Intl.DisplayNames(["en"], { type: "language" }).of(tag)) : void 0;
-	const found = language ? safe(() => new Intl.PluralRules(tag).resolvedOptions().pluralCategories) : void 0;
-	const pluralCategories = found ? pluralOrder.filter((category) => found.includes(category)) : ["other"];
+	const categories = (type) => {
+		const found = language ? safe(() => new Intl.PluralRules(tag, { type }).resolvedOptions().pluralCategories) : void 0;
+		return found ? pluralOrder.filter((category) => found.includes(category)) : ["other"];
+	};
 	const flagRegion = region ?? (language === "zh" && script === "Hant" ? "TW" : language ? defaultRegions[language] : void 0);
 	return {
 		code,
@@ -405,7 +429,8 @@ function parseLocaleInfo(code) {
 		region,
 		displayName,
 		flag: flagRegion ? flagOf(flagRegion) : void 0,
-		pluralCategories
+		pluralCategories: categories("cardinal"),
+		ordinalCategories: categories("ordinal")
 	};
 }
 /** Codes that differ only in spelling (`zh_CN` and `zh-cn`), the same after a lenient normalization. */
@@ -684,6 +709,7 @@ const extractOptions = v.strictObject({
 	reuseExisting: v.optional(v.boolean()),
 	ignore: v.optional(strings),
 	ignoreByFile: v.optional(v.record(v.string(), strings)),
+	attributes: v.optional(strings),
 	ignoreAttributes: v.optional(strings),
 	ignoreCallees: v.optional(strings),
 	templates: v.optional(extractTemplates)
@@ -712,6 +738,7 @@ const ConfigSchema = v.strictObject({
 	sourceLocale: v.optional(v.string()),
 	locales: v.optional(strings),
 	ignoreLocales: v.optional(strings),
+	localeFallbacks: v.optional(v.union([v.literal("auto"), v.record(v.string(), v.string())])),
 	presets: v.optional(v.union([v.literal("auto"), v.array(pluginSpecifier)])),
 	plugins: v.optional(v.array(pluginSpecifier)),
 	resources: v.optional(v.array(resourceSpec)),
@@ -915,6 +942,148 @@ function createHistory(input) {
 	};
 }
 //#endregion
+//#region src/project/usages.ts
+function innermost(scopes, range) {
+	let best;
+	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 createUsageResolver(config, namespaced, normalizers) {
+	const separator = config.namespace.separator;
+	return { resolve(candidate, scopes, path, scanner) {
+		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;
+			}
+		}
+		const scopeNamespace = candidate.namespace ?? scope?.namespace;
+		const scopePrefix = candidate.keyPrefix ?? scope?.keyPrefix;
+		let namespace;
+		let explicit = false;
+		if (namespaced) {
+			const index = text.indexOf(separator);
+			explicit = index > 0;
+			if (explicit) {
+				namespace = text.slice(0, index);
+				text = text.slice(index + separator.length);
+			} else namespace = scopeNamespace ?? config.namespace.default;
+		}
+		if (scopePrefix && !explicit) text = text ? `${scopePrefix}.${text}` : scopePrefix;
+		let key;
+		if (candidate.dynamic === "unknown") key = void 0;
+		else key = joinKey(namespace, text === "" ? [] : text.split("."));
+		return {
+			key,
+			raw: candidate.raw,
+			path,
+			range: candidate.range,
+			expression: candidate.expression,
+			scanner,
+			kind: candidate.kind,
+			dynamic: candidate.dynamic,
+			locale: candidate.locale,
+			scopeNamespace,
+			scopePrefix
+		};
+	} };
+}
+/** True when a prefix usage may refer to `key`. The key of `t(`pages.${id}`)` is `pages.`, so only children match. */
+function prefixMatches(usage, key) {
+	return usage.dynamic === "prefix" && usage.key !== void 0 && key.startsWith(usage.key);
+}
+/** Ranges covered by `x18n-disable-next-line` and `x18n-disable` ... `x18n-enable` comments. */
+function suppressedRanges(text) {
+	if (!text.includes("x18n-disable")) return [];
+	const ranges = [];
+	for (const match of text.matchAll(/x18n-disable-next-line/g)) {
+		const lineEnd = text.indexOf("\n", match.index);
+		if (lineEnd === -1) continue;
+		const nextEnd = text.indexOf("\n", lineEnd + 1);
+		ranges.push({
+			start: lineEnd + 1,
+			end: nextEnd === -1 ? text.length : nextEnd
+		});
+	}
+	for (const match of text.matchAll(/x18n-disable(?![-\w])/g)) {
+		const end = text.indexOf("x18n-enable", match.index);
+		ranges.push({
+			start: match.index,
+			end: end === -1 ? text.length : end
+		});
+	}
+	return ranges;
+}
+/** The plural categories of a locale's language: Japanese has only `other`. */
+function categoriesOf(info, type) {
+	return type === "ordinal" ? info.ordinalCategories : info.pluralCategories;
+}
+const tokens = /(\{key\}|\{plural\}|\{ordinal\}|\*)/;
+const categories = [
+	"zero",
+	"one",
+	"two",
+	"few",
+	"many",
+	"other"
+];
+/**
+* Compiles derived-key rules (`{key}_plural`, `{key}_*`, `{key}_{plural}`). `*` is any key segment;
+* `{plural}` and `{ordinal}` are CLDR plural categories, which each locale needs its own set of.
+*/
+function derivedKeys(rules) {
+	const compiled = rules.map((rule) => {
+		const parts = rule.split(tokens);
+		const type = parts.includes("{ordinal}") ? "ordinal" : parts.includes("{plural}") ? "cardinal" : void 0;
+		const source = parts.map((part) => {
+			if (part === "{key}") return "(?<key>.+)";
+			if (part === "{plural}" || part === "{ordinal}") return `(?<category>${categories.join("|")})`;
+			if (part === "*") return "[^.:]+";
+			return part.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+		}).join("");
+		return {
+			type,
+			re: new RegExp(`^${source}$`, "d")
+		};
+	});
+	const baseOf = (key) => {
+		for (const { re } of compiled) {
+			const base = re.exec(key)?.groups?.key;
+			if (base) return base;
+		}
+	};
+	return {
+		basesOf(key) {
+			const bases = [];
+			for (let base = baseOf(key); base !== void 0; base = baseOf(base)) bases.push(base);
+			return bases;
+		},
+		formOf(key) {
+			let best;
+			for (const { type, re } of compiled) {
+				const match = type && re.exec(key);
+				if (!type || !match) continue;
+				const base = match.groups?.key;
+				const category = categories.find((c) => c === match.groups?.category);
+				const at = match.indices?.groups?.category;
+				if (!base || !category || !at || best && best.base.length <= base.length) continue;
+				const [start, end] = at;
+				best = {
+					base,
+					type,
+					category,
+					keyOf: (other) => `${key.slice(0, start)}${other}${key.slice(end)}`
+				};
+			}
+			return best;
+		}
+	};
+}
+//#endregion
 //#region src/project/analysis.ts
 function levelOf(setting) {
 	if (setting === void 0) return void 0;
@@ -927,17 +1096,38 @@ function levelOf(setting) {
 		options: setting[1]
 	};
 }
-function computeCoverage(state, reference) {
+/**
+* The keys a locale needs: the reference keys, with plural forms swapped for the categories of the locale's
+* language. Forms the language lacks (`item_zero` in English) count only where they exist.
+*/
+function expectedKeys(state, options, reference, locale) {
+	const info = options.localeInfo(locale);
+	const keys = /* @__PURE__ */ new Set();
+	for (const key of reference) {
+		const form = options.formOf(key);
+		if (!form || state.messages.get(key)?.has(locale)) keys.add(key);
+		form && categoriesOf(info, form.type).forEach((category) => keys.add(form.keyOf(category)));
+	}
+	return [...keys].sort();
+}
+function computeCoverage(state, options, sourceKeys) {
 	const { messages, sourceLocale } = state;
 	return state.locales.map((locale) => {
+		const reference = expectedKeys(state, options, sourceKeys, locale);
+		const chain = fallbackChain(state.fallbacks, locale);
+		const inherited = (key) => chain.some((code) => {
+			const value = messages.get(key)?.get(code)?.[0]?.value;
+			return value !== void 0 && value !== "";
+		});
 		const missing = [];
 		const empty = [];
 		const outdated = [];
 		for (const key of reference) {
 			const value = messages.get(key)?.get(locale)?.[0]?.value;
-			if (value === void 0) missing.push(key);
-			else if (value === "") empty.push(key);
-			else if (locale !== sourceLocale && isOutdated(state.history(key, sourceLocale), state.history(key, locale))) outdated.push(key);
+			if (value === void 0 || value === "") {
+				if (inherited(key)) continue;
+				(value === void 0 ? missing : empty).push(key);
+			} else if (locale !== sourceLocale && isOutdated(state.history(key, sourceLocale), state.history(key, locale))) outdated.push(key);
 		}
 		return {
 			locale,
@@ -978,7 +1168,7 @@ function* runCheck(check, level, inputs, input) {
 		const severity = config.strict && (item.severity ?? level) === "warning" ? "error" : item.severity ?? level;
 		let location = item.location;
 		if (!location && item.key !== void 0) {
-			const byLocale = state.messages.get(item.key);
+			const byLocale = state.messages.get(item.key) ?? state.messages.get(input.ctx.formOf(item.key)?.keyOf("other") ?? item.key);
 			const found = byLocale?.get(item.locale ?? state.sourceLocale)?.[0] ?? byLocale?.get(state.sourceLocale)?.[0];
 			if (found) location = {
 				path: resourcePath(found.resource),
@@ -1038,7 +1228,7 @@ function createAnalyzer(options) {
 		const { sourceLocale, locales, messages } = state;
 		const sourceKeys = [...messages.keys()].filter((key) => messages.get(key)?.has(sourceLocale)).sort();
 		const allKeys = [...messages.keys()].sort();
-		const coverage = computeCoverage(state, sourceKeys.length > 0 ? sourceKeys : allKeys);
+		const coverage = computeCoverage(state, options, sourceKeys.length > 0 ? sourceKeys : allKeys);
 		const isDefined = (key) => messages.get(key)?.has(sourceLocale) === true || state.parents.has(key) || (state.derived.get(key)?.length ?? 0) > 0 || sourceKeys.length === 0 && messages.has(key);
 		const hasScanners = state.files.size > 0;
 		const referenceSyntaxes = registry.placeholders.filter((syntax) => syntax.reference);
@@ -1050,8 +1240,7 @@ function createAnalyzer(options) {
 		const prefixes = [...new Set(state.prefixUsages.flatMap((usage) => usage.key === void 0 ? [] : [usage.key]))];
 		const isUsed = (key) => {
 			if (state.usagesByKey.has(key) || inUse(key) || referenced.has(key)) return true;
-			const base = options.baseOf(key);
-			if (base !== void 0 && (state.usagesByKey.has(base) || inUse(base))) return true;
+			if (options.basesOf(key).some((base) => state.usagesByKey.has(base) || inUse(base))) return true;
 			return prefixes.some((prefix) => key.startsWith(prefix));
 		};
 		const unused = hasScanners ? allKeys.filter((key) => !isUsed(key)) : [];
@@ -1069,6 +1258,7 @@ function createAnalyzer(options) {
 			config,
 			sourceLocale,
 			locales,
+			fallbacks: (locale) => fallbackChain(state.fallbacks, locale),
 			resources: state.resources.map((s) => s.resource),
 			hasScanners,
 			keys: () => allKeys,
@@ -1077,6 +1267,7 @@ function createAnalyzer(options) {
 			},
 			message: (key, locale) => messages.get(key)?.get(locale)?.[0],
 			duplicates: (key, locale) => messages.get(key)?.get(locale) ?? [],
+			formOf: options.formOf,
 			usages: () => state.usages,
 			coverage: () => coverage,
 			unused: () => unused,
@@ -1497,7 +1688,7 @@ var PlanBuilder = class {
 		const all = this.options.allKeys();
 		const isLeaf = this.options.messages(op.from) !== void 0;
 		const under = all.filter((key) => isKeyUnder(key, op.from));
-		const derived = all.filter((key) => this.options.baseOf(key) === op.from);
+		const derived = all.filter((key) => this.options.basesOf(key).includes(op.from));
 		let keys;
 		if (op.type === "rename-prefix") keys = under;
 		else if (isLeaf) keys = [op.from, ...derived];
@@ -1543,7 +1734,7 @@ var PlanBuilder = class {
 			case "set":
 				this.setValue(op.key, op.locale, op.value);
 				if (this.config.write.keepFilled) {
-					for (const locale of this.state.locales) if (locale !== op.locale && !this.options.message(op.key, locale)) this.setValue(op.key, locale, "");
+					for (const locale of this.state.locales) if (locale !== op.locale && !this.state.fallbacks[locale] && !this.options.message(op.key, locale)) this.setValue(op.key, locale, "");
 				}
 				break;
 			case "delete":
@@ -1889,95 +2080,6 @@ function renderPrompt(data) {
 	return out.join("\n");
 }
 //#endregion
-//#region src/project/usages.ts
-function innermost(scopes, range) {
-	let best;
-	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 createUsageResolver(config, namespaced, normalizers) {
-	const separator = config.namespace.separator;
-	return { resolve(candidate, scopes, path, scanner) {
-		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;
-			}
-		}
-		const scopeNamespace = candidate.namespace ?? scope?.namespace;
-		const scopePrefix = candidate.keyPrefix ?? scope?.keyPrefix;
-		let namespace;
-		let explicit = false;
-		if (namespaced) {
-			const index = text.indexOf(separator);
-			explicit = index > 0;
-			if (explicit) {
-				namespace = text.slice(0, index);
-				text = text.slice(index + separator.length);
-			} else namespace = scopeNamespace ?? config.namespace.default;
-		}
-		if (scopePrefix && !explicit) text = text ? `${scopePrefix}.${text}` : scopePrefix;
-		let key;
-		if (candidate.dynamic === "unknown") key = void 0;
-		else key = joinKey(namespace, text === "" ? [] : text.split("."));
-		return {
-			key,
-			raw: candidate.raw,
-			path,
-			range: candidate.range,
-			scanner,
-			kind: candidate.kind,
-			dynamic: candidate.dynamic,
-			locale: candidate.locale,
-			scopeNamespace,
-			scopePrefix
-		};
-	} };
-}
-/** True when a prefix usage may refer to `key`. The key of `t(`pages.${id}`)` is `pages.`, so only children match. */
-function prefixMatches(usage, key) {
-	return usage.dynamic === "prefix" && usage.key !== void 0 && key.startsWith(usage.key);
-}
-/** Ranges covered by `x18n-disable-next-line` and `x18n-disable` ... `x18n-enable` comments. */
-function suppressedRanges(text) {
-	if (!text.includes("x18n-disable")) return [];
-	const ranges = [];
-	for (const match of text.matchAll(/x18n-disable-next-line/g)) {
-		const lineEnd = text.indexOf("\n", match.index);
-		if (lineEnd === -1) continue;
-		const nextEnd = text.indexOf("\n", lineEnd + 1);
-		ranges.push({
-			start: lineEnd + 1,
-			end: nextEnd === -1 ? text.length : nextEnd
-		});
-	}
-	for (const match of text.matchAll(/x18n-disable(?![-\w])/g)) {
-		const end = text.indexOf("x18n-enable", match.index);
-		ranges.push({
-			start: match.index,
-			end: end === -1 ? text.length : end
-		});
-	}
-	return ranges;
-}
-/** Compiles derived-key rules (`{key}_plural`, `{key}_*`) into a function from a key to its base key. */
-function derivedBase(rules) {
-	const regexes = rules.map((rule) => {
-		const source = rule.split("{key}").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^.:]+")).join("(.+)");
-		return new RegExp(`^${source}$`);
-	});
-	return (key) => {
-		for (const re of regexes) {
-			const match = re.exec(key);
-			if (match?.[1]) return match[1];
-		}
-	};
-}
-//#endregion
 //#region src/project/project.ts
 const scanConcurrency = 64;
 function createProject(options) {
@@ -1993,6 +2095,7 @@ function createProject(options) {
 	let revision = 0;
 	let namespaced = false;
 	let locales = [];
+	let fallbacks = {};
 	let sourceLocale = config.sourceLocale;
 	let resolver;
 	let watcher;
@@ -2002,7 +2105,7 @@ function createProject(options) {
 	const normalizers = registry.plugins.flatMap((plugin) => plugin.normalizeKey ? [plugin.normalizeKey] : []);
 	const transforms = registry.plugins.flatMap((plugin) => plugin.transformResource ? [plugin.transformResource] : []);
 	const localeInfoHooks = registry.plugins.flatMap((plugin) => plugin.localeInfo ? [plugin.localeInfo] : []);
-	const baseOf = derivedBase(config.usage.derivedKeys);
+	const { basesOf, formOf } = derivedKeys(config.usage.derivedKeys);
 	const scanSignature = hashText(JSON.stringify({
 		usage: config.usage,
 		namespace: config.namespace,
@@ -2030,6 +2133,11 @@ function createProject(options) {
 		}
 		return info;
 	}
+	/** Whether `locale` needs `key`: not a plural form of a category its language lacks. */
+	function needs(key, locale) {
+		const form = formOf(key);
+		return !form || categoriesOf(localeInfo(locale), form.type).includes(form.category);
+	}
 	async function discover() {
 		const ctx = {
 			host,
@@ -2184,6 +2292,7 @@ function createProject(options) {
 		if (!found.includes(sourceLocale) && config.origins.sourceLocale === void 0 && found.length > 0) sourceLocale = found.find((code) => code.toLowerCase().startsWith("en")) ?? [...found].sort()[0];
 		locales = [sourceLocale, ...found.filter((code) => code !== sourceLocale).sort()];
 		if (!found.includes(sourceLocale) && found.length === 0) locales = [sourceLocale];
+		fallbacks = resolveFallbacks(config.localeFallbacks, locales, sourceLocale);
 		resolver = createUsageResolver(config, namespaced, normalizers);
 		resolved = /* @__PURE__ */ new WeakMap();
 		resourceIndex = void 0;
@@ -2347,13 +2456,10 @@ function createProject(options) {
 		}
 		for (const { namespace, path } of keyPaths.values()) for (let i = 1; i < path.length; i++) parents.add(joinKey(namespace, path.slice(0, i)));
 		const derived = /* @__PURE__ */ new Map();
-		if (config.usage.derivedKeys.length > 0) for (const key of messages.keys()) {
-			const base = baseOf(key);
-			if (base) {
-				const list = derived.get(base) ?? [];
-				derived.set(base, list);
-				list.push(key);
-			}
+		if (config.usage.derivedKeys.length > 0) for (const key of messages.keys()) for (const base of basesOf(key)) {
+			const list = derived.get(base) ?? [];
+			derived.set(base, list);
+			list.push(key);
 		}
 		return {
 			messages,
@@ -2425,8 +2531,7 @@ function createProject(options) {
 		const inPath = (usage) => query.path === void 0 || usage.path === query.path;
 		if (query.key !== void 0) {
 			const key = query.key;
-			const base = baseOf(key);
-			return [...[...usagesByKey.get(key) ?? [], ...base ? usagesByKey.get(base) ?? [] : []].filter(inPath).map((usage) => ({
+			return [...[key, ...basesOf(key)].flatMap((k) => usagesByKey.get(k) ?? []).filter(inPath).map((usage) => ({
 				usage,
 				possible: false
 			})), ...prefixUsages.filter((usage) => inPath(usage) && prefixMatches(usage, key)).map((usage) => ({
@@ -2456,6 +2561,7 @@ function createProject(options) {
 			revision,
 			sourceLocale,
 			locales,
+			fallbacks,
 			resources: [...resourceStates.values()],
 			resourceErrors: [...resourceStates.values()].flatMap((s) => s.error ? [{
 				error: s.error,
@@ -2475,7 +2581,8 @@ function createProject(options) {
 			files,
 			history: history.get
 		}),
-		baseOf,
+		basesOf,
+		formOf,
 		localeInfo,
 		text: (path) => fileTexts.get(path) ?? files.get(path)?.text
 	});
@@ -2489,7 +2596,7 @@ function createProject(options) {
 			const locale = query.missing;
 			list = list.filter((key) => {
 				const value = message(key, locale)?.value;
-				return message(key, sourceLocale) !== void 0 && (value === void 0 || value === "");
+				return message(key, sourceLocale) !== void 0 && (value === void 0 || value === "") && needs(key, locale);
 			});
 		}
 		if (query.unused) {
@@ -2509,7 +2616,7 @@ function createProject(options) {
 			namespace: id.namespace,
 			path: id.path,
 			messages: list,
-			missing: locales.filter((locale) => !byLocale.has(locale)),
+			missing: locales.filter((locale) => !byLocale.has(locale) && needs(key, locale)),
 			usages: usageMatches({ key }),
 			diagnostics: analyzer.analyze().diagnostics.filter((d) => d.key === key)
 		};
@@ -2630,6 +2737,7 @@ function createProject(options) {
 			revision,
 			sourceLocale,
 			locales,
+			fallbacks,
 			namespaced,
 			resources: [...resourceStates.values()],
 			fileTexts
@@ -2640,7 +2748,7 @@ function createProject(options) {
 		parents: () => idx().parents,
 		usageMatches,
 		text: (path) => fileTexts.get(path) ?? files.get(path)?.text,
-		baseOf,
+		basesOf,
 		toStored: (target, path) => storedPathOf(target)(path),
 		resolveNew(locale, namespace) {
 			const ctx = {
@@ -2714,7 +2822,7 @@ function createProject(options) {
 		lookup(key, locale) {
 			const exact = message(key, locale);
 			if (exact) return exact;
-			const derived = [...idx().derived.get(key) ?? []].sort();
+			const derived = (idx().derived.get(key) ?? []).filter((k) => message(k, locale) !== void 0).sort((a, b) => a.length - b.length || a.localeCompare(b));
 			const other = derived.find((k) => /[._-]other$/.test(k)) ?? derived[0];
 			return other === void 0 ? void 0 : message(other, locale);
 		},
@@ -2779,6 +2887,7 @@ function defaultDraft() {
 		sourceLocale: "en",
 		locales: void 0,
 		ignoreLocales: [],
+		localeFallbacks: {},
 		resources: [],
 		formats: {},
 		keyStyle: "auto",
@@ -2822,6 +2931,12 @@ function serializablePart(config) {
 		history: options
 	};
 }
+function mergeFallbacks(base, layer) {
+	return base === "auto" || layer === "auto" ? layer : {
+		...base,
+		...layer
+	};
+}
 /** Applies a user config layer: scalars replace, lists of rules append. */
 function applyLayer(draft, layer, origin, origins) {
 	const mark = (key) => {
@@ -2839,6 +2954,10 @@ function applyLayer(draft, layer, origin, origins) {
 		draft.ignoreLocales = [...draft.ignoreLocales, ...layer.ignoreLocales];
 		mark("ignoreLocales");
 	}
+	if (layer.localeFallbacks !== void 0) {
+		draft.localeFallbacks = mergeFallbacks(draft.localeFallbacks, layer.localeFallbacks);
+		mark("localeFallbacks");
+	}
 	if (layer.resources !== void 0) {
 		draft.resources = layer.resources;
 		mark("resources");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/core",
   "type": "module",
-  "version": "0.0.10",
+  "version": "0.0.13",
   "description": "Runtime-neutral engine of x18n: domain model, plugin API and project analysis",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",

package/schema/config.json

@@ -25,6 +25,22 @@
         "type": "string"
       }
     },
+    "localeFallbacks": {
+      "anyOf": [
+        {
+          "const": "auto"
+        },
+        {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      ]
+    },
     "presets": {
       "anyOf": [
         {
@@ -388,6 +404,12 @@
             }
           }
         },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
         "ignoreAttributes": {
           "type": "array",
           "items": {