@x18n/core 0.0.2 → 0.0.5

package/dist/index.d.mts

@@ -0,0 +1,1316 @@
+import * as v from "valibot";
+//#region src/errors.d.ts
+/**
+ * Every coded error. Groups: 0xxx config, 1xxx plugin, 2xxx discovery and parse,
+ * 3xxx scanning, 4xxx edits, 5xxx reviews.
+ */
+type ErrorCode = "X18N0001" | "X18N0002" | "X18N0003" | "X18N1001" | "X18N1002" | "X18N1003" | "X18N1004" | "X18N2001" | "X18N2002" | "X18N2003" | "X18N2004" | "X18N3001" | "X18N4001" | "X18N4002" | "X18N4003" | "X18N4004" | "X18N4005" | "X18N4006" | "X18N4007" | "X18N4008";
+export declare const errorCodes: { readonly [C in ErrorCode]: {
+  readonly message: string;
+  readonly hint: string;
+}; };
+interface ErrorInfo {
+  readonly code: ErrorCode;
+  readonly message: string;
+  readonly hint: string;
+  readonly docs: string;
+}
+export declare class X18nError extends Error {
+  readonly code: ErrorCode;
+  readonly hint: string;
+  readonly docs: string;
+  readonly details: readonly string[];
+  constructor(code: ErrorCode, detail?: string, details?: readonly string[]);
+  toJSON(): ErrorInfo;
+}
+export declare function isX18nError(error: unknown): error is X18nError;
+//#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;
+  readonly pluralCategories: 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;
+  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[];
+};
+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 `data` shape. */
+export declare const contractVersion = 1;
+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;
+}
+interface GlobOptions {
+  readonly ignore?: readonly string[] | undefined;
+  /** Honour the project's `.gitignore` files. */
+  readonly gitignore?: boolean | undefined;
+}
+interface FileEvent {
+  readonly type: "create" | "change" | "delete";
+  /** Posix path relative to the host root. */
+  readonly path: string;
+}
+/** Persistent key-value store. Values are JSON text. */
+interface CacheStore {
+  readonly get: (key: string) => Promise<string | undefined>;
+  readonly set: (key: string, value: string) => Promise<void>;
+}
+interface Logger {
+  readonly info: (message: string) => void;
+  readonly warn: (message: string) => void;
+  readonly error: (message: string) => void;
+}
+/** Gives a project file access, globbing, watching and caching. All paths are posix and relative to `root`. */
+interface Host {
+  readonly root: string;
+  readonly readFile: (path: string) => Promise<string | undefined>;
+  readonly writeFile: (path: string, content: string) => Promise<void>;
+  readonly deleteFile: (path: string) => Promise<void>;
+  readonly glob: (patterns: readonly string[], options?: GlobOptions) => Promise<string[]>;
+  readonly watch?: ((patterns: readonly string[], onChange: (events: readonly FileEvent[]) => void) => Disposable) | undefined;
+  readonly cache?: CacheStore | undefined;
+  readonly logger?: Logger | undefined;
+}
+//#endregion
+//#region src/types/plugin.d.ts
+interface ConfigContext {
+  readonly host: Host;
+  /** The user config as written, before presets ran. */
+  readonly user: SerializableConfig;
+}
+interface ManifestReader {
+  readonly id: string;
+  /** File name relative to the project root, for example 'package.json'. */
+  readonly file: string;
+  /** Dependency names listed in the manifest. */
+  readonly read: (text: string) => readonly string[];
+}
+interface DetectContext {
+  readonly host: Host;
+  readonly dependencies: ReadonlySet<string>;
+  readonly hasDependency: (name: string) => boolean;
+  readonly hasAnyDependency: (names: readonly string[]) => boolean;
+  readonly fileExists: (pattern: string) => Promise<boolean>;
+}
+interface ResourceCandidate {
+  readonly path: string;
+  readonly locale: LocaleCode;
+  readonly namespace: string | undefined;
+  /** Format id hint; otherwise picked by extension. */
+  readonly format?: string | undefined;
+  readonly block?: ResourceBlock | undefined;
+  readonly readonly?: boolean | undefined;
+}
+interface FinderContext {
+  readonly host: Host;
+  readonly config: ResolvedConfig;
+  /** Extensions of every registered format. */
+  readonly extensions: readonly string[];
+}
+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. */
+  readonly resolveNew?: ((target: {
+    readonly locale: LocaleCode;
+    readonly namespace: string | undefined;
+  }, ctx: FinderContext) => string | undefined) | undefined;
+}
+interface FormatContext {
+  readonly path: string;
+  readonly locale: LocaleCode;
+  readonly namespace: string | undefined;
+  readonly indent: number | "tab" | undefined;
+}
+interface ParseResult {
+  readonly tree: MessageTree;
+  /** Ranges of keys and values (leaves and objects), keyed by `pathId(storedPath)`. */
+  readonly ranges?: ReadonlyMap<string, NodeRange> | undefined;
+}
+type MessageOp = {
+  readonly type: "set";
+  readonly path: readonly string[];
+  readonly value: MessageLeaf;
+} | {
+  readonly type: "delete";
+  readonly path: readonly string[];
+};
+interface Format {
+  readonly id: string;
+  /** File extensions without the dot. */
+  readonly extensions: readonly string[];
+  readonly parse: (text: string, ctx: FormatContext) => ParseResult;
+  /** Edits text in place. Preferred; keeps comments and layout. Ops run in order. */
+  readonly edit?: ((text: string, ops: readonly MessageOp[], ctx: FormatContext) => readonly TextEdit[]) | undefined;
+  /** Full serialization. Used to create files, and when `edit` is missing. */
+  readonly serialize?: ((tree: MessageTree, ctx: FormatContext) => string) | undefined;
+}
+interface SourceFile {
+  readonly path: string;
+  readonly text: string;
+  /** Extension without the dot. */
+  readonly extension: string;
+}
+interface ScanContext {
+  readonly config: ResolvedConfig;
+  /** Call specs after `usage.ignoreCallees`. */
+  readonly calls: readonly CallSpec[];
+}
+interface UsageCandidate {
+  readonly raw: string;
+  readonly range: TextRange;
+  readonly kind: UsageKind;
+  readonly dynamic: false | "prefix" | "unknown";
+  readonly namespace?: string | undefined;
+  readonly keyPrefix?: string | undefined;
+  readonly locale?: LocaleCode | undefined;
+}
+/** A region of code with a default namespace or key prefix. */
+interface Scope {
+  readonly range: TextRange;
+  readonly namespace?: string | undefined;
+  readonly keyPrefix?: string | undefined;
+}
+interface HardString {
+  readonly text: string;
+  /** Range of the whole literal, quotes included: what a replacement rewrites. */
+  readonly range: TextRange;
+  readonly kind: string;
+  /** Template arguments: `${name}` becomes `{name}` in the message, the expression is passed to the call. */
+  readonly args?: readonly {
+    readonly name: string;
+    readonly expression: string;
+  }[] | undefined;
+  /** Attribute name for attribute kinds. */
+  readonly attribute?: string | undefined;
+}
+interface ScanResult {
+  readonly usages: readonly UsageCandidate[];
+  readonly scopes?: readonly Scope[] | undefined;
+  /** Positions where completion of a key makes sense. */
+  readonly keySlots?: readonly TextRange[] | undefined;
+  /** Hard strings found while walking the same AST, for extraction. */
+  readonly hardStrings?: readonly HardString[] | undefined;
+}
+interface Scanner {
+  readonly id: string;
+  /** File extensions without dot. `*` matches every file. */
+  readonly extensions: readonly string[];
+  readonly runtime?: "any" | "node" | undefined;
+  readonly scan: (file: SourceFile, ctx: ScanContext) => ScanResult | Promise<ScanResult>;
+}
+interface Extractor {
+  readonly id: string;
+  /** Replacement templates per hard-string kind for this library. */
+  readonly templates: readonly ExtractTemplate[];
+}
+interface DiagnosticInput {
+  readonly message: string;
+  readonly key?: KeyString | undefined;
+  readonly locale?: LocaleCode | undefined;
+  /** Defaults to the message range of `key` in `locale` (or the source locale). */
+  readonly location?: Location | undefined;
+  readonly severity?: Severity | undefined;
+  readonly fixes?: readonly Fix[] | undefined;
+}
+interface LocaleCoverage {
+  readonly locale: LocaleCode;
+  readonly total: number;
+  readonly translated: number;
+  readonly missing: readonly KeyString[];
+  readonly empty: readonly KeyString[];
+  /** Translated keys whose message last changed before the source message. */
+  readonly outdated: readonly KeyString[];
+}
+/** When a message last changed, as a history provider knows it. */
+interface MessageChange {
+  /** Milliseconds since the epoch. `Infinity` for a change not yet known to the provider. */
+  readonly updatedAt: number;
+  /** A provider revision, such as a commit sha. */
+  readonly revision?: string | undefined;
+  readonly author?: string | undefined;
+  /** The value the provider knows. A different current value is a local change. */
+  readonly value?: MessageLeaf | undefined;
+}
+interface MessageHistory {
+  readonly changes: ReadonlyMap<KeyString, ReadonlyMap<LocaleCode, MessageChange>>;
+  /** The value a message had at a time, for translate prompts of stale messages. */
+  readonly valueAt?: ((key: KeyString, locale: LocaleCode, at: number) => MessageLeaf | undefined) | undefined;
+}
+interface HistoryContext {
+  readonly host: Host;
+  readonly config: ResolvedConfig;
+  readonly resources: readonly Resource[];
+  /** Messages of a resource in another version of its file, read like the current file. Undefined for embedded resources and parse errors. */
+  readonly messagesIn: (resource: Resource, text: string) => ReadonlyMap<KeyString, MessageLeaf> | undefined;
+}
+interface HistoryProvider {
+  readonly id: string;
+  /** Reads when each message last changed. Undefined when the provider has nothing for this project. */
+  readonly load: (ctx: HistoryContext) => Promise<MessageHistory | undefined>;
+  /** Calls `onChange` when the history changes outside resource files, for example on a commit. */
+  readonly watch?: ((ctx: HistoryContext, onChange: () => void) => Disposable) | undefined;
+}
+interface CheckContext {
+  readonly config: ResolvedConfig;
+  readonly sourceLocale: LocaleCode;
+  readonly locales: readonly LocaleCode[];
+  readonly resources: readonly Resource[];
+  /** Options from `[severity, options]` in config. */
+  readonly options: JsonObject;
+  /** True when at least one scanner is registered. */
+  readonly hasScanners: boolean;
+  readonly keys: () => readonly KeyString[];
+  readonly messages: (locale?: LocaleCode) => Iterable<Message>;
+  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[];
+  readonly usages: () => Iterable<Usage>;
+  readonly coverage: () => readonly LocaleCoverage[];
+  readonly unused: () => readonly KeyString[];
+  /** Usages whose key is not defined in the source locale. */
+  readonly undefinedUsages: () => readonly Usage[];
+  readonly placeholders: (value: string) => readonly Placeholder[];
+  readonly placeholderSyntaxes: readonly PlaceholderSyntax[];
+  /** Errors reported by the `validate` of every placeholder syntax. */
+  readonly syntaxErrors: (value: string) => readonly string[];
+  readonly localeInfo: (code: LocaleCode) => LocaleInfo;
+  readonly text: (path: string) => string | undefined;
+  readonly hardStrings: () => Iterable<HardString & {
+    readonly path: string;
+  }>;
+  /** When a message last changed, from the history providers. Undefined until history is loaded. */
+  readonly history: (key: KeyString, locale: LocaleCode) => MessageChange | undefined;
+}
+interface Check {
+  readonly id: string;
+  readonly defaultSeverity: Severity | "off";
+  readonly description?: string | undefined;
+  readonly docs?: string | undefined;
+  readonly override?: boolean | undefined;
+  readonly run: (ctx: CheckContext) => Iterable<DiagnosticInput>;
+}
+interface ReportSummary {
+  readonly errors: number;
+  readonly warnings: number;
+  readonly infos: number;
+  readonly files: number;
+}
+interface ReportInput {
+  readonly project: string;
+  /** File text, for code frames and line numbers. */
+  readonly text: (path: string) => string | undefined;
+  readonly diagnostics: readonly Diagnostic[];
+  readonly coverage: readonly LocaleCoverage[];
+  readonly summary: ReportSummary;
+}
+interface ReporterContext {
+  /** Turns a project path into the path to print (relative to the cwd). */
+  readonly displayPath: (path: string, project: string) => string;
+  readonly color: boolean;
+}
+interface Reporter {
+  readonly id: string;
+  readonly override?: boolean | undefined;
+  readonly report: (inputs: readonly ReportInput[], ctx: ReporterContext) => string | Promise<string>;
+}
+interface PlaceholderSyntax {
+  readonly id: string;
+  readonly find: (value: string) => readonly Placeholder[];
+  /** Syntax errors in a value, for the `invalid-syntax` check. */
+  readonly validate?: ((value: string) => readonly string[]) | undefined;
+  /** Text used in prompts, for example `{name}`. */
+  readonly example?: string | undefined;
+  /** The placeholder name is another key (vue-i18n `@:key`, i18next `$t(key)`), which then counts as used. */
+  readonly reference?: boolean | undefined;
+  /** Names the library always passes, which a translation may leave out or add (vue-i18n `n` and `count`). */
+  readonly implicit?: readonly string[] | undefined;
+}
+interface KeyContext {
+  readonly path: string;
+}
+interface ResourceTransformContext {
+  readonly locale: LocaleCode;
+  readonly namespace: string | undefined;
+  readonly path: string;
+}
+/**
+ * Changes how a resource's tree maps to keys, for example Rails' top-level locale key
+ * or Chrome's `{ "name": { "message": "..." } }`. Edits go to the stored paths.
+ */
+interface ResourceTransform {
+  /** Whether the transform applies to a resource. Default: every resource. */
+  readonly applies?: ((ctx: ResourceTransformContext) => boolean) | undefined;
+  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[];
+}
+interface PromptDraft {
+  readonly rules: string[];
+  readonly notes: string[];
+}
+interface PromptContext {
+  readonly sourceLocale: LocaleCode;
+  readonly targetLocale: LocaleCode;
+  readonly localeInfo: LocaleInfo;
+}
+interface Plugin {
+  /** Unique, kebab-case. Built-ins use the `x18n:` prefix. */
+  readonly name: string;
+  readonly enforce?: "pre" | "post" | undefined;
+  /** Where the plugin can run. Default 'any'. */
+  readonly runtime?: "any" | "node" | undefined;
+  /** Change the config before it is final. Presets use this to set defaults. */
+  readonly config?: ((config: ConfigDraft, ctx: ConfigContext) => void | Promise<void>) | undefined;
+  readonly configResolved?: ((config: ResolvedConfig) => void) | undefined;
+  readonly manifests?: readonly ManifestReader[] | undefined;
+  readonly localeFinders?: readonly LocaleFinder[] | undefined;
+  readonly formats?: readonly Format[] | undefined;
+  readonly scanners?: readonly Scanner[] | undefined;
+  readonly extractors?: readonly Extractor[] | undefined;
+  readonly checks?: readonly Check[] | undefined;
+  readonly reporters?: readonly Reporter[] | undefined;
+  readonly placeholders?: readonly PlaceholderSyntax[] | undefined;
+  readonly histories?: readonly HistoryProvider[] | undefined;
+  /** Turns raw key text into canonical form. The first plugin that returns a value wins. */
+  readonly normalizeKey?: ((raw: string, ctx: KeyContext) => string | undefined) | undefined;
+  readonly derivedKeys?: readonly string[] | undefined;
+  readonly transformResource?: ResourceTransform | undefined;
+  readonly translatePrompt?: ((draft: PromptDraft, ctx: PromptContext) => void) | undefined;
+  /** Display data for a locale code. The first plugin that returns a value wins. */
+  readonly localeInfo?: ((code: LocaleCode) => Partial<LocaleInfo> | undefined) | undefined;
+}
+interface Preset {
+  readonly name: string;
+  /** Decides if the preset applies. 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;
+  readonly plugins: readonly (Plugin | Preset)[];
+}
+/** A preset factory as referenced by name from YAML and JSON configs. */
+type PresetFactory = (options?: JsonObject) => Preset;
+//#endregion
+//#region src/types/config.d.ts
+/** Where a value comes from: an argument, or a property of an object argument. */
+interface ArgSource {
+  readonly arg: number;
+  readonly property?: string | undefined;
+}
+/** Data that drives the AST scanners: which calls are translate calls and where the key is. */
+interface CallSpec {
+  /** Function or member path: 't', '$t', 'i18n.t', 'intl.formatMessage'. */
+  readonly callee: string | readonly string[];
+  /** 'call' (default): the key is an argument. 'selector': the argument is `$ => $.a.b`. 'accessor': member chain on a root. */
+  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 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 }`. */
+  readonly factory?: boolean | undefined;
+  /** For factories: the names of the returned translate functions. Default `['t']`. */
+  readonly returns?: readonly string[] | undefined;
+  /** Type names that mark a parameter or prop as a translate function: ['TFunction']. */
+  readonly types?: readonly string[] | undefined;
+}
+interface RegexScannerSpec {
+  /** File extensions, without dot. */
+  readonly extensions: readonly string[];
+  /** Patterns with a `{key}` placeholder (i18n-ally `usageMatchRegex`), or a regex whose first group is the key. */
+  readonly patterns: readonly string[];
+}
+interface ResourceSpec {
+  /** Path pattern with `{locale}`, `{locale?}`, `{namespace}`, `{namespaces}` and `{ext}` tokens and globs. */
+  readonly pattern: string;
+  readonly format?: string | undefined;
+  /** Fixed namespace for every matching file. */
+  readonly namespace?: string | undefined;
+  /** Fixed locale for every matching file, for patterns without `{locale}` (`package.nls.json`). */
+  readonly locale?: string | undefined;
+  /** Run matching JS/TS files in Node instead of reading them statically. Makes them read-only. */
+  readonly execute?: boolean | undefined;
+}
+type CheckLevel = Severity | "off";
+type CheckSetting = CheckLevel | readonly [CheckLevel, JsonObject];
+interface GlossaryEntry {
+  readonly term: string;
+  /** Translation per locale. */
+  readonly translations?: {
+    readonly [locale: string]: string;
+  } | undefined;
+  readonly note?: string | undefined;
+  readonly doNotTranslate?: boolean | undefined;
+}
+interface ExtractTemplate {
+  readonly template: string;
+  /** Hard-string kinds the template applies to, for example `jsx-text`. */
+  readonly kinds?: readonly string[] | undefined;
+  /** File globs the template applies to. */
+  readonly files?: readonly string[] | undefined;
+  /** Lines added once per file when missing, for example an import. */
+  readonly imports?: readonly string[] | undefined;
+}
+interface ExtractOptions {
+  /** Report hard strings as `hard-string` diagnostics. */
+  readonly autoDetect?: boolean | undefined;
+  readonly keygen?: "slug" | "source" | "random" | "empty" | undefined;
+  readonly keyCase?: "camel" | "snake" | "kebab" | "dot" | undefined;
+  /** Template with `{fileName}`, `{dirName}` or `{component}`. */
+  readonly keyPrefix?: string | undefined;
+  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. */
+  readonly ignore?: readonly string[] | undefined;
+  /** Ignored strings per file glob. */
+  readonly ignoreByFile?: {
+    readonly [glob: string]: readonly string[];
+  } | undefined;
+  readonly ignoreAttributes?: readonly string[] | undefined;
+  readonly ignoreCallees?: readonly string[] | undefined;
+  readonly templates?: readonly (string | ExtractTemplate)[] | undefined;
+}
+interface UsageOptions {
+  readonly include?: readonly string[] | undefined;
+  readonly exclude?: readonly string[] | undefined;
+  readonly calls?: readonly CallSpec[] | undefined;
+  readonly regex?: readonly RegexScannerSpec[] | undefined;
+  /** Callee names never counted as translate calls. */
+  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. */
+  readonly derivedKeys?: readonly string[] | undefined;
+}
+interface WriteOptions {
+  readonly sort?: false | "binary" | "locale" | undefined;
+  readonly indent?: number | "tab" | undefined;
+  /** i18n-ally `keepFulfilled`: `set` in one locale adds the key with an empty value to the others. */
+  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;
+  /** Namespace of keys written without one. */
+  readonly default?: 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;
+}
+type NamespaceFromPath = NonNullable<NamespaceOptions["fromPath"]>;
+type PluginSpecifier = string | readonly [string, JsonObject];
+/** The part of the config that YAML and JSON files can hold. Validated by `ConfigSchema`. */
+interface SerializableConfig {
+  readonly $schema?: string | undefined;
+  /** Project root, relative to the config file. */
+  readonly root?: string | undefined;
+  /** Project name in a monorepo. Default: the directory name. */
+  readonly name?: string | undefined;
+  readonly sourceLocale?: string | undefined;
+  /** Locale codes as written in paths. Filters the found locales. */
+  readonly locales?: readonly string[] | undefined;
+  readonly ignoreLocales?: readonly string[] | undefined;
+  /** `'auto'` detects built-in presets from the project's dependencies. */
+  readonly presets?: "auto" | readonly PluginSpecifier[] | undefined;
+  readonly plugins?: readonly PluginSpecifier[] | undefined;
+  readonly resources?: readonly ResourceSpec[] | undefined;
+  /** Explicit format id per file extension (without dot). */
+  readonly formats?: {
+    readonly [extension: string]: string;
+  } | undefined;
+  readonly keyStyle?: "auto" | "nested" | "flat" | undefined;
+  readonly namespace?: NamespaceOptions | undefined;
+  readonly usage?: UsageOptions | undefined;
+  readonly write?: WriteOptions | undefined;
+  readonly extract?: ExtractOptions | undefined;
+  /** Overrides on top of the `recommended` check set. */
+  readonly checks?: {
+    readonly [checkId: string]: CheckSetting;
+  } | undefined;
+  /** Turn every warning into an error. */
+  readonly strict?: boolean | undefined;
+  /** Keys (globs) excluded from all checks. */
+  readonly ignoreKeys?: readonly string[] | undefined;
+  readonly glossary?: readonly GlossaryEntry[] | undefined;
+  /** History providers for stale translations. `false` turns every provider off. Options of a provider sit under its key, such as `git: { maxDepth, since }` (or `git: false`). */
+  readonly history?: boolean | HistoryOptions | undefined;
+  /** Monorepo: directories (globs) that are projects inheriting this config. */
+  readonly projects?: readonly string[] | undefined;
+}
+/** Check ids of known plugins, for autocompletion. Plugins add theirs through declaration merging. */
+interface CheckIds {}
+/** Options of plugins under their own config key. Plugins add theirs through declaration merging. */
+interface PluginConfigs {}
+/** Options of history providers under their own key, such as `git`. Providers add theirs through declaration merging. */
+interface HistoryConfigs {}
+type HistoryOptions = Partial<HistoryConfigs>;
+interface HistorySettings extends HistoryOptions {
+  /** Providers asked before those of plugins. */
+  readonly providers: readonly HistoryProvider[];
+}
+type PresetOption = Preset | PluginSpecifier | false | undefined;
+type PluginOption = Plugin | Preset | PluginSpecifier | false | undefined;
+/** The config accepted by `defineConfig`: the serializable part plus plugin objects. */
+interface UserConfig extends Omit<SerializableConfig, "presets" | "plugins" | "checks" | "history"> {
+  readonly presets?: "auto" | readonly PresetOption[] | undefined;
+  /** History providers for stale translations: `false` turns them off; provider options such as `git` sit under their key; `providers` adds providers asked first. */
+  readonly history?: boolean | (HistoryOptions & {
+    readonly providers?: readonly HistoryProvider[] | undefined;
+  }) | undefined;
+  readonly plugins?: readonly PluginOption[] | undefined;
+  readonly checks?: { readonly [K in keyof CheckIds]?: CheckSetting; } & {
+    readonly [checkId: string]: CheckSetting;
+  } | undefined;
+  readonly pluginConfigs?: Partial<PluginConfigs> | undefined;
+}
+type ConfigOrigin = "default" | "user" | "parent" | `plugin:${string}`;
+/** The final config of one project. Every field is set. */
+interface ResolvedConfig {
+  readonly name: string;
+  readonly sourceLocale: string;
+  readonly locales: readonly string[] | undefined;
+  readonly ignoreLocales: readonly string[];
+  readonly resources: readonly ResourceSpec[];
+  readonly formats: {
+    readonly [extension: string]: string;
+  };
+  readonly keyStyle: "auto" | "nested" | "flat";
+  readonly namespace: {
+    readonly separator: string;
+    readonly default: string | undefined;
+    readonly fromPath: NamespaceFromPath;
+  };
+  readonly usage: {
+    readonly include: readonly string[];
+    readonly exclude: readonly string[];
+    readonly calls: readonly CallSpec[];
+    readonly regex: readonly RegexScannerSpec[];
+    readonly ignoreCallees: readonly string[];
+    readonly keysInUse: readonly string[];
+    readonly derivedKeys: readonly string[];
+  };
+  readonly write: {
+    readonly sort: false | "binary" | "locale";
+    readonly indent: number | "tab" | undefined;
+    readonly keepFilled: boolean;
+  };
+  readonly extract: ExtractOptions;
+  readonly checks: {
+    readonly [checkId: string]: CheckSetting;
+  };
+  readonly strict: boolean;
+  readonly ignoreKeys: readonly string[];
+  readonly glossary: readonly GlossaryEntry[];
+  readonly history: false | HistorySettings;
+  readonly pluginConfigs: Partial<PluginConfigs>;
+  /** Origin of each top-level value, for `explain()`. */
+  readonly origins: {
+    readonly [key: string]: ConfigOrigin;
+  };
+}
+/** 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/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;
+export declare function definePreset<const T extends Preset>(preset: T): T;
+export declare function defineConfig(config: UserConfig & { readonly [K in keyof PluginConfigs]?: PluginConfigs[K]; }): UserConfig;
+//#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;
+/** Replaces the `from` prefix of `key` with `to`. */
+export declare function replaceKeyPrefix(key: KeyString, from: KeyString, to: KeyString): KeyString;
+/**
+ * Glob over paths. `**` spans separators, `*` and `?` stay inside a segment,
+ * `{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 posix file paths. */
+export declare function pathMatcher(globs: readonly string[]): (path: string) => boolean;
+//#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;
+/** Codes that differ only in spelling (`zh_CN` and `zh-cn`), the same after a lenient normalization. */
+export declare function localeSpellingKey(code: LocaleCode): string;
+//#endregion
+//#region src/memory-host.d.ts
+interface MemoryHost extends Host {
+  readonly files: Map<string, string>;
+}
+/** A host over in-memory files, for tests, demos and agents that pass content directly. */
+export declare function createMemoryHost(initial?: Readonly<Record<string, string>>, root?: string): MemoryHost;
+//#endregion
+//#region src/message-tree.d.ts
+export declare function isMessageLeaf(value: unknown): value is MessageLeaf;
+/** Checks parsed data (for example from `JSON.parse`) before it enters the project. */
+export declare function isMessageTree(value: unknown): value is MessageTree;
+/** Stable id of a stored property path, the key of `ParseResult.ranges`. */
+export declare function pathId(path: readonly string[]): string;
+interface TreeLeaf {
+  readonly path: readonly string[];
+  readonly value: MessageLeaf;
+}
+export declare function walkLeaves(tree: MessageTree, prefix?: readonly string[]): Generator<TreeLeaf>;
+/** Applies ops to a copy of the tree. Parent objects left empty are removed. */
+export declare function applyMessageOps(tree: MessageTree, ops: readonly MessageOp[]): MessageTree;
+/** Sorts keys at every level. */
+export declare function sortTree(tree: MessageTree, compare: (a: string, b: string) => number): MessageTree;
+/** Builds a nested or flat tree from leaves. */
+export declare function buildTree(leaves: Iterable<TreeLeaf>): MessageTree;
+//#endregion
+//#region src/overlay-host.d.ts
+interface OverlayHost extends Host {
+  /** Shadows the file content, for example with an unsaved editor buffer. */
+  readonly setOverlay: (path: string, content: string) => void;
+  readonly clearOverlay: (path: string) => void;
+  readonly hasOverlay: (path: string) => boolean;
+}
+/** Wraps a host so open editor buffers shadow the content on disk. */
+export declare function createOverlayHost(base: Host): OverlayHost;
+//#endregion
+//#region src/plugins.d.ts
+export declare function isPreset(value: Plugin | Preset): value is Preset;
+interface CapabilityConflict {
+  readonly capability: "format" | "scanner";
+  readonly extension: string;
+  readonly winner: string;
+  readonly loser: string;
+}
+/** The capabilities of the final plugin list, indexed for the project engine. */
+interface PluginRegistry {
+  readonly plugins: readonly Plugin[];
+  readonly formats: readonly Format[];
+  readonly finders: readonly LocaleFinder[];
+  readonly scanners: readonly Scanner[];
+  readonly checks: ReadonlyMap<string, Check>;
+  readonly reporters: ReadonlyMap<string, Reporter>;
+  readonly placeholders: readonly PlaceholderSyntax[];
+  readonly manifests: readonly ManifestReader[];
+  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. */
+  readonly formatFor: (path: string, hint?: string) => Format | undefined;
+  readonly formatById: (id: string) => Format | undefined;
+  readonly scannersFor: (path: string) => readonly Scanner[];
+}
+export declare function extensionOf(path: string): string;
+export declare function createRegistry(input: readonly Plugin[], config: Pick<ResolvedConfig, "formats">): PluginRegistry;
+//#endregion
+//#region src/project/prompt.d.ts
+interface PromptOptions {
+  /** Key glob, or a list of keys. */
+  readonly keys?: string | readonly KeyString[] | undefined;
+  readonly namespace?: string | undefined;
+  /** Items per prompt. Default 50. */
+  readonly limit?: number | undefined;
+  /** Offset from `nextCursor` of the previous prompt. */
+  readonly cursor?: string | undefined;
+  /** Include code around usages. Default true. */
+  readonly context?: boolean | undefined;
+  /** Translate prompts: add stale translations (load history first). */
+  readonly stale?: boolean | undefined;
+}
+interface UsageContext {
+  readonly path: string;
+  readonly line: number;
+  readonly snippet: string;
+}
+interface PromptItem {
+  readonly key: KeyString;
+  readonly source: string;
+  readonly placeholders: readonly string[];
+  /** 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. */
+  readonly previousSource?: string | undefined;
+  readonly context: readonly UsageContext[];
+}
+interface PromptData {
+  readonly kind: "translate" | "review";
+  readonly project: string;
+  readonly from: LocaleCode;
+  readonly to: LocaleCode;
+  readonly targetName: string | undefined;
+  readonly total: number;
+  readonly remaining: number;
+  readonly nextCursor: string | undefined;
+  readonly rules: readonly string[];
+  readonly notes: readonly string[];
+  readonly glossary: readonly {
+    readonly term: string;
+    readonly translation: string | undefined;
+    readonly note: string | undefined;
+    readonly doNotTranslate: boolean;
+  }[];
+  readonly examples: readonly {
+    readonly key: KeyString;
+    readonly source: string;
+    readonly target: string;
+  }[];
+  readonly items: readonly PromptItem[];
+  readonly instructions: readonly string[];
+}
+/** Plain markdown, with no provider-specific syntax. */
+export declare function renderPrompt(data: PromptData): string;
+//#endregion
+//#region src/resolve.d.ts
+/** Plugins that are always on, and presets that `'auto'` and names refer to. Passed in by the caller. */
+interface Builtins {
+  readonly plugins: readonly Plugin[];
+  readonly presets: {
+    readonly [name: string]: PresetFactory;
+  };
+}
+interface ResolveConfigOptions {
+  readonly host: Host;
+  readonly config: UserConfig;
+  /** Root config of a monorepo, inherited by this project. */
+  readonly parent?: UserConfig | undefined;
+  readonly builtins: Builtins;
+  /** Default project name. */
+  readonly name?: string | undefined;
+  /** Loads string plugin specifiers. Without it, string plugins are a config error. */
+  readonly loadPlugin?: ((specifier: string, options: JsonObject | undefined) => Promise<Plugin | Preset>) | undefined;
+  readonly runtime?: "node" | "browser" | undefined;
+  /** Extra directories (relative to the host root) whose manifests count for detection, such as the workspace root. */
+  readonly manifestRoots?: readonly string[] | undefined;
+}
+interface PresetExplanation {
+  readonly name: string;
+  readonly reason: "listed" | "detected" | "not-detected" | "after-exclusive";
+}
+interface Setup {
+  readonly config: ResolvedConfig;
+  readonly registry: PluginRegistry;
+  readonly presets: readonly PresetExplanation[];
+  /** Plugins skipped because they cannot run in this runtime. */
+  readonly skipped: readonly {
+    readonly name: string;
+    readonly reason: string;
+  }[];
+}
+export declare function resolveConfig(options: ResolveConfigOptions): Promise<Setup>;
+//#endregion
+//#region src/types/project.d.ts
+interface KeyQuery {
+  /** Key glob: `*` inside a segment, `**` across segments. */
+  readonly glob?: string | undefined;
+  readonly namespace?: string | undefined;
+  /** Only keys missing (or empty) in this locale. */
+  readonly missing?: LocaleCode | undefined;
+  /** Only keys without usages. */
+  readonly unused?: boolean | undefined;
+}
+interface UsageMatch {
+  readonly usage: Usage;
+  /** True for prefix usages that may refer to the key. */
+  readonly possible: boolean;
+}
+interface UsageQuery {
+  readonly key?: KeyString | undefined;
+  /** Every usage of a key under this prefix (subtree). */
+  readonly prefix?: KeyString | undefined;
+  readonly path?: string | undefined;
+}
+interface KeyInfo {
+  readonly key: KeyString;
+  readonly namespace: string | undefined;
+  readonly path: readonly string[];
+  /** One message per locale that has the key, source locale first. */
+  readonly messages: readonly Message[];
+  readonly missing: readonly LocaleCode[];
+  readonly usages: readonly UsageMatch[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+/** The key, or the resource node, under a position. */
+type KeyTarget = {
+  readonly type: "key";
+  readonly key: KeyString;
+  readonly range: TextRange;
+  readonly source: "usage" | "resource";
+  readonly usage?: Usage | undefined;
+} | {
+  readonly type: "subtree";
+  readonly key: KeyString;
+  readonly range: TextRange;
+  readonly source: "resource";
+};
+/** A key or parent node in a resource file, with its ranges. */
+interface ResourceNode {
+  readonly key: KeyString;
+  readonly range: NodeRange;
+  /** False for parent objects. */
+  readonly leaf: boolean;
+  readonly locale: LocaleCode;
+  readonly path: string;
+}
+interface Analysis {
+  readonly revision: number;
+  readonly diagnostics: readonly Diagnostic[];
+  readonly coverage: readonly LocaleCoverage[];
+  readonly unused: readonly KeyString[];
+  /** Usages whose key is not defined in the source locale. */
+  readonly undefinedUsages: readonly Usage[];
+}
+interface ProjectExplanation {
+  readonly name: string;
+  readonly root: string;
+  readonly presets: readonly PresetExplanation[];
+  readonly plugins: readonly string[];
+  readonly skipped: readonly {
+    readonly name: string;
+    readonly reason: string;
+  }[];
+  readonly finders: readonly {
+    readonly id: string;
+    readonly resources: readonly string[];
+  }[];
+  /** Candidates dropped because an earlier finder already returned the same resource. */
+  readonly duplicates: readonly {
+    readonly path: string;
+    readonly finder: string;
+    readonly keptFrom: string;
+  }[];
+  readonly formats: readonly {
+    readonly id: string;
+    readonly extensions: readonly string[];
+    readonly resources: number;
+  }[];
+  readonly scanners: readonly {
+    readonly id: string;
+    readonly extensions: readonly string[];
+    readonly files: number;
+  }[];
+  readonly conflicts: readonly CapabilityConflict[];
+  readonly errors: readonly (ErrorInfo & {
+    readonly path?: string | undefined;
+  })[];
+  readonly config: ResolvedConfig;
+}
+type FileChange = {
+  readonly type: "edit";
+  readonly path: string;
+  readonly edits: readonly TextEdit[];
+} | {
+  readonly type: "create";
+  readonly path: string;
+  readonly content: string;
+} | {
+  readonly type: "delete";
+  readonly path: string;
+};
+interface DecisionOption {
+  readonly id: string;
+  readonly label: string;
+}
+/** A question in a plan that a surface must answer before apply. */
+interface Decision {
+  readonly id: string;
+  readonly message: string;
+  readonly options: readonly DecisionOption[];
+  /** The option picked by `--yes`. */
+  readonly default: string;
+}
+interface Plan {
+  readonly id: string;
+  readonly revision: number;
+  readonly ops: readonly EditOp[];
+  readonly changes: readonly FileChange[];
+  readonly decisions: readonly Decision[];
+  readonly warnings: readonly string[];
+  /** Keys whose messages or usages the plan changes. */
+  readonly keys: readonly KeyString[];
+}
+interface Answers {
+  readonly [decisionId: string]: string;
+}
+interface ApplyResult {
+  readonly revision: number;
+  readonly changes: readonly FileChange[];
+}
+interface ProjectChange {
+  readonly revision: number;
+  readonly paths: readonly string[];
+  readonly keys: readonly KeyString[];
+}
+interface FileScan {
+  readonly path: string;
+  readonly result: ScanResult;
+}
+interface Project {
+  readonly name: string;
+  readonly config: ResolvedConfig;
+  /** Resolves when discovery, parse, scan and index are done. */
+  readonly ready: Promise<void>;
+  readonly revision: number;
+  readonly locales: readonly LocaleCode[];
+  readonly sourceLocale: LocaleCode;
+  readonly resources: readonly Resource[];
+  /** True when keys carry a namespace (`ns:key`). */
+  readonly namespaced: boolean;
+  readonly reporters: ReadonlyMap<string, Reporter>;
+  readonly placeholderSyntaxes: readonly PlaceholderSyntax[];
+  /** Extraction templates: config `extract.templates` first, then those of presets. */
+  readonly extractTemplates: readonly ExtractTemplate[];
+  readonly keys: (query?: KeyQuery) => KeyString[];
+  readonly get: (key: KeyString) => KeyInfo | undefined;
+  readonly message: (key: KeyString, locale: LocaleCode) => Message | undefined;
+  /** The message a usage of `key` shows: the key's own, or one of its derived keys (`item` → `item_other`). */
+  readonly lookup: (key: KeyString, locale: LocaleCode) => Message | undefined;
+  /** Parses user input such as `common:save` or `save` into a key string. */
+  readonly parseKey: (input: string) => KeyString;
+  readonly usages: (query?: UsageQuery) => UsageMatch[];
+  readonly keyAt: (path: string, offset: number) => KeyTarget | undefined;
+  /** Key and parent nodes of a resource file, in file order. */
+  readonly nodes: (path: string) => readonly ResourceNode[];
+  /** The nodes of a key (or parent) in every locale, source locale first. */
+  readonly locations: (key: KeyString) => readonly ResourceNode[];
+  /** Completion positions in a source file. */
+  readonly keySlots: (path: string) => readonly TextRange[];
+  readonly hardStrings: (path?: string) => readonly (HardString & {
+    readonly path: string;
+  })[];
+  readonly analyze: () => Analysis;
+  /** Loads history from the history providers, after `ready`. `watch` reloads it when a provider sees a change. Analysis runs again once it is loaded. */
+  readonly loadHistory: (options?: {
+    readonly watch?: boolean | undefined;
+  }) => Promise<void>;
+  /** When a message last changed. Undefined until history is loaded, and for messages without history. */
+  readonly history: (key: KeyString, locale: LocaleCode) => MessageChange | undefined;
+  /** The value a message had at a time (ms), from the provider that knows the message. */
+  readonly valueAt: (key: KeyString, locale: LocaleCode, at: number) => MessageLeaf | undefined;
+  /** Parts of a translate or review prompt for an agent or LLM; render with `renderPrompt`. */
+  readonly prompt: (kind: "translate" | "review", locale: LocaleCode, options?: PromptOptions) => PromptData;
+  readonly explain: () => ProjectExplanation;
+  readonly localeInfo: (code: LocaleCode) => LocaleInfo;
+  readonly text: (path: string) => string | undefined;
+  /** True when the path is a resource file or a scanned source file. */
+  readonly owns: (path: string) => boolean;
+  readonly plan: (ops: readonly EditOp[]) => Plan;
+  readonly apply: (plan: Plan, options?: {
+    readonly answers?: Answers | undefined;
+  }) => Promise<ApplyResult>;
+  /** Re-reads the given files. Hosts with `watch` call this; the LSP calls it for open buffers. */
+  readonly update: (events: readonly FileEvent[]) => Promise<ProjectChange | undefined>;
+  /** Starts watching through the host. */
+  readonly watch: () => void;
+  readonly onChange: (listener: (change: ProjectChange) => void) => () => void;
+  readonly dispose: () => void;
+}
+//#endregion
+//#region src/project/batch.d.ts
+/** A value whose placeholders differ from the source value of its key. */
+interface PlaceholderProblem {
+  readonly key: KeyString;
+  readonly locale: LocaleCode;
+  readonly missing: readonly string[];
+  readonly extra: readonly string[];
+}
+/** Parses the batch shape `{ "<locale>": { "<key>": "<value>" } }` (as in `x18n apply`) into set ops. */
+export declare function parseMessageBatch(project: Project, data: JsonValue): EditOp[];
+/** Set ops whose value drops or adds placeholders compared to the source value. */
+type PlaceholderComparer = (source: string, target: string) => {
+  readonly missing: string[];
+  readonly extra: string[];
+};
+/**
+ * Compares the placeholders of a target value with its source. Key references (`@:key`) are not
+ * parameters, and implicit names (vue-i18n `{n}` in plural messages) may be left out. Build it once per run.
+ */
+export declare function createPlaceholderComparer(syntaxes: readonly PlaceholderSyntax[], find?: (value: string) => readonly Placeholder[]): PlaceholderComparer;
+export declare function placeholderProblems(project: Project, ops: readonly EditOp[]): PlaceholderProblem[];
+//#endregion
+//#region src/project/project.d.ts
+interface CreateProjectOptions {
+  readonly host: Host;
+  readonly setup: Setup;
+}
+export declare function createProject(options: CreateProjectOptions): Project;
+//#endregion
+//#region src/schema.d.ts
+export declare function isJsonObject(value: unknown): value is JsonObject;
+/** Validates YAML and JSON configs, and the serializable part of TS configs. */
+export declare const ConfigSchema: v.GenericSchema<SerializableConfig>;
+/** A YAML plugin (`*.x18n-plugin.yml`): the declarative subset of the plugin API. */
+interface PluginFile {
+  readonly $schema?: string | undefined;
+  readonly name: string;
+  readonly detect?: {
+    readonly dependencies?: {
+      readonly any?: readonly string[] | undefined;
+      readonly all?: readonly string[] | undefined;
+    } | undefined;
+    readonly files?: readonly string[] | undefined;
+  } | undefined;
+  readonly exclusive?: boolean | undefined;
+  readonly config?: {
+    readonly sourceLocale?: string | undefined;
+    readonly locales?: readonly string[] | undefined;
+    readonly resources?: readonly ResourceSpec[] | undefined;
+    readonly namespace?: NamespaceOptions | undefined;
+    readonly keyStyle?: "auto" | "nested" | "flat" | undefined;
+  } | undefined;
+  readonly scanners?: {
+    readonly calls?: readonly CallSpec[] | undefined;
+    readonly regex?: readonly RegexScannerSpec[] | undefined;
+  } | undefined;
+  readonly scopes?: {
+    /** Regex whose first group is the namespace of the code after it (i18n-ally `scopeRangeRegex`). */
+    readonly regex: string;
+  } | undefined;
+  readonly derivedKeys?: readonly string[] | undefined;
+  readonly normalizeKey?: readonly {
+    readonly replace: {
+      readonly pattern: string;
+      readonly with: string;
+    };
+  }[] | undefined;
+  /** Placeholder shapes with `name` as the name: `{name}`, `{{name}}`, `%{name}`. */
+  readonly placeholders?: readonly string[] | undefined;
+  readonly localeInfo?: {
+    readonly [code: string]: {
+      readonly flag?: string | undefined;
+      readonly displayName?: string | undefined;
+    };
+  } | undefined;
+  readonly extract?: {
+    readonly templates?: readonly (string | ExtractTemplate)[] | undefined;
+  } | undefined;
+}
+export declare const PluginFileSchema: v.GenericSchema<PluginFile>;
+interface SchemaIssue {
+  readonly path: string;
+  readonly message: string;
+}
+/** Validates data against a schema and returns readable issues instead of throwing. */
+export declare function validate<T>(schema: v.GenericSchema<T>, data: unknown): {
+  readonly success: true;
+  readonly output: T;
+} | {
+  readonly success: false;
+  readonly issues: readonly SchemaIssue[];
+};
+//#endregion
+//#region src/text.d.ts
+/** One edit covering only the part that differs, so bytes outside it stay the same. */
+export declare function diffText(before: string, after: string): TextEdit[];
+/** Applies non-overlapping edits given against the same text. */
+export declare function applyTextEdits(text: string, edits: readonly TextEdit[]): string;
+interface LinePosition {
+  /** Zero-based. */
+  readonly line: number;
+  /** Zero-based, UTF-16 code units. */
+  readonly character: number;
+}
+/** Converts offsets to lines and back for one text. */
+interface LineIndex {
+  readonly position: (offset: number) => LinePosition;
+  readonly offset: (position: LinePosition) => number;
+  readonly line: (line: number) => string;
+  readonly lineCount: number;
+}
+/** Line index of a text, cached for the few texts used at a time (reporters, LSP ranges). */
+export declare function createLineIndex(text: string): LineIndex;
+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 };