@x18n/core 0.1.6 → 0.1.7

package/dist/index.d.mts

@@ -248,235 +248,6 @@ interface ReviewFilter {
   readonly open?: boolean | undefined;
 }
 //#endregion
-//#region src/types/model.d.ts
-/** A locale code exactly as written in paths and files: `en`, `zh_CN`, `pt-BR`. Never normalized. */
-type LocaleCode = string;
-/** Canonical key string: `ns:a.b.c`, or `a.b.c` without namespace. */
-type KeyString = string;
-/** Resource id: the resource path, plus `#<block index>` for embedded resources. */
-type ResourceId = string;
-type MessageLeaf = string | number | boolean | null;
-interface MessageTree {
-  readonly [segment: string]: MessageLeaf | MessageTree;
-}
-/** UTF-16 offsets, the same as JS strings. */
-interface TextRange {
-  readonly start: number;
-  readonly end: number;
-}
-interface TextEdit {
-  readonly range: TextRange;
-  readonly text: string;
-}
-/** Ranges of a key and its value (or object) in the resource text. */
-interface NodeRange {
-  readonly key: TextRange;
-  readonly value: TextRange;
-}
-interface KeyId {
-  readonly namespace: string | undefined;
-  readonly path: readonly string[];
-}
-/** Display data from a lenient parse of a code. Never changes the code itself. */
-interface LocaleInfo {
-  readonly code: LocaleCode;
-  readonly language: string | undefined;
-  readonly region: string | undefined;
-  readonly displayName: string | undefined;
-  readonly flag: string | undefined;
-  /** The plural categories a message may have. */
-  readonly pluralCategories: readonly Intl.LDMLPluralRule[];
-  /** Categories of ordinal numbers (1st, 2nd), which differ from the cardinal ones. */
-  readonly ordinalCategories: readonly Intl.LDMLPluralRule[];
-  /** The plural categories a message must have: those whole numbers select. French may leave out `many`, from 1,000,000 only. */
-  readonly requiredPluralCategories: readonly Intl.LDMLPluralRule[];
-  readonly requiredOrdinalCategories: readonly Intl.LDMLPluralRule[];
-}
-/** Embedded resource inside a file, for example a Vue `<i18n>` block. */
-interface ResourceBlock {
-  readonly index: number;
-  /** Range of the block content in the file. */
-  readonly range: TextRange;
-  readonly lang: string | undefined;
-}
-interface Resource {
-  readonly id: ResourceId;
-  /** Posix path relative to the project root. */
-  readonly path: string;
-  readonly locale: LocaleCode;
-  readonly namespace: string | undefined;
-  readonly format: string;
-  readonly block: ResourceBlock | undefined;
-  /** True for read-only formats and for resources loaded with `execute: true`. */
-  readonly readonly: boolean;
-  /** Id of the locale finder that found the resource. */
-  readonly finder: string;
-}
-/** One stored value of one key in one locale. */
-interface Message {
-  readonly key: KeyString;
-  readonly locale: LocaleCode;
-  readonly value: MessageLeaf;
-  readonly resource: ResourceId;
-  /** Property path as stored in the resource (`['a.b']` in a flat file, `['a', 'b']` nested). */
-  readonly storedPath: readonly string[];
-  /** Ranges in the resource file text (block offsets already added). */
-  readonly range: NodeRange | undefined;
-}
-type UsageKind = "call" | "selector" | "accessor" | "constant" | "marker";
-interface Usage {
-  /** Undefined when the key is fully dynamic. */
-  readonly key: KeyString | undefined;
-  /** The key text as written in code. */
-  readonly raw: string;
-  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;
-  /** Names of the params the call passes (`t('a', { n })` gives `['n']`); undefined when the scanner cannot tell, as with a spread or a variable. */
-  readonly params?: readonly string[] | undefined;
-  /** The default value written in code (`t('a', 'Default')`), when the scanner knows it. */
-  readonly defaultValue?: string | undefined;
-  readonly scanner: string;
-  readonly kind: UsageKind;
-  /** `t(`pages.${id}.title`)` gives 'prefix' with key `pages`. */
-  readonly dynamic: false | "prefix" | "unknown";
-  readonly locale: LocaleCode | undefined;
-  /** Namespace that came from a scope or a factory, not from the raw text. */
-  readonly scopeNamespace: string | undefined;
-  /** Key prefix that came from a scope or factory (`keyPrefix`), not from the raw text. */
-  readonly scopePrefix: string | undefined;
-}
-type Severity = "error" | "warning" | "info" | "hint";
-type EditOp = {
-  readonly type: "set";
-  readonly key: KeyString;
-  readonly locale: LocaleCode;
-  readonly value: MessageLeaf;
-} | {
-  readonly type: "rename";
-  readonly from: KeyString;
-  readonly to: KeyString;
-  readonly usages?: boolean;
-} | {
-  readonly type: "rename-prefix";
-  readonly from: KeyString;
-  readonly to: KeyString;
-  readonly usages?: boolean;
-} | {
-  readonly type: "delete";
-  readonly key: KeyString;
-  readonly locales?: "all" | readonly LocaleCode[];
-} | {
-  readonly type: "extract";
-  readonly items: readonly ExtractItem[];
-} | {
-  readonly type: "format";
-  readonly paths?: readonly string[];
-} | {
-  readonly type: "review";
-  readonly key: KeyString;
-  readonly locale: LocaleCode;
-  readonly review: ReviewType;
-  readonly text?: string | undefined;
-  /** The proposed value, required for `suggestion`. */
-  readonly suggestion?: string | undefined;
-  readonly author?: ReviewAuthor | undefined;
-  readonly id?: string | undefined;
-  readonly time?: string | undefined;
-} | {
-  readonly type: "resolve-review";
-  readonly id: string;
-} | {
-  readonly type: "apply-suggestion";
-  readonly id: string;
-} | {
-  readonly type: "mark-fresh";
-  readonly key: KeyString;
-  readonly locales?: readonly LocaleCode[] | undefined;
-};
-interface ExtractItem {
-  readonly path: string;
-  /** Range of the hard string in the source file, quotes included. */
-  readonly range: TextRange;
-  readonly key: KeyString;
-  readonly value: string;
-  /** Replacement text for the range. */
-  readonly replacement: string;
-  /** Lines to add once per file when missing, for example an import. */
-  readonly imports?: readonly string[];
-}
-interface Fix {
-  readonly title: string;
-  readonly ops: readonly EditOp[];
-}
-interface Location {
-  readonly path: string;
-  readonly range: TextRange;
-}
-interface Diagnostic {
-  /** Check id, for example 'missing-translation'. */
-  readonly code: string;
-  readonly severity: Severity;
-  readonly message: string;
-  readonly key: KeyString | undefined;
-  readonly locale: LocaleCode | undefined;
-  readonly location: Location | undefined;
-  readonly fixes: readonly Fix[];
-}
-interface Placeholder {
-  readonly syntax: string;
-  /** Text as written, for example `{name}`. */
-  readonly text: string;
-  /** Name used for comparison across locales, for example `name`. */
-  readonly name: string;
-  readonly range: TextRange;
-}
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | readonly JsonValue[] | JsonObject;
-interface JsonObject {
-  readonly [key: string]: JsonValue;
-}
-//#endregion
-//#region src/contracts.d.ts
-/** Version of every JSON contract (CLI `--json`, LSP `x18n/*`, RPC, MCP). Bumped on breaking changes to any shape. */
-export declare const contractVersion = 2;
-interface WireRange {
-  /** 1-based. */
-  readonly line: number;
-  /** 1-based, UTF-16 code units. */
-  readonly column: number;
-  readonly endLine: number;
-  readonly endColumn: number;
-  /** 0-based UTF-16 offsets. */
-  readonly start: number;
-  readonly end: number;
-}
-interface WireDiagnostic {
-  readonly project: string;
-  readonly code: string;
-  readonly severity: Severity;
-  readonly message: string;
-  readonly key: KeyString | undefined;
-  readonly locale: LocaleCode | undefined;
-  /** Path relative to the project root. */
-  readonly file: string | undefined;
-  readonly range: WireRange | undefined;
-  readonly fixes: readonly Fix[];
-}
-interface Envelope<T> {
-  readonly x18n: number;
-  readonly command: string;
-  readonly data: T;
-  readonly diagnostics: readonly WireDiagnostic[];
-  readonly errors: readonly ErrorInfo[];
-}
-/** Line and column form of an offset range in a text. */
-export declare function toWireRange(text: string | undefined, start: number, end: number): WireRange;
-export declare function toWireDiagnostic(project: string, diagnostic: Diagnostic, text: (path: string) => string | undefined): WireDiagnostic;
-export declare function envelope<T>(command: string, data: T, diagnostics?: readonly WireDiagnostic[], errors?: readonly ErrorInfo[]): Envelope<T>;
-//#endregion
 //#region src/types/host.d.ts
 interface Disposable {
   readonly dispose: () => void;
@@ -543,6 +314,8 @@ interface ResourceCandidate {
   readonly format?: string | undefined;
   readonly block?: ResourceBlock | undefined;
   readonly readonly?: boolean | undefined;
+  /** Key separator of the resource, over the config's (from `ResourceSpec.keySeparator`). */
+  readonly keySeparator?: KeySeparator | undefined;
 }
 interface FinderContext {
   readonly host: Host;
@@ -574,6 +347,8 @@ interface ParseResult {
   readonly tree: MessageTree;
   /** Ranges of keys and values (leaves and objects), keyed by `pathId(storedPath)`. */
   readonly ranges?: ReadonlyMap<string, NodeRange> | undefined;
+  /** What the file says about a message for translators (a note or comment next to it), keyed by `pathId(storedPath)`. */
+  readonly descriptions?: ReadonlyMap<string, string> | undefined;
 }
 type MessageOp = {
   readonly type: "set";
@@ -635,6 +410,8 @@ interface UsageCandidate {
   readonly params?: readonly string[] | undefined;
   /** The default value the call writes in code. */
   readonly defaultValue?: string | undefined;
+  /** A description of the message written next to the key in code. */
+  readonly description?: string | undefined;
   readonly kind: UsageKind;
   readonly dynamic: false | "prefix" | "unknown";
   readonly namespace?: string | undefined;
@@ -648,6 +425,10 @@ interface Scope {
   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;
+  /** With `optionalPrefix`: more prefixes to try after `keyPrefix`, in order. */
+  readonly otherPrefixes?: readonly string[] | undefined;
+  /** With `optionalPrefix`: a prefixed key counts in the fallback namespaces too. */
+  readonly prefixInFallback?: boolean | undefined;
 }
 interface HardString {
   readonly text: string;
@@ -843,6 +624,8 @@ interface ResourceTransform {
   readonly read: (tree: MessageTree, ctx: ResourceTransformContext) => MessageTree;
   /** The path in the file of a key path of the transformed tree. */
   readonly toStored: (path: readonly string[], ctx: ResourceTransformContext) => string[];
+  /** Descriptions that the stored tree holds beside the messages, such as `{ "name": { "message": "...", "description": "..." } }`, keyed by `pathId(storedPath)`. */
+  readonly describe?: ((tree: MessageTree, ctx: ResourceTransformContext) => ReadonlyMap<string, string>) | undefined;
 }
 interface PromptDraft {
   readonly rules: string[];
@@ -951,6 +734,8 @@ interface CallSpec {
   readonly params?: ParamsSource | undefined;
   /** Where a default value written in code comes from; the first string found wins. For factories, that of the returned functions. */
   readonly defaultValue?: readonly ArgSource[] | undefined;
+  /** With a key read from a property: the property beside it that describes the message for translators, such as `'description'` for `{ id, description }`. */
+  readonly description?: string | undefined;
   /** The callee is a factory that returns the translate function, for example `useI18n()` returning `{ t }`. */
   readonly factory?: boolean | undefined;
   /** For factories: the names of the returned translate functions. Default `['t']`. */
@@ -974,7 +759,14 @@ interface ResourceSpec {
   readonly locale?: string | undefined;
   /** Run matching JS/TS files in Node instead of reading them statically. Makes them read-only. */
   readonly execute?: boolean | undefined;
+  /** Key separator of matching files, over `keySeparator`. `false` for files keyed by whole sentences (Laravel `lang/{locale}.json`). */
+  readonly keySeparator?: string | false | undefined;
 }
+/**
+ * What splits a key into a path: `.` by default (`a.b` is `{ a: { b } }` in a nested file).
+ * `false` makes keys literal, so `Welcome back.` or `Note: x` is one key (i18next `keySeparator: false`, gettext, Laravel JSON).
+ */
+type KeySeparator = string | false;
 type CheckLevel = Severity | "off";
 type CheckSetting = CheckLevel | readonly [CheckLevel, JsonObject];
 interface GlossaryEntry {
@@ -987,6 +779,7 @@ interface GlossaryEntry {
   readonly doNotTranslate?: boolean | undefined;
 }
 interface ExtractTemplate {
+  /** Replacement code with `{key}`, `{attr}`, `{args}`, `{text}`, `{source}` and `{parts}` tokens. `{key}` and `{text}` are escaped for the quotes around them. */
   readonly template: string;
   /** Hard-string kinds the template applies to, for example `jsx-text`. */
   readonly kinds?: readonly string[] | undefined;
@@ -1036,8 +829,8 @@ interface WriteOptions {
   readonly keepFilled?: boolean | undefined;
 }
 interface NamespaceOptions {
-  /** Separator between namespace and key in code. `.` merges the namespace into the key path. Default `.`. */
-  readonly separator?: string | undefined;
+  /** Separator between namespace and key in code. `.` merges the namespace into the key path. `false` keeps namespaces out of keys in code (i18next `nsSeparator: false`), so a key may hold `:`. Default `.`. */
+  readonly separator?: string | false | 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`). */
@@ -1083,6 +876,8 @@ interface SerializableConfig {
     readonly [extension: string]: string;
   } | undefined;
   readonly keyStyle?: "auto" | "nested" | "flat" | undefined;
+  /** What splits a key into a path: `a.b` is `{ a: { b } }` in a nested file. `false` makes keys literal, so `Welcome back.` or `Note: x` is one key and a new key is one property (i18next `keySeparator: false`, gettext). A resource pattern can set its own. */
+  readonly keySeparator?: string | false | undefined;
   readonly namespace?: NamespaceOptions | undefined;
   readonly usage?: UsageOptions | undefined;
   readonly write?: WriteOptions | undefined;
@@ -1144,8 +939,9 @@ interface ResolvedConfig {
     readonly [extension: string]: string;
   };
   readonly keyStyle: "auto" | "nested" | "flat";
+  readonly keySeparator: KeySeparator;
   readonly namespace: {
-    readonly separator: string;
+    readonly separator: string | false;
     readonly default: string | undefined;
     readonly fallback: readonly string[];
     readonly byFile: {
@@ -1189,6 +985,241 @@ interface ResolvedConfig {
 /** A mutable view of the config that `config` hooks change. */
 type ConfigDraft = { -readonly [K in keyof Omit<ResolvedConfig, "origins" | "name">]: ResolvedConfig[K]; };
 //#endregion
+//#region src/types/model.d.ts
+/** A locale code exactly as written in paths and files: `en`, `zh_CN`, `pt-BR`. Never normalized. */
+type LocaleCode = string;
+/** Canonical key string: `ns:a.b.c`, or `a.b.c` without namespace. */
+type KeyString = string;
+/** Resource id: the resource path, plus `#<block index>` for embedded resources. */
+type ResourceId = string;
+type MessageLeaf = string | number | boolean | null;
+interface MessageTree {
+  readonly [segment: string]: MessageLeaf | MessageTree;
+}
+/** UTF-16 offsets, the same as JS strings. */
+interface TextRange {
+  readonly start: number;
+  readonly end: number;
+}
+interface TextEdit {
+  readonly range: TextRange;
+  readonly text: string;
+}
+/** Ranges of a key and its value (or object) in the resource text. */
+interface NodeRange {
+  readonly key: TextRange;
+  readonly value: TextRange;
+}
+interface KeyId {
+  readonly namespace: string | undefined;
+  readonly path: readonly string[];
+}
+/** Display data from a lenient parse of a code. Never changes the code itself. */
+interface LocaleInfo {
+  readonly code: LocaleCode;
+  readonly language: string | undefined;
+  readonly region: string | undefined;
+  readonly displayName: string | undefined;
+  readonly flag: string | undefined;
+  /** The plural categories a message may have. */
+  readonly pluralCategories: readonly Intl.LDMLPluralRule[];
+  /** Categories of ordinal numbers (1st, 2nd), which differ from the cardinal ones. */
+  readonly ordinalCategories: readonly Intl.LDMLPluralRule[];
+  /** The plural categories a message must have: those whole numbers select. French may leave out `many`, from 1,000,000 only. */
+  readonly requiredPluralCategories: readonly Intl.LDMLPluralRule[];
+  readonly requiredOrdinalCategories: readonly Intl.LDMLPluralRule[];
+}
+/** Embedded resource inside a file, for example a Vue `<i18n>` block. */
+interface ResourceBlock {
+  readonly index: number;
+  /** Range of the block content in the file. */
+  readonly range: TextRange;
+  readonly lang: string | undefined;
+}
+interface Resource {
+  readonly id: ResourceId;
+  /** Posix path relative to the project root. */
+  readonly path: string;
+  readonly locale: LocaleCode;
+  readonly namespace: string | undefined;
+  readonly format: string;
+  readonly block: ResourceBlock | undefined;
+  /** True for read-only formats and for resources loaded with `execute: true`. */
+  readonly readonly: boolean;
+  /** Id of the locale finder that found the resource. */
+  readonly finder: string;
+  /** Key separator of the resource when it differs from the config's `keySeparator` (from its resource spec). */
+  readonly keySeparator?: KeySeparator | undefined;
+}
+/** One stored value of one key in one locale. */
+interface Message {
+  readonly key: KeyString;
+  readonly locale: LocaleCode;
+  readonly value: MessageLeaf;
+  readonly resource: ResourceId;
+  /** Property path as stored in the resource (`['a.b']` in a flat file, `['a', 'b']` nested). */
+  readonly storedPath: readonly string[];
+  /** Ranges in the resource file text (block offsets already added). */
+  readonly range: NodeRange | undefined;
+  /** What the resource says about the message for translators, such as a note or a comment beside it. */
+  readonly description?: string | undefined;
+}
+type UsageKind = "call" | "selector" | "accessor" | "constant" | "marker";
+interface Usage {
+  /** Undefined when the key is fully dynamic. */
+  readonly key: KeyString | undefined;
+  /** The key text as written in code. */
+  readonly raw: string;
+  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;
+  /** Names of the params the call passes (`t('a', { n })` gives `['n']`); undefined when the scanner cannot tell, as with a spread or a variable. */
+  readonly params?: readonly string[] | undefined;
+  /** The default value written in code (`t('a', 'Default')`), when the scanner knows it. */
+  readonly defaultValue?: string | undefined;
+  /** A description of the message written next to the key in code (`CallSpec.description`), when the scanner knows it. */
+  readonly description?: string | undefined;
+  readonly scanner: string;
+  readonly kind: UsageKind;
+  /** `t(`pages.${id}.title`)` gives 'prefix' with key `pages`. */
+  readonly dynamic: false | "prefix" | "unknown";
+  readonly locale: LocaleCode | undefined;
+  /** Namespace that came from a scope or a factory, not from the raw text. */
+  readonly scopeNamespace: string | undefined;
+  /** Key prefix that came from a scope or factory (`keyPrefix`), not from the raw text. */
+  readonly scopePrefix: string | undefined;
+}
+type Severity = "error" | "warning" | "info" | "hint";
+type EditOp = {
+  readonly type: "set";
+  readonly key: KeyString;
+  readonly locale: LocaleCode;
+  readonly value: MessageLeaf;
+} | {
+  readonly type: "rename";
+  readonly from: KeyString;
+  readonly to: KeyString;
+  readonly usages?: boolean;
+} | {
+  readonly type: "rename-prefix";
+  readonly from: KeyString;
+  readonly to: KeyString;
+  readonly usages?: boolean;
+} | {
+  readonly type: "delete";
+  readonly key: KeyString;
+  readonly locales?: "all" | readonly LocaleCode[];
+} | {
+  readonly type: "extract";
+  readonly items: readonly ExtractItem[];
+} | {
+  readonly type: "format";
+  readonly paths?: readonly string[];
+} | {
+  readonly type: "review";
+  readonly key: KeyString;
+  readonly locale: LocaleCode;
+  readonly review: ReviewType;
+  readonly text?: string | undefined;
+  /** The proposed value, required for `suggestion`. */
+  readonly suggestion?: string | undefined;
+  readonly author?: ReviewAuthor | undefined;
+  readonly id?: string | undefined;
+  readonly time?: string | undefined;
+} | {
+  readonly type: "resolve-review";
+  readonly id: string;
+} | {
+  readonly type: "apply-suggestion";
+  readonly id: string;
+} | {
+  readonly type: "mark-fresh";
+  readonly key: KeyString;
+  readonly locales?: readonly LocaleCode[] | undefined;
+};
+interface ExtractItem {
+  readonly path: string;
+  /** Range of the hard string in the source file, quotes included. */
+  readonly range: TextRange;
+  readonly key: KeyString;
+  readonly value: string;
+  /** Replacement text for the range. */
+  readonly replacement: string;
+  /** Lines to add once per file when missing, for example an import. */
+  readonly imports?: readonly string[];
+}
+interface Fix {
+  readonly title: string;
+  readonly ops: readonly EditOp[];
+}
+interface Location {
+  readonly path: string;
+  readonly range: TextRange;
+}
+interface Diagnostic {
+  /** Check id, for example 'missing-translation'. */
+  readonly code: string;
+  readonly severity: Severity;
+  readonly message: string;
+  readonly key: KeyString | undefined;
+  readonly locale: LocaleCode | undefined;
+  readonly location: Location | undefined;
+  readonly fixes: readonly Fix[];
+}
+interface Placeholder {
+  readonly syntax: string;
+  /** Text as written, for example `{name}`. */
+  readonly text: string;
+  /** Name used for comparison across locales, for example `name`. */
+  readonly name: string;
+  readonly range: TextRange;
+}
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | readonly JsonValue[] | JsonObject;
+interface JsonObject {
+  readonly [key: string]: JsonValue;
+}
+//#endregion
+//#region src/contracts.d.ts
+/** Version of every JSON contract (CLI `--json`, LSP `x18n/*`, RPC, MCP). Bumped on breaking changes to any shape. */
+export declare const contractVersion = 2;
+interface WireRange {
+  /** 1-based. */
+  readonly line: number;
+  /** 1-based, UTF-16 code units. */
+  readonly column: number;
+  readonly endLine: number;
+  readonly endColumn: number;
+  /** 0-based UTF-16 offsets. */
+  readonly start: number;
+  readonly end: number;
+}
+interface WireDiagnostic {
+  readonly project: string;
+  readonly code: string;
+  readonly severity: Severity;
+  readonly message: string;
+  readonly key: KeyString | undefined;
+  readonly locale: LocaleCode | undefined;
+  /** Path relative to the project root. */
+  readonly file: string | undefined;
+  readonly range: WireRange | undefined;
+  readonly fixes: readonly Fix[];
+}
+interface Envelope<T> {
+  readonly x18n: number;
+  readonly command: string;
+  readonly data: T;
+  readonly diagnostics: readonly WireDiagnostic[];
+  readonly errors: readonly ErrorInfo[];
+}
+/** Line and column form of an offset range in a text. */
+export declare function toWireRange(text: string | undefined, start: number, end: number): WireRange;
+export declare function toWireDiagnostic(project: string, diagnostic: Diagnostic, text: (path: string) => string | undefined): WireDiagnostic;
+export declare function envelope<T>(command: string, data: T, diagnostics?: readonly WireDiagnostic[], errors?: readonly ErrorInfo[]): Envelope<T>;
+//#endregion
 //#region src/define.d.ts
 export declare function definePlugin<const T extends Plugin>(plugin: T): T;
 export declare function definePlugin<O, const T extends Plugin>(factory: (options: O) => T): (options: O) => T;
@@ -1200,12 +1231,15 @@ export declare function defineConfig(config: UserConfig & { readonly [K in keyof
 export declare function fuzzyScore(query: string, text: string): number;
 //#endregion
 //#region src/keys.d.ts
-/** Canonical string form of a key: `ns:a.b.c`, or `a.b.c` without namespace. */
-export declare function joinKey(namespace: string | undefined, path: readonly string[]): KeyString;
-/** Splits a key string. `namespaced` is false for projects without namespaces, where `:` is part of the key. */
-export declare function splitKey(key: KeyString, namespaced?: boolean): KeyId;
-/** True when `key` is `prefix` itself or lies under it (`a.b` is under `a`). */
-export declare function isKeyUnder(key: KeyString, prefix: KeyString): boolean;
+/** Canonical string form of a key: `ns:a.b.c`, or `a.b.c` without namespace. `separator` joins the path (`.` by default). */
+export declare function joinKey(namespace: string | undefined, path: readonly string[], separator?: KeySeparator): KeyString;
+/**
+ * Splits a key string. `namespaced` is false for projects without namespaces, where `:` is part of the key.
+ * The namespace ends at the first `:`, so the rest of the key may hold more. With `separator: false` the path is one literal segment.
+ */
+export declare function splitKey(key: KeyString, namespaced?: boolean, separator?: KeySeparator): KeyId;
+/** True when `key` is `prefix` itself or lies under it (`a.b` is under `a`). A literal key (`separator: false`) has nothing under it but in its namespace. */
+export declare function isKeyUnder(key: KeyString, prefix: KeyString, separator?: KeySeparator): boolean;
 /** Replaces the `from` prefix of `key` with `to`. */
 export declare function replaceKeyPrefix(key: KeyString, from: KeyString, to: KeyString): KeyString;
 /**
@@ -1213,8 +1247,8 @@ export declare function replaceKeyPrefix(key: KeyString, from: KeyString, to: Ke
  * `{a,b}` alternates, `[...]` is a character class.
  */
 export declare function globToRegExp(glob: string, separator?: string): RegExp;
-/** Matcher over key globs: `*` stays inside a segment, `**` spans segments. */
-export declare function keyMatcher(globs: readonly string[]): (key: KeyString) => boolean;
+/** Matcher over key globs: `*` stays inside a segment, `**` spans segments. With literal keys (`separator: false`) `*` spans the whole key. */
+export declare function keyMatcher(globs: readonly string[], separator?: KeySeparator): (key: KeyString) => boolean;
 /** Matcher over posix file paths. */
 export declare function pathMatcher(globs: readonly string[]): (path: string) => boolean;
 //#endregion
@@ -1236,6 +1270,8 @@ interface LibraryOptions {
   /** Default resource patterns (i18n-ally `preferredLocalePaths` + `pathMatcher`). */
   readonly resources?: readonly ResourceSpec[];
   readonly keyStyle?: "nested" | "flat";
+  /** The library's key separator; `false` for literal keys (gettext). The user's `keySeparator` wins. */
+  readonly keySeparator?: KeySeparator;
   readonly templates?: readonly ExtractTemplate[];
   readonly finders?: readonly LocaleFinder[];
   readonly normalizeKey?: Plugin["normalizeKey"];
@@ -1342,6 +1378,15 @@ interface PromptOptions {
   readonly stale?: boolean | undefined;
   /** Translate prompts: add translations that checks report in the target locale, all of them (`true`) or of these check ids. */
   readonly check?: boolean | readonly string[] | undefined;
+  /**
+   * Values of related locales to show next to each message: `true` (default) picks them (see `relatedLocales`),
+   * a list names them in order, `false` leaves them out.
+   */
+  readonly related?: boolean | readonly LocaleCode[] | undefined;
+}
+interface RelatedValue {
+  readonly locale: LocaleCode;
+  readonly value: string;
 }
 interface PromptIssue {
   /** Check id, for example `identical-to-source`. */
@@ -1357,6 +1402,10 @@ interface PromptItem {
   readonly key: KeyString;
   readonly source: string;
   readonly placeholders: readonly string[];
+  /** What the resources or the code say about the message for translators, when they say something. */
+  readonly description?: string | undefined;
+  /** Values of the message in related locales, such as `pt` when translating to `pt-BR`, nearest first. */
+  readonly related?: readonly RelatedValue[] | undefined;
   /** The current value in the target locale, when there is one. */
   readonly existing: string | undefined;
   /** For a stale translation: the source value when the translation last changed, when known. */
@@ -1390,6 +1439,12 @@ interface PromptData {
   readonly items: readonly PromptItem[];
   readonly instructions: readonly string[];
 }
+/**
+ * The locales whose values help translate to `to`, nearest first: the fallback chain of `to`, then the other locales of
+ * the same language, those that share more subtags with `to` first, then the shorter codes (`pt` and `pt-PT` for `pt-BR`,
+ * `pt-BR` for `pt`). The source locale and `to` itself are never related.
+ */
+export declare function relatedLocales(to: LocaleCode, locales: readonly LocaleCode[], sourceLocale: LocaleCode, fallbacks: Readonly<Record<LocaleCode, LocaleCode>>): LocaleCode[];
 /** Plain markdown, with no provider-specific syntax. */
 export declare function renderPrompt(data: PromptData): string;
 //#endregion
@@ -1505,6 +1560,35 @@ interface Analysis {
   /** Usages whose key is not defined in the source locale. */
   readonly undefinedUsages: readonly Usage[];
 }
+/** Which unused keys `planUnused` deletes. */
+interface UnusedQuery {
+  /** Key glob: `*` inside a segment, `**` across segments. */
+  readonly glob?: string | undefined;
+  readonly namespace?: string | undefined;
+}
+/** An unused key the plan deletes, with the messages it removes. */
+interface UnusedKeyDeletion {
+  readonly key: KeyString;
+  /** One entry per message, in locale order. */
+  readonly messages: readonly {
+    readonly locale: LocaleCode;
+    readonly path: string;
+  }[];
+}
+/** An unused key left alone because fully dynamic usages in a scope (`keyPrefix`, namespace) may reach it. */
+interface KeptUnusedKey {
+  readonly key: KeyString;
+  readonly usages: readonly Usage[];
+}
+/** The bulk delete of unused keys, as data: review it (dry run), then pass `plan` to `apply`. */
+interface UnusedDeletion {
+  /** Deletes `keys` in every locale, in place. Its warnings list the fully dynamic usages that may reach any key. */
+  readonly plan: Plan;
+  /** Sorted by key. */
+  readonly keys: readonly UnusedKeyDeletion[];
+  /** Sorted by key. */
+  readonly kept: readonly KeptUnusedKey[];
+}
 interface ProjectExplanation {
   readonly name: string;
   readonly root: string;
@@ -1648,6 +1732,8 @@ interface Project {
   /** True when the path is a resource file or a scanned source file. */
   readonly owns: (path: string) => boolean;
   readonly plan: (ops: readonly EditOp[]) => Plan;
+  /** Plans the deletion of the unused keys (`analyze().unused`), minus `ignoreKeys` and keys a scoped fully dynamic usage may reach. */
+  readonly planUnused: (query?: UnusedQuery) => UnusedDeletion;
   readonly apply: (plan: Plan, options?: {
     readonly answers?: Answers | undefined;
   }) => Promise<ApplyResult>;
@@ -1714,6 +1800,7 @@ interface PluginFile {
     readonly resources?: readonly ResourceSpec[] | undefined;
     readonly namespace?: NamespaceOptions | undefined;
     readonly keyStyle?: "auto" | "nested" | "flat" | undefined;
+    readonly keySeparator?: KeySeparator | undefined;
   } | undefined;
   readonly scanners?: {
     readonly calls?: readonly CallSpec[] | undefined;
@@ -1789,4 +1876,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, BaselineSummary, 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, ParamsSource, 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, PromptIssue, PromptItem, PromptOptions, RegexScannerSpec, ReportInput, ReportSummary, Reporter, ReporterContext, ReporterLoader, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ReviewAuthor, ReviewComment, ReviewData, ReviewFile, ReviewFilter, ReviewOptions, ReviewState, ReviewStore, ReviewThread, ReviewType, ScanContext, ScanResult, Scanner, ScannerEntry, SchemaIssue, Scope, SearchMatch, SearchOptions, SerializableConfig, Setup, Severity, SourceFile, TextEdit, TextRange, ThreadComment, TreeLeaf, Usage, UsageCandidate, UsageContext, UsageKind, UsageMatch, UsageOptions, UsageQuery, UserConfig, WireDiagnostic, WireRange, WriteOptions, X18nError };
+export type { Analysis, Answers, ApplyResult, ArgSource, BaselineSummary, 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, KeptUnusedKey, KeyContext, KeyId, KeyInfo, KeyQuery, KeySeparator, 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, ParamsSource, 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, PromptIssue, PromptItem, PromptOptions, RegexScannerSpec, RelatedValue, ReportInput, ReportSummary, Reporter, ReporterContext, ReporterLoader, ResolveConfigOptions, ResolvedConfig, Resource, ResourceBlock, ResourceCandidate, ResourceId, ResourceNode, ResourceSpec, ResourceTransform, ResourceTransformContext, ReviewAuthor, ReviewComment, ReviewData, ReviewFile, ReviewFilter, ReviewOptions, ReviewState, ReviewStore, ReviewThread, ReviewType, ScanContext, ScanResult, Scanner, ScannerEntry, SchemaIssue, Scope, SearchMatch, SearchOptions, SerializableConfig, Setup, Severity, SourceFile, TextEdit, TextRange, ThreadComment, TreeLeaf, UnusedDeletion, UnusedKeyDeletion, UnusedQuery, Usage, UsageCandidate, UsageContext, UsageKind, UsageMatch, UsageOptions, UsageQuery, UserConfig, WireDiagnostic, WireRange, WriteOptions, X18nError };