@x18n/core 0.0.12 → 0.0.14

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`. */
@@ -430,10 +434,14 @@ interface LocaleFinder {
   readonly id: string;
   readonly override?: boolean | undefined;
   readonly find: (ctx: FinderContext) => Promise<readonly ResourceCandidate[]>;
-  /** Where a new resource for (locale, namespace) should go. Used by edits that create files. */
+  /**
+   * Where a new resource for (locale, namespace) should go. Used by edits that create files.
+   * `model` is the existing resource the new one would otherwise mirror: the key's source file when it has one.
+   */
   readonly resolveNew?: ((target: {
     readonly locale: LocaleCode;
     readonly namespace: string | undefined;
+    readonly model: Resource | undefined;
   }, ctx: FinderContext) => string | undefined) | undefined;
 }
 interface FormatContext {
@@ -455,6 +463,28 @@ type MessageOp = {
   readonly type: "delete";
   readonly path: readonly string[];
 };
+/** A built-in format known by its extensions only: the module behind `load` is imported when a file of that format is read. */
+interface FormatEntry {
+  /** File extensions without the dot. */
+  readonly extensions: readonly string[];
+  /** The module's default export creates a plugin that holds the format. */
+  readonly load: PluginLoader;
+}
+/** A format entry under its id, as plugins list it. */
+interface LazyFormat extends FormatEntry {
+  readonly id: string;
+}
+/** A built-in scanner known by its extensions only: the module behind `load` is imported when a file it scans is first scanned. */
+interface ScannerEntry {
+  /** File extensions without dot. `*` matches every file. */
+  readonly extensions: readonly string[];
+  /** The module's default export creates a plugin that holds the scanner. */
+  readonly load: PluginLoader;
+}
+/** A scanner entry under its id, as plugins list it. */
+interface LazyScanner extends ScannerEntry {
+  readonly id: string;
+}
 interface Format {
   readonly id: string;
   /** File extensions without the dot. */
@@ -479,6 +509,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;
@@ -490,6 +522,8 @@ interface Scope {
   readonly range: TextRange;
   readonly namespace?: string | undefined;
   readonly keyPrefix?: string | undefined;
+  /** The key prefix applies only to keys it defines; others resolve without it, as page messages that extend global ones. */
+  readonly optionalPrefix?: boolean | undefined;
 }
 interface HardString {
   readonly text: string;
@@ -571,6 +605,13 @@ 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;
@@ -587,6 +628,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[];
@@ -688,6 +731,10 @@ interface Plugin {
   readonly manifests?: readonly ManifestReader[] | undefined;
   readonly localeFinders?: readonly LocaleFinder[] | undefined;
   readonly formats?: readonly Format[] | undefined;
+  /** Formats that load their module when a file of that format is first read. */
+  readonly lazyFormats?: readonly LazyFormat[] | undefined;
+  /** Scanners that load their module when a file they scan is first scanned. */
+  readonly lazyScanners?: readonly LazyScanner[] | undefined;
   readonly scanners?: readonly Scanner[] | undefined;
   readonly extractors?: readonly Extractor[] | undefined;
   readonly checks?: readonly Check[] | undefined;
@@ -712,6 +759,32 @@ interface Preset {
 }
 /** A preset factory as referenced by name from YAML and JSON configs. */
 type PresetFactory = (options?: JsonObject) => Preset;
+/** Loads a plugin on demand, usually `() => import('./plugin')`: the module's default export creates it. */
+type PluginLoader = () => Promise<{
+  readonly default: () => Plugin;
+}>;
+/** Loads a reporter on demand, usually `() => import('./reporter')`: the module's default export is the reporter. */
+type ReporterLoader = () => Promise<{
+  readonly default: Reporter;
+}>;
+/** Loads a preset on demand, usually `() => import('./preset')`: the module's default export is the factory. */
+type PresetLoader = () => Promise<{
+  readonly default: PresetFactory;
+}>;
+/** When a built-in preset applies. Cheap, so it stays loaded while the preset module does not. */
+interface PresetDetection {
+  /** Without `detect`, the preset applies only when listed in config. */
+  readonly detect?: ((ctx: DetectContext) => boolean | Promise<boolean>) | undefined;
+  /** When true and detected, presets that come after it are not applied. */
+  readonly exclusive?: boolean | undefined;
+}
+/**
+ * A built-in preset split in two: the detection is always loaded; the module behind `load`
+ * is imported only when it passes or the preset is listed in config.
+ */
+interface PresetEntry extends PresetDetection {
+  readonly load: PresetLoader;
+}
 //#endregion
 //#region src/types/config.d.ts
 /** Where a value comes from: an argument, or a property of an object argument. */
@@ -727,8 +800,8 @@ interface CallSpec {
   readonly kind?: "call" | "selector" | "accessor" | undefined;
   /** Which argument holds the key. Default 0. */
   readonly key?: number | ArgSource | undefined;
-  /** Where the namespace comes from (call option, or factory argument when `factory` is true). */
-  readonly namespace?: ArgSource | undefined;
+  /** Where the namespace comes from (call option, or factory argument when `factory` is true), or a fixed namespace such as `'shared'` for a hook that wraps `useTranslation('shared')`. */
+  readonly namespace?: ArgSource | string | undefined;
   /** Where a key prefix comes from (`keyPrefix` option, or next-intl `useTranslations('a.b')`). */
   readonly keyPrefix?: ArgSource | undefined;
   /** The callee is a factory that returns the translate function, for example `useI18n()` returning `{ t }`. */
@@ -785,12 +858,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;
@@ -804,7 +879,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 {
@@ -818,6 +893,12 @@ interface NamespaceOptions {
   readonly separator?: string | undefined;
   /** Namespace of keys written without one. */
   readonly default?: string | undefined;
+  /** Namespaces searched in order when a key written without a namespace is not in its own (i18next `fallbackNS`). */
+  readonly fallback?: readonly string[] | undefined;
+  /** Namespace of keys written without one, per glob of source files, before `default`: `{ 'packages/admin/**': 'admin' }`. */
+  readonly byFile?: {
+    readonly [glob: string]: string;
+  } | undefined;
   /** How `{namespaces}` folders name a namespace: `dot` makes `pages/home` into `pages.home`, `slash` keeps `pages/home`, `camel` makes `todos-page` into `todosPage`. Default `dot`. */
   readonly fromPath?: "dot" | "slash" | "camel" | undefined;
 }
@@ -909,6 +990,10 @@ interface ResolvedConfig {
   readonly namespace: {
     readonly separator: string;
     readonly default: string | undefined;
+    readonly fallback: readonly string[];
+    readonly byFile: {
+      readonly [glob: string]: string;
+    };
     readonly fromPath: NamespaceFromPath;
   };
   readonly usage: {
@@ -967,6 +1052,34 @@ export declare function keyMatcher(globs: readonly string[]): (key: KeyString) =
 /** Matcher over posix file paths. */
 export declare function pathMatcher(globs: readonly string[]): (path: string) => boolean;
 //#endregion
+//#region src/library.d.ts
+interface LibraryOptions {
+  /** The plugin name, prefixed by the caller: `x18n:vue-i18n`. */
+  readonly name: string;
+  readonly calls?: readonly CallSpec[];
+  /** i18n-ally style `usageMatchRegex` patterns, for languages without an AST scanner. */
+  readonly regex?: readonly RegexScannerSpec[];
+  /** The library's placeholder syntaxes. */
+  readonly placeholders?: readonly PlaceholderSyntax[];
+  readonly derivedKeys?: readonly string[];
+  readonly namespace?: {
+    readonly separator?: string;
+    readonly default?: string;
+    readonly fromPath?: NamespaceFromPath;
+  };
+  /** Default resource patterns (i18n-ally `preferredLocalePaths` + `pathMatcher`). */
+  readonly resources?: readonly ResourceSpec[];
+  readonly keyStyle?: "nested" | "flat";
+  readonly templates?: readonly ExtractTemplate[];
+  readonly finders?: readonly LocaleFinder[];
+  readonly normalizeKey?: Plugin["normalizeKey"];
+  readonly transformResource?: ResourceTransform;
+  readonly extra?: (draft: ConfigDraft, ctx: ConfigContext) => void | Promise<void>;
+  readonly translatePrompt?: Plugin["translatePrompt"];
+}
+/** One plugin holding a library's call specs, regexes, namespace rules, defaults and extraction templates. */
+export declare function createLibraryPlugin(options: LibraryOptions): Plugin;
+//#endregion
 //#region src/locale.d.ts
 /** Lenient display parse of a locale code (`zh_CN`, `pt-BR`, `sr-Latn-RS`). Never changes the code. */
 export declare function parseLocaleInfo(code: LocaleCode): LocaleInfo;
@@ -1019,9 +1132,11 @@ interface CapabilityConflict {
 /** The capabilities of the final plugin list, indexed for the project engine. */
 interface PluginRegistry {
   readonly plugins: readonly Plugin[];
-  readonly formats: readonly Format[];
+  /** Every format, loaded or not; use `formatFor` and `loadFormatFor` to run one. */
+  readonly formats: readonly (Format | LazyFormat)[];
   readonly finders: readonly LocaleFinder[];
-  readonly scanners: readonly Scanner[];
+  /** Every scanner, loaded or not. */
+  readonly scanners: readonly (Scanner | LazyScanner)[];
   readonly checks: ReadonlyMap<string, Check>;
   readonly reporters: ReadonlyMap<string, Reporter>;
   readonly placeholders: readonly PlaceholderSyntax[];
@@ -1029,10 +1144,18 @@ interface PluginRegistry {
   readonly extractors: readonly Extractor[];
   readonly histories: readonly HistoryProvider[];
   readonly conflicts: readonly CapabilityConflict[];
-  /** Format for a file path: config `formats` first, then the first format that claims the extension. */
+  /** The loaded format for a file path: config `formats` first, then the first format that claims the extension. */
   readonly formatFor: (path: string, hint?: string) => Format | undefined;
+  /** The id of the format `formatFor` would pick, loaded or not. */
+  readonly formatIdFor: (path: string, hint?: string) => string | undefined;
+  /** The loaded format with this id. */
   readonly formatById: (id: string) => Format | undefined;
-  readonly scannersFor: (path: string) => readonly Scanner[];
+  /** Loads the format of a file path, once, and returns it. */
+  readonly loadFormatFor: (path: string, hint?: string) => Promise<Format | undefined>;
+  /** The scanners that handle a file path, loaded or not. */
+  readonly scannersFor: (path: string) => readonly (Scanner | LazyScanner)[];
+  /** Loads the scanners of a file path, once each, and returns them. */
+  readonly loadScannersFor: (path: string) => Promise<readonly Scanner[]>;
 }
 export declare function extensionOf(path: string): string;
 export declare function createRegistry(input: readonly Plugin[], config: Pick<ResolvedConfig, "formats">): PluginRegistry;
@@ -1099,7 +1222,7 @@ export declare function renderPrompt(data: PromptData): string;
 interface Builtins {
   readonly plugins: readonly Plugin[];
   readonly presets: {
-    readonly [name: string]: PresetFactory;
+    readonly [name: string]: PresetEntry;
   };
 }
 interface ResolveConfigOptions {
@@ -1456,4 +1579,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, FormatEntry, GlobOptions, GlossaryEntry, HardString, HistoryConfigs, HistoryContext, HistoryOptions, HistoryProvider, HistorySettings, Host, JsonObject, JsonPrimitive, JsonValue, KeyContext, KeyId, KeyInfo, KeyQuery, KeyString, KeyTarget, LazyFormat, LazyScanner, LibraryOptions, 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, PluginLoader, PluginOption, PluginRegistry, PluginSpecifier, PluralForm, Preset, PresetDetection, PresetEntry, PresetExplanation, PresetFactory, PresetLoader, PresetOption, Project, ProjectChange, ProjectExplanation, PromptContext, PromptData, PromptDraft, PromptItem, PromptOptions, RegexScannerSpec, ReportInput, ReportSummary, Reporter, ReporterContext, ReporterLoader, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ScanContext, ScanResult, Scanner, ScannerEntry, 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

@@ -138,7 +138,9 @@ function defineConfig(config) {
 }
 //#endregion
 //#region src/errors.ts
-const at = (p) => p.line === void 0 ? p.path : `${p.path}:${p.line}`;
+function at(p) {
+	return p.line === void 0 ? p.path : `${p.path}:${p.line}`;
+}
 /**
 * Every coded error. Groups: 0xxx config, 1xxx plugin, 2xxx discovery and parse,
 * 3xxx scanning, 4xxx edits, 5xxx reviews. `fix` stays static so the docs can show it.
@@ -331,6 +333,40 @@ function pathMatcher(globs) {
 	return (path) => regexes.some((re) => re.test(path));
 }
 //#endregion
+//#region src/library.ts
+/** One plugin holding a library's call specs, regexes, namespace rules, defaults and extraction templates. */
+function createLibraryPlugin(options) {
+	return {
+		name: options.name,
+		async config(draft, ctx) {
+			if (options.namespace) draft.namespace = {
+				...draft.namespace,
+				separator: options.namespace.separator ?? draft.namespace.separator,
+				default: draft.namespace.default ?? options.namespace.default,
+				fromPath: options.namespace.fromPath ?? draft.namespace.fromPath
+			};
+			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;
+			draft.usage = {
+				...draft.usage,
+				calls: [...draft.usage.calls, ...options.calls ?? []],
+				regex: [...draft.usage.regex, ...options.regex ?? []],
+				derivedKeys: [...draft.usage.derivedKeys, ...options.derivedKeys ?? []]
+			};
+			await options.extra?.(draft, ctx);
+		},
+		placeholders: options.placeholders,
+		localeFinders: options.finders,
+		normalizeKey: options.normalizeKey,
+		transformResource: options.transformResource,
+		translatePrompt: options.translatePrompt,
+		extractors: options.templates ? [{
+			id: options.name,
+			templates: options.templates
+		}] : void 0
+	};
+}
+//#endregion
 //#region src/locale.ts
 const defaultRegions = {
 	ar: "SA",
@@ -418,8 +454,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,
@@ -427,7 +465,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. */
@@ -582,8 +621,8 @@ function uniqueById(items, kind) {
 }
 function createRegistry(input, config) {
 	const plugins = sortByEnforce(input);
-	const formats = plugins.flatMap((plugin) => plugin.formats ?? []);
-	const scanners = plugins.flatMap((plugin) => plugin.scanners ?? []);
+	const formats = plugins.flatMap((plugin) => [...plugin.formats ?? [], ...plugin.lazyFormats ?? []]);
+	const scanners = plugins.flatMap((plugin) => [...plugin.scanners ?? [], ...plugin.lazyScanners ?? []]);
 	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");
@@ -599,8 +638,58 @@ function createRegistry(input, config) {
 		});
 		else byExtension.set(extension, format);
 	}
-	const formatById = (id) => formats.find((format) => format.id === id);
+	const isLazy = (format) => "load" in format;
+	const loaded = new Map(formats.filter((format) => !isLazy(format)).map((format) => [format.id, format]));
+	const loading = /* @__PURE__ */ new Map();
+	const formatById = (id) => loaded.get(id);
+	const formatIdFor = (path, hint) => {
+		if (hint) return hint;
+		const extension = extensionOf(path);
+		return config.formats[extension] ?? byExtension.get(extension)?.id;
+	};
+	const loadFormat = (id) => {
+		const ready = loaded.get(id);
+		if (ready) return Promise.resolve(ready);
+		const lazy = formats.find((format) => format.id === id);
+		if (!lazy || !isLazy(lazy)) return Promise.resolve(void 0);
+		let pending = loading.get(id);
+		if (!pending) {
+			pending = lazy.load().then((mod) => {
+				const format = mod.default().formats?.find((item) => item.id === id && !isLazy(item));
+				if (format) loaded.set(id, format);
+				return format;
+			});
+			loading.set(id, pending);
+		}
+		return pending;
+	};
 	const scannerCache = /* @__PURE__ */ new Map();
+	const loadedScanners = new Map(scanners.filter((scanner) => !("load" in scanner)).map((scanner) => [scanner.id, scanner]));
+	const loadingScanners = /* @__PURE__ */ new Map();
+	const loadScanner = (entry) => {
+		if (!("load" in entry)) return Promise.resolve(entry);
+		const ready = loadedScanners.get(entry.id);
+		if (ready) return Promise.resolve(ready);
+		let pending = loadingScanners.get(entry.id);
+		if (!pending) {
+			pending = entry.load().then((mod) => {
+				const scanner = mod.default().scanners?.find((item) => item.id === entry.id);
+				if (scanner) loadedScanners.set(entry.id, scanner);
+				return scanner;
+			});
+			loadingScanners.set(entry.id, pending);
+		}
+		return pending;
+	};
+	const scannersFor = (path) => {
+		const extension = extensionOf(path);
+		let list = scannerCache.get(extension);
+		if (!list) {
+			list = extension ? scanners.filter((scanner) => scanner.extensions.includes(extension) || scanner.extensions.includes("*")) : [];
+			scannerCache.set(extension, list);
+		}
+		return list;
+	};
 	return {
 		plugins,
 		formats,
@@ -614,20 +703,18 @@ function createRegistry(input, config) {
 		histories: plugins.flatMap((plugin) => plugin.histories ?? []),
 		conflicts,
 		formatById,
+		formatIdFor,
 		formatFor(path, hint) {
-			if (hint) return formatById(hint);
-			const extension = extensionOf(path);
-			const mapped = config.formats[extension];
-			return mapped ? formatById(mapped) : byExtension.get(extension);
+			const id = formatIdFor(path, hint);
+			return id === void 0 ? void 0 : formatById(id);
 		},
-		scannersFor(path) {
-			const extension = extensionOf(path);
-			let list = scannerCache.get(extension);
-			if (!list) {
-				list = extension ? scanners.filter((scanner) => scanner.extensions.includes(extension) || scanner.extensions.includes("*")) : [];
-				scannerCache.set(extension, list);
-			}
-			return list;
+		async loadFormatFor(path, hint) {
+			const id = formatIdFor(path, hint);
+			return id === void 0 ? void 0 : loadFormat(id);
+		},
+		scannersFor,
+		async loadScannersFor(path) {
+			return (await Promise.all(scannersFor(path).map(loadScanner))).filter((scanner) => scanner !== void 0);
 		}
 	};
 }
@@ -662,7 +749,7 @@ const callSpec = v.strictObject({
 		"accessor"
 	])),
 	key: v.optional(v.union([v.number(), argSource])),
-	namespace: v.optional(argSource),
+	namespace: v.optional(v.union([argSource, v.string()])),
 	keyPrefix: v.optional(argSource),
 	factory: v.optional(v.boolean()),
 	returns: v.optional(strings),
@@ -706,6 +793,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)
@@ -720,6 +808,8 @@ const checkSetting = v.union([level, v.tuple([level, jsonObject])]);
 const namespaceOptions = v.strictObject({
 	separator: v.optional(v.string()),
 	default: v.optional(v.string()),
+	fallback: v.optional(strings),
+	byFile: v.optional(v.record(v.string(), v.string())),
 	fromPath: v.optional(v.picklist([
 		"dot",
 		"slash",
@@ -938,6 +1028,159 @@ 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, fallback } = config.namespace;
+	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;
+			}
+		}
+		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);
+			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) {
+			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 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;
+		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;
@@ -950,9 +1193,24 @@ 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;
@@ -1007,7 +1265,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),
@@ -1067,7 +1325,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);
@@ -1079,8 +1337,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)) : [];
@@ -1107,6 +1364,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,
@@ -1184,7 +1442,8 @@ function mirrorPath(path, from, to) {
 function importEdit(text, lines) {
 	const missing = lines.filter((line) => !text.includes(line.trim()));
 	if (missing.length === 0) return void 0;
-	const script = /<script\b[^>]*>\r?\n?/.exec(text);
+	const open = /^\s*---\r?\n/.exec(text);
+	const script = (open && /^---\s*$/m.test(text.slice(open[0].length)) ? open : void 0) ?? /<script\b[^>]*>\r?\n?/.exec(text);
 	let at = 0;
 	if (script) at = script.index + script[0].length;
 	else {
@@ -1278,7 +1537,9 @@ var PlanBuilder = class {
 		const sourceState = source && this.stateById.get(source.resource);
 		const namespace = namespaced ? this.keyId(key).namespace ?? this.config.namespace.default : sourceState?.resource.namespace;
 		const exists = (path) => resources.some((r) => r.resource.path === path);
-		const resolved = this.options.resolveNew(locale, namespace);
+		const sibling = (r) => r.resource.locale === locale && r.resource.namespace !== void 0 && namespace !== void 0;
+		const model = (sourceState && fits(sourceState) ? sourceState : void 0) ?? resources.find((s) => s.resource.locale === sourceLocale && fits(s)) ?? resources.find(fits) ?? resources.find(sibling);
+		const resolved = this.options.resolveNew(locale, namespace, model?.resource);
 		if (resolved && !exists(resolved)) {
 			const format = this.options.registry.formatFor(resolved);
 			if (format?.serialize) {
@@ -1294,8 +1555,6 @@ var PlanBuilder = class {
 				return target;
 			}
 		}
-		const sibling = (r) => r.resource.locale === locale && r.resource.namespace !== void 0 && namespace !== void 0;
-		const model = (sourceState && fits(sourceState) ? sourceState : void 0) ?? resources.find((s) => s.resource.locale === sourceLocale && fits(s)) ?? resources.find(fits) ?? resources.find(sibling);
 		const format = model && this.options.registry.formatById(model.resource.format);
 		let path = model && mirrorPath(model.resource.path, model.resource.locale, locale);
 		if (model && path && namespace !== void 0 && model.resource.namespace !== void 0 && model.resource.namespace !== namespace) path = mirrorPath(path, model.resource.namespace, namespace);
@@ -1527,7 +1786,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];
@@ -1919,95 +2178,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) {
@@ -2033,7 +2203,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,
@@ -2061,6 +2231,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,
@@ -2188,6 +2363,22 @@ function createProject(options) {
 		if (state.error) return void 0;
 		return new Map([...walkLeaves(state.tree)].map((leaf) => [keyFor(state.resource, leaf.path), leaf.value]));
 	}
+	/** A path for a new resource, from the locale finders. */
+	function newResourcePath(locale, namespace, model) {
+		const ctx = {
+			host,
+			config,
+			extensions: [...new Set(registry.formats.flatMap((format) => format.extensions))]
+		};
+		for (const finder of registry.finders) {
+			const path = finder.resolveNew?.({
+				locale,
+				namespace,
+				model
+			}, ctx);
+			if (path) return path;
+		}
+	}
 	async function loadResources(candidates, reread) {
 		const next = /* @__PURE__ */ new Map();
 		const paths = [...new Set(candidates.map((c) => c.path))];
@@ -2199,6 +2390,7 @@ function createProject(options) {
 			}
 		}));
 		namespaced = config.namespace.separator !== "." && candidates.some((c) => c.namespace !== void 0);
+		await Promise.all(candidates.map((candidate) => registry.loadFormatFor(candidate.path, candidate.format)));
 		for (const candidate of candidates) {
 			const text = fileTexts.get(candidate.path);
 			if (text === void 0) continue;
@@ -2219,6 +2411,11 @@ function createProject(options) {
 		resolver = createUsageResolver(config, namespaced, normalizers);
 		resolved = /* @__PURE__ */ new WeakMap();
 		resourceIndex = void 0;
+		const namespaces = /* @__PURE__ */ new Set([void 0, ...[...resourceStates.values()].map((state) => state.resource.namespace)]);
+		await Promise.all([...namespaces].map((namespace) => {
+			const path = newResourcePath(sourceLocale, namespace, void 0);
+			return path ? registry.loadFormatFor(path) : void 0;
+		}));
 	}
 	async function scanOne(file) {
 		const usages = [];
@@ -2226,7 +2423,7 @@ function createProject(options) {
 		const keySlots = [];
 		const hardStrings = [];
 		const calls = config.usage.calls.filter((spec) => ![spec.callee].flat().some((name) => config.usage.ignoreCallees.includes(name)));
-		for (const scanner of registry.scannersFor(file.path)) {
+		for (const scanner of await registry.loadScannersFor(file.path)) {
 			const result = await scanner.scan(file, {
 				config,
 				calls
@@ -2379,13 +2576,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,
@@ -2396,12 +2590,13 @@ function createProject(options) {
 		};
 	}
 	function buildIndex() {
-		resourceIndex ??= buildResourceIndex();
+		const { messages, parents, derived } = resourceIndex ??= buildResourceIndex();
+		const has = (key) => messages.has(key) || parents.has(key) || derived.has(key);
 		const usages = [];
 		for (const [path, state] of [...files].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
 			let list = resolved.get(state);
 			if (!list) {
-				list = state.result.usages.map((candidate) => resolver.resolve(candidate, state.result.scopes ?? [], path, "scanner"));
+				list = state.result.usages.map((candidate) => resolver.resolve(candidate, state.result.scopes ?? [], path, "scanner", has));
 				resolved.set(state, list);
 			}
 			usages.push(...list);
@@ -2457,8 +2652,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) => ({
@@ -2508,7 +2702,8 @@ function createProject(options) {
 			files,
 			history: history.get
 		}),
-		baseOf,
+		basesOf,
+		formOf,
 		localeInfo,
 		text: (path) => fileTexts.get(path) ?? files.get(path)?.text
 	});
@@ -2522,7 +2717,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) {
@@ -2542,7 +2737,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)
 		};
@@ -2634,8 +2829,9 @@ function createProject(options) {
 			const before = idx();
 			const paths = new Set(events.map((event) => event.path));
 			const resourcePaths = new Set([...resourceStates.values()].map((state) => state.resource.path));
-			const maybeResource = (path) => !resourcePaths.has(path) && registry.formatFor(path) !== void 0 && !usageEligible(path);
-			const structural = events.some((event) => event.type !== "change" || maybeResource(event.path));
+			const maybeResource = (path) => !resourcePaths.has(path) && registry.formatIdFor(path) !== void 0 && !usageEligible(path);
+			const blockPaths = new Set([...resourceStates.values()].filter((state) => state.resource.block).map((state) => state.resource.path));
+			const structural = events.some((event) => event.type !== "change" || maybeResource(event.path) || blockPaths.has(event.path));
 			if (structural || [...paths].some((path) => resourcePaths.has(path))) await loadResources(structural ? await discover() : [...resourceStates.values()].map((state) => ({
 				...state.resource,
 				format: state.resource.format === "unknown" ? void 0 : state.resource.format
@@ -2674,22 +2870,9 @@ 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 = {
-				host,
-				config,
-				extensions: [...new Set(registry.formats.flatMap((format) => format.extensions))]
-			};
-			for (const finder of registry.finders) {
-				const path = finder.resolveNew?.({
-					locale,
-					namespace
-				}, ctx);
-				if (path) return path;
-			}
-		},
+		resolveNew: newResourcePath,
 		update
 	});
 	const ready = (async () => {
@@ -2748,7 +2931,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);
 		},
@@ -2820,6 +3003,8 @@ function defaultDraft() {
 		namespace: {
 			separator: ".",
 			default: void 0,
+			fallback: [],
+			byFile: {},
 			fromPath: "dot"
 		},
 		usage: {
@@ -2903,6 +3088,11 @@ function applyLayer(draft, layer, origin, origins) {
 		draft.namespace = {
 			separator: layer.namespace.separator ?? draft.namespace.separator,
 			default: layer.namespace.default ?? draft.namespace.default,
+			fallback: layer.namespace.fallback ?? draft.namespace.fallback,
+			byFile: {
+				...draft.namespace.byFile,
+				...layer.namespace.byFile
+			},
 			fromPath: layer.namespace.fromPath ?? draft.namespace.fromPath
 		};
 		mark("namespace");
@@ -3007,8 +3197,8 @@ function createLoader(options) {
 		if (option === false || option === void 0) return void 0;
 		if (typeof option === "object" && !Array.isArray(option)) return option;
 		const [specifier, pluginOptions] = typeof option === "string" ? [option, void 0] : [option[0], option[1]];
-		const factory = options.builtins.presets[specifier];
-		if (factory) return factory(pluginOptions);
+		const entry = options.builtins.presets[specifier];
+		if (entry) return (await entry.load()).default(pluginOptions);
 		if (!options.loadPlugin) throw errors.X18N1003({ preset: specifier });
 		return options.loadPlugin(specifier, pluginOptions);
 	};
@@ -3044,7 +3234,17 @@ async function expandPresets(presets, userPlugins, listed, detectCtx) {
 		name: preset.name,
 		reason: "after-exclusive"
 	});
-	else stopped = await flatten(preset, listed);
+	else if ("entry" in preset) {
+		const applies = listed || (preset.entry.detect ? await preset.entry.detect(detectCtx) : false);
+		explanations.push({
+			name: preset.name,
+			reason: applies ? listed ? "listed" : "detected" : "not-detected"
+		});
+		if (!applies) continue;
+		const loaded = (await preset.entry.load()).default();
+		for (const child of loaded.plugins) await flatten(child, false);
+		stopped = preset.entry.exclusive === true || loaded.exclusive === true;
+	} else stopped = await flatten(preset, listed);
 	for (const plugin of userPlugins) await flatten(plugin, true);
 	return {
 		plugins,
@@ -3067,7 +3267,10 @@ async function resolveConfig(options) {
 	const userPlugins = await loadAll(load, [...options.parent?.plugins ?? [], ...user.plugins ?? []]);
 	const presetOption = user.presets ?? options.parent?.presets ?? "auto";
 	const auto = presetOption === "auto";
-	const presets = auto ? Object.values(builtins.presets).map((factory) => factory()) : (await loadAll(load, presetOption)).map((item) => isPreset(item) ? item : {
+	const presets = auto ? Object.entries(builtins.presets).map(([name, entry]) => ({
+		name,
+		entry
+	})) : (await loadAll(load, presetOption)).map((item) => isPreset(item) ? item : {
 		name: item.name,
 		plugins: [item]
 	});
@@ -3108,4 +3311,4 @@ async function resolveConfig(options) {
 	};
 }
 //#endregion
-export { ConfigSchema, PluginFileSchema, applyMessageOps, applyTextEdits, buildTree, contractVersion, createLineIndex, createMemoryHost, createOverlayHost, createPlaceholderComparer, createProject, createRegistry, defineConfig, definePlugin, definePreset, diffText, envelope, errors, extensionOf, globToRegExp, hashText, isJsonObject, isKeyUnder, isMessageLeaf, isMessageTree, isPreset, isX18nError, joinKey, keyMatcher, localeSpellingKey, parseLocaleInfo, parseMessageBatch, pathId, pathMatcher, placeholderProblems, rangeContains, renderPrompt, replaceKeyPrefix, resolveConfig, sortTree, splitKey, toErrorInfo, toWireDiagnostic, toWireRange, validate, walkLeaves };
+export { ConfigSchema, PluginFileSchema, applyMessageOps, applyTextEdits, buildTree, contractVersion, createLibraryPlugin, createLineIndex, createMemoryHost, createOverlayHost, createPlaceholderComparer, createProject, createRegistry, defineConfig, definePlugin, definePreset, diffText, envelope, errors, extensionOf, globToRegExp, hashText, isJsonObject, isKeyUnder, isMessageLeaf, isMessageTree, isPreset, isX18nError, joinKey, keyMatcher, localeSpellingKey, parseLocaleInfo, parseMessageBatch, pathId, pathMatcher, placeholderProblems, rangeContains, renderPrompt, replaceKeyPrefix, resolveConfig, sortTree, splitKey, toErrorInfo, toWireDiagnostic, toWireRange, validate, walkLeaves };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/core",
   "type": "module",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "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

@@ -145,6 +145,21 @@
         "default": {
           "type": "string"
         },
+        "fallback": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "byFile": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
         "fromPath": {
           "enum": [
             "dot",
@@ -221,19 +236,26 @@
                 ]
               },
               "namespace": {
-                "type": "object",
-                "properties": {
-                  "arg": {
-                    "type": "number"
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "arg": {
+                        "type": "number"
+                      },
+                      "property": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "arg"
+                    ],
+                    "additionalProperties": false
                   },
-                  "property": {
+                  {
                     "type": "string"
                   }
-                },
-                "required": [
-                  "arg"
-                ],
-                "additionalProperties": false
+                ]
               },
               "keyPrefix": {
                 "type": "object",
@@ -404,6 +426,12 @@
             }
           }
         },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
         "ignoreAttributes": {
           "type": "array",
           "items": {

package/schema/plugin.json

@@ -90,6 +90,21 @@
             "default": {
               "type": "string"
             },
+            "fallback": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "byFile": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {
+                "type": "string"
+              }
+            },
             "fromPath": {
               "enum": [
                 "dot",
@@ -166,19 +181,26 @@
                 ]
               },
               "namespace": {
-                "type": "object",
-                "properties": {
-                  "arg": {
-                    "type": "number"
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "arg": {
+                        "type": "number"
+                      },
+                      "property": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "arg"
+                    ],
+                    "additionalProperties": false
                   },
-                  "property": {
+                  {
                     "type": "string"
                   }
-                },
-                "required": [
-                  "arg"
-                ],
-                "additionalProperties": false
+                ]
               },
               "keyPrefix": {
                 "type": "object",