intor-translator 1.0.14 → 1.1.0

package/dist/index.d.cts

@@ -1,421 +1,413 @@
-/**
- * Represents a locale identifier, such as 'en', 'zh-TW', or 'fr-FR'.
- *
- * @example
- * const locale: Locale = "en";
- */
-type Locale = string;
-/**
- * Represents a message namespace.
- * Typically used to group related messages, such as 'common', 'auth', or 'dashboard'.
- *
- * @example
- * const namespace: Namespace = "dashboard";
- */
-type Namespace = string;
-/**
- * Represents a single translatable message string.
- *
- * @example
- * const message: Message = "Hello World";
- */
-type Message = string;
-/**
- * A recursive replacement object used for interpolating values in message templates.
- *
- * Each key maps to a value that can be a string, number, or another nested `Replacement`.
- * This structure supports deep replacements such as `user.profile.link`.
- *
- * @example
- * const replacements: Replacement = {
- *   name: "intor",
- *   count: 5,
- *   user: {
- *     profile: {
- *       link: "https://example.com/avatar.png"
- *     }
- *   }
- * };
- */
-type Replacement = {
-    [key: string]: string | number | Replacement;
-};
-
-/** Represents primitive types supported in rich replacements. */
-type RichPrimitive = string | number | boolean | Date;
-/** Represents serializable objects that provide a custom string representation. */
-type RichSerializable = {
-    toString(): string;
-};
-/** A formatter function that takes a string chunk and returns any formatted output. */
-type RichFormatterFunction = (value: unknown, ...args: unknown[]) => unknown;
-/**
- * Possible value types for rich replacements.
- * Can be a primitive, serializable object, formatter function, or null/undefined.
- */
-type ReplacementValue = RichPrimitive | RichSerializable | RichFormatterFunction | null | undefined;
-/**
- * A recursive replacement object that supports rich replacement values,
- * allowing complex nested interpolation structures.
- *
- * @example
- * const replacements: RichReplacement = {
- *   name: "Alice",
- *   age: 30,
- *   isActive: true,
- *   birthday: new Date("1993-04-25"),
- *   formatter: (value, ...args) => `<b>${value}</b>`,
- *   nested: {
- *     score: 100,
- *     note: null,
- *   },
- * };
- */
-type RichReplacement = {
-    [key: string]: ReplacementValue;
-};
-
 /**
  * A nested message structure or a simple string message.
- * Used to represent either a plain message or an object containing more nested messages.
+ *
+ * - Used to represent either a plain message or an object containing more nested messages.
  *
  * @example
+ * ```ts
  * const greeting: NestedMessage = "Hello";
- *
  * const userMessages: NestedMessage = {
  *   profile: {
  *     greeting: "Hello, user!",
  *     farewell: "Goodbye!"
  *   }
  * };
+ * ```
  */
-type NestedMessage = Message | {
+type NestedMessage = string | {
     [key: string]: NestedMessage;
 };
 /**
- * A record of messages where keys are strings, and values can be strings or nested message objects.
- * Supports deep message trees like `errors.form.required`.
+ * Messages grouped by locale.
+ * Used to structure all available messages for multiple locales.
  *
- * @example
- * const messages: MessageRecord = {
- *   greeting: "Hello",
- *   user: {
- *     profile: {
- *       name: "Your Name"
- *     }
- *   }
- * };
- */
-type MessageRecord = Record<string, NestedMessage>;
-/**
- * A record of messages grouped by namespace.
- * Each namespace contains its own `MessageRecord` structure.
+ * - Each key is a locale string, e.g., "en" or "zh-TW".
+ * - Each value is a `NestedMessage`, allowing for deeply nested message objects.
  *
  * @example
- * const namespaceMessages: NamespaceMessages = {
- *   common: {
- *     hello: "Hello",
- *     goodbye: "Goodbye"
- *   },
- *   auth: {
- *     login: {
- *       success: "Login successful"
- *     }
- *   }
- * };
- */
-type NamespaceMessages = Record<Namespace, NestedMessage>;
-/**
- * Messages grouped by locale and then by namespace.
- * Used to structure all available messages for multiple locales and namespaces.
- *
- * @example
- * const messages: LocaleNamespaceMessages = {
+ * ```ts
+ * const messages: LocaleMessages = {
  *   en: {
- *     common: {
- *       welcome: "Welcome"
- *     },
+ *     welcome: "Welcome",
  *     auth: {
  *       login: {
- *         success: "Login successful"
+ *         success: "Login successful",
+ *         failure: "Login failed"
  *       }
  *     }
  *   },
  *   "zh-TW": {
- *     common: {
- *       welcome: "歡迎"
+ *     welcome: "歡迎",
+ *     auth: {
+ *       login: {
+ *         success: "登入成功",
+ *         failure: "登入失敗"
+ *       }
  *     }
  *   }
  * };
+ * ```
  */
-type LocaleNamespaceMessages = Record<Locale, NamespaceMessages>;
+type LocaleMessages = Record<string, {
+    [x: string]: NestedMessage;
+}>;
 /**
- * Merges messages from all locales into a single unified structure.
+ * Merges messages from all locales into a single unified structure,
+ * or extracts messages for a specific locale if `L` is provided.
  *
  * @example
+ * ```ts
  * const messages = {
- *   en: { auth: { login: "Login" } },
- *   zh: { auth: { logout: "登出" } },
+ *   en: { greeting: { morning: "morning" } },
+ *   zh: { greeting: { evening: "晚上好" } },
  * };
  *
- * type Result = UnionLocaleMessages<typeof messages>;
- * // Result: { auth: { login: "Login" } } | { auth: { logout: "登出" } }
- */
-type UnionLocaleMessages<M> = M[StrictLocaleKey<M>];
-
-/**
- * Extracts the locale keys from the messages object as string literals.
+ * // 1. Union of all locales
+ * UnionLocaleMessages<typeof messages>;
+ * // → { greeting: { morning: string; }; } | { greeting: { evening: string; }; }
  *
- * @example
- * type Locales = LocaleKey<{
- *   en: {};
- *   "zh-TW": {};
- * }>;
- * // Locales is "en" | "zh-TW"
+ * // 2. Messages for a specified locale
+ * UnionLocaleMessages<typeof messages, "en">; // → { greeting: { morning: string; }; }
+ * UnionLocaleMessages<typeof messages, "zh">; // → { greeting: { evening: string; }; }
+ *
+ * // 3. Fallback if M is not LocaleMessages
+ * UnionLocaleMessages // → unknown
+ * ```
  */
-type StrictLocaleKey<M> = keyof M & string;
+type LocalizedMessagesUnion<M = unknown, L extends keyof M | "union" = "union"> = M extends LocaleMessages ? L extends "union" ? M[Locale<M>] : M[L & keyof M] : unknown;
+
 /**
  * Extracts locale keys only when M is a valid messages object.
  *
- * When M is a concrete `LocaleNamespaceMessages`, the locale key
- * will be inferred as a union of its top-level keys like `"en" | "zh-TW"`.
+ * - When M is a concrete `LocaleMessages`,
+ * the locale key will be inferred as a union of its top-level keys like `"en" | "zh-TW"`.
  * Otherwise, falls back to a generic `string`.
  *
- * This helps retain intellisense when `messages` is provided,
+ * - This helps retain intellisense when `messages` is provided,
  * but avoids TypeScript errors when M is left as `unknown`.
  *
  * @example
- * type Locales = LocaleKey<{
+ * ```ts
+ * type Locales = Locale<{
  *   en: {};
  *   fr: {};
  * }>;
- * //   → "en" | "fr"
+ * // → "en" | "fr"
  *
- * type Fallback = LocaleKey<unknown>;
- * //   → string
+ * type Locales = Locale<unknown>;
+ * // → string
+ * ```
  */
-type LocaleKey<M = unknown> = M extends LocaleNamespaceMessages ? StrictLocaleKey<M> : string;
+type Locale<M = unknown> = M extends LocaleMessages ? keyof M & string : string;
 /**
  * A map that defines fallback locales for each base locale.
  *
- * When a message is missing for a given locale, the system will attempt to find the message
+ * - When a message is missing for a given locale, the system will attempt to find the message
  * by falling back to the locales listed here, in the specified order.
  *
  * @example
+ * ```ts
  * const fallbacks: FallbackLocalesMap = {
  *   "en-AU": ["en-GB", "en"],
  *   "zh-TW": ["zh-HK", "zh"]
  * };
+ * ```
  */
 type FallbackLocalesMap<L extends string = string> = Partial<Record<L, L[]>>;
 
 /**
- * Gets all dot-separated keys (including non-leaf nodes) from a nested object.
+ * Represents a recursive replacement object used for interpolating values in message templates.
+ *
+ * - Each key can be any value (`string`, `number`, `boolean`, `Date`, `function`, nested object, etc.).
+ * - Supports nested structures for complex interpolation.
+ * - Can be used directly with `intl-messageformat` or custom format handlers.
  *
  * @example
- * NodeKeys<{ a: { b: { c: string }, d: string } }> → "a" | "a.b" | "a.b.c" | "a.d"
+ * const replacements: Replacement = {
+ *   name: "Alice",
+ *   count: 5,
+ *   nested: {
+ *     score: 100
+ *   },
+ *   formatter: (value: unknown) => `<b>${value}</b>`
+ * };
  */
-type NodeKeys<M> = M extends object ? {
-    [K in keyof M]: K extends string ? `${K}` | `${K}.${NodeKeys<M[K]>}` : never;
-}[keyof M] : never;
+type Replacement = Record<string, unknown>;
+
 /**
  * Default maximum recursive depth for nested key type computations,
  * balancing type safety and compiler performance.
  */
 type DefaultDepth = 15;
-/** Countdown tuple for limiting recursive depth (up to 10 levels). */
-type Prev = [
-    never,
-    0,
-    1,
-    2,
-    3,
-    4,
-    5,
-    6,
-    7,
-    8,
-    9,
-    10,
-    11,
-    12,
-    13,
-    14,
-    15,
-    16,
-    17,
-    18,
-    19,
-    20
-];
+/** Countdown tuple for limiting recursive depth (up to 15 levels). */
+type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
+/**
+ * Gets all dot-separated keys (including non-leaf nodes) from a nested object.
+ *
+ * @example
+ * ```ts
+ * NodeKeys<{ a: { b: { c: string }, d: string } }> // → "a" | "a.b" | "a.b.c" | "a.d"
+ * ```
+ */
+type NodeKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never : M extends object ? {
+    [K in keyof M]: K extends string ? `${K}` | `${K}.${NodeKeys<M[K], Prev[D]>}` : never;
+}[keyof M] : never;
 /**
  * Gets dot-separated keys to string leaf nodes in a nested object.
  *
  * @example
- * LeafKeys<{ a: { b: "x", c: { d: "y" } } }> → "a.b" | "a.c.d"
+ * ```ts
+ * LeafKeys<{ a: { b: { c: string }, d: string } }> // → "a.d" | "a.b.c"
+ * ```
  */
 type LeafKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never : M extends object ? {
     [K in keyof M]: M[K] extends string ? `${K & string}` : M[K] extends object ? `${K & string}.${LeafKeys<M[K], Prev[D]>}` : never;
 }[keyof M] : never;
+
 /**
- * Gets string leaf keys from all locale messages combined.
+ * Extracts all **node keys** from the messages
+ * of a specified locale (or union of locales).
  *
  * @example
- * UnionLocaleLeafKeys<{ en: { a: { b: "x" } }, zh: { a: { c: "y" } } }> → "a.b" | "a.c"
+ * ```ts
+ * const messages = {
+ *   en: { greeting: { morning: "morning" } },
+ *   zh: { greeting: { evening: "晚上好" } },
+ * };
+ *
+ * // 1. Union of all locales
+ * LocalizedNodeKeys<typeof messages> // → "greeting" | "greeting.morning" | "greeting.evening"
+ *
+ * // 2. For a specified locale
+ * LocalizedNodeKeys<typeof messages, "en"> // → "greeting" | "greeting.morning"
+ * LocalizedNodeKeys<typeof messages, "zh"> // → "greeting" | "greeting.evening"
+ *
+ * // 3. Fallback when M is not LocaleMessages
+ * LocalizedNodeKeys // → string
+ * ```
  */
-type UnionLocaleLeafKeys<M, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends NamespaceMessages ? LeafKeys<UnionLocaleMessages<M>, D> : never;
+type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends NestedMessage ? NodeKeys<LocalizedMessagesUnion<M, L>, D> : never : string;
 /**
- * Resolves the type at a dot-separated key in a nested object.
+ * Extracts all **leaf keys** from the messages
+ * of a specified locale (or union of locales).
  *
  * @example
- * ResolvePathType<{ a: { b: { c: string } } }, "a.b.c"> → string
- * ResolvePathType<{ a: { b: { c: "hello" } } }, "a.b.c"> → "hello"
+ * ```ts
+ * const messages = {
+ *   en: { greeting: { morning: "morning" } },
+ *   zh: { greeting: { evening: "晚上好" } },
+ * };
+ *
+ * // 1. Union of all locales
+ * LocalizedLeafKeys<typeof messages> // → "greeting.morning" | "greeting.evening"
+ *
+ * // 2. For a specified locale
+ * LocalizedLeafKeys<typeof messages, "en"> // → "greeting.morning"
+ * LocalizedLeafKeys<typeof messages, "zh"> // → "greeting.evening"
+ *
+ * // 3. Fallback if M is not LocaleMessages
+ * LocalizedLeafKeys // → string
+ * ```
  */
-type ResolvePathType<T, P extends string> = P extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? ResolvePathType<T[Head], Tail> : never : P extends keyof T ? T[P] : never;
+type LocalizedLeafKeys<M = unknown, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends NestedMessage ? LeafKeys<LocalizedMessagesUnion<M, L>, D> : never : string;
+
 /**
- * Extracts leaf keys under a scoped path (K) from all locales combined.
+ * Resolves the type at a dot-separated key in a nested object.
  *
  * @example
- * type Messages = {
- *   en: { auth: { login: { success: string } } },
- *   zh: { auth: { login: { success: string; failed: string } } }
+ * ```ts
+ * const structure = {
+ *   a: {
+ *     b: { c: "hello" },
+ *     z: "world",
+ *   },
  * };
- * ScopedLeafKeys<Messages, "auth.login"> → "success" | "failed"
+ *
+ * MessagesAtPreKey<typeof structure, "a"> // → { b: { c: string; }; z: string;}
+ * MessagesAtPreKey<typeof structure, "a.b"> // → { c: string; };
+ * ```
  */
-type ScopedLeafKeys<M, K extends string, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends infer ResolvedLocaleMessages ? ResolvedLocaleMessages extends object ? LeafKeys<ResolvePathType<ResolvedLocaleMessages, K>, D> : never : never;
+type MessagesAtPreKey<T, PK extends string> = PK extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? MessagesAtPreKey<T[Head], Tail> : never : PK extends keyof T ? T[PK] : never;
 /**
- * Infer valid key type from locale messages.
+ * Extracts all **leaf keys** under a scoped path (`PK`) from the messages
+ * of a specified locale (`L`) (or union of locales).
+ *
+ * @example
+ * ```ts
+ * const messages = {
+ *   en: { a: { b: { c: "hello" }, z: "world" } },
+ *   zh: { a: { b: "hello" },
+ * };
  *
- * If `M` is not passed or empty, fallback to `string`.
+ * ScopedLeafKeys<typeof messages, "a">; // → "b.c" | "z"
+ * ScopedLeafKeys<typeof messages, "a.b">; // → "c"
+ * ScopedLeafKeys<typeof messages, "a", "zh">; // →  "b"
+ * ```
  */
-type InferTranslatorKey<M> = M extends LocaleNamespaceMessages ? UnionLocaleLeafKeys<M> : string;
+type ScopedLeafKeys<M, PK extends string, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends infer messages ? messages extends NestedMessage ? LeafKeys<MessagesAtPreKey<messages, PK>, D> : never : never : string;
 
 /**
  * A ref object holding all localized messages by locale.
  *
  * @example
- * const messagesRef: MessagesRef<AllMessages> = {
+ * ```ts
+ * const messagesRef: MessagesRef<Messages> = {
  *   current: {
  *     en: { home: { title: "Welcome" } },
  *     zh: { home: { title: "歡迎" } }
  *   }
  * };
+ * ```
  */
-type MessagesRef<M> = {
+type MessagesRef<M = unknown> = {
     current?: Readonly<M>;
 };
 /**
  * A ref object holding the currently selected locale.
  *
  * @example
- * const localeRef: LocaleRef<AllMessages> = {
+ * ```ts
+ * const localeRef: LocaleRef<Messages> = {
  *   current: "en"
  * };
+ * ```
  */
-type LocaleRef<M> = {
-    current?: LocaleKey<M>;
+type LocaleRef<M = unknown> = {
+    current: Locale<M>;
 };
 /**
  * A ref object indicating whether translation is loading.
  *
  * @example
+ * ```ts
  * const isLoadingRef: IsLoadingRef = {
  *   current: true
  * };
+ * ```
  */
 type IsLoadingRef = {
     current: boolean;
 };
 
-type ScopedTranslatorMethods<M, K extends string> = {
-    hasKey: (key?: ScopedLeafKeys<M, K> & string, targetLocale?: LocaleKey<M>) => boolean;
-    t: (key?: ScopedLeafKeys<M, K> & string, replacements?: Replacement | RichReplacement) => string;
-};
-type TranslatorMethods<M> = {
-    hasKey: (key?: InferTranslatorKey<M> & string, targetLocale?: LocaleKey<M>) => boolean;
-    t: (key?: InferTranslatorKey<M> & string, replacements?: Replacement | RichReplacement) => string;
-};
-
-/** Config options for translation behavior. */
-type TranslateConfig<M> = {
-    fallbackLocales?: FallbackLocalesMap<LocaleKey<M>>;
+/**
+ * Configuration options for translation behavior.
+ */
+type TranslateConfig<M = unknown> = {
+    /** Optional mapping of fallback locales to use when a message is missing in the current locale. */
+    fallbackLocales?: FallbackLocalesMap<Locale<M>>;
+    /** Optional message to display while translations are still loading. */
     loadingMessage?: string;
+    /** Optional placeholder to use when a message cannot be found. */
     placeholder?: string;
+    /** Optional set of handler functions for customizing translation behavior. */
     handlers?: TranslateHandlers;
 };
-/** Optional handler functions for customizing translation behavior. */
+/**
+ * Optional handler functions for customizing translation behavior.
+ */
 type TranslateHandlers = {
-    formatMessage?: FormatMessage;
-    onLoading?: OnLoading;
-    onMissing?: OnMissing;
+    /** Function to format a resolved message before returning it. */
+    formatHandler?: FormatHandler;
+    /** Function called when a translation is still loading. */
+    loadingHandler?: LoadingHandler;
+    /** Function called when no message is found for a given key. */
+    missingHandler?: MissingHandler;
 };
-/** Format a resolved message before returning it. */
-type FormatMessage<Result = unknown> = (ctx: TranslateContext & {
+/** Function to format a resolved message. */
+type FormatHandler<Result = unknown> = (ctx: TranslateHandlerContext & {
     message: string;
 }) => Result;
-/** Called when translation is still loading. */
-type OnLoading<Result = unknown> = (ctx: TranslateContext) => Result;
-/** Called when no message is found for the given key. */
-type OnMissing<Result = unknown> = (ctx: TranslateContext) => Result;
+/** Function called when translation is still loading. */
+type LoadingHandler<Result = unknown> = (ctx: TranslateHandlerContext) => Result;
+/** Function called when no message is found for the given key. */
+type MissingHandler<Result = unknown> = (ctx: TranslateHandlerContext) => Result;
 /**
- * Context passed to translation-related functions.
+ * Context object passed to translation-related functions.
+ *
  * @example
  * {
  *   locale: "en",
  *   key: "home.title",
- *   replacements: { name: "Yiming" }
+ *   replacements: { name: "John" }
  * }
  */
-type TranslateContext = {
+type TranslateHandlerContext = {
+    /** The current locale being translated. */
     locale: Locale;
+    /** The translation key for the message. */
     key: string;
-    replacements?: Replacement | RichReplacement;
+    /** Optional replacements for dynamic interpolation in the message. */
+    replacements?: Replacement;
 };
 
+/**
+ * Options for initializing a translator
+ *
+ * @template M - type of messages object
+ */
 interface BaseTranslatorOptions<M = unknown> {
+    /**
+     * Messages object for translations.
+     * - Use `LocaleMessages` type to enable key inference for `hasKey` and `t`.
+     */
     messages?: Readonly<M>;
-    locale?: LocaleKey<M>;
+    /**
+     * Current locale key.
+     * - If `messages` is typed as `LocaleMessages`, this can be inferred automatically.
+     */
+    locale: Locale<M>;
 }
 
 declare class BaseTranslator<M = unknown> {
+    /** Current messages for translation, updatable at runtime */
     protected messagesRef: MessagesRef<M>;
+    /** Current active locale, can be changed dynamically */
     protected localeRef: LocaleRef<M>;
-    constructor(options?: BaseTranslatorOptions<M>);
-    /** Get all message data. */
+    constructor(options: BaseTranslatorOptions<M>);
+    /** Get messages. */
     get messages(): M | undefined;
+    /** Get the current active locale. */
+    get locale(): Locale<M>;
     /**
      * Replace messages with new ones.
      *
-     * Note: This allows runtime setting of messages even if M is inferred as `never` (uninitialized).
-     * Type cast is used to bypass TypeScript restrictions on dynamic messages.
+     * - Note: This allows runtime setting of messages even if `M` is inferred as `never`.
+     * The type cast bypasses TypeScript restrictions on dynamic messages.
      */
-    setMessages<N extends LocaleNamespaceMessages>(messages: N): void;
-    /** Get the current active locale. */
-    get locale(): LocaleKey<M> | undefined;
-    /** Change the active locale. */
-    setLocale(newLocale: LocaleKey<M>): void;
-    /** Check if a key exists in the specified locale or current locale. */
-    hasKey: (key: InferTranslatorKey<M>, targetLocale?: LocaleKey<M>) => boolean;
+    setMessages<N extends LocaleMessages>(messages: N): void;
+    /**
+     * Set the active locale.
+     *
+     * - Note: Unlike `setMessages`, the locale structure cannot be changed at runtime.
+     */
+    setLocale(newLocale: Locale<M>): void;
 }
 
 interface CoreTranslatorOptions<M> extends BaseTranslatorOptions<M>, TranslateConfig<M> {
 }
 
-declare class CoreTranslator<M = unknown> extends BaseTranslator<M> {
+declare class CoreTranslator<M = unknown, L extends keyof M | "union" = "union"> extends BaseTranslator<M> {
     protected options: CoreTranslatorOptions<M>;
     protected isLoadingRef: IsLoadingRef;
-    constructor(options?: CoreTranslatorOptions<M>);
+    constructor(options: CoreTranslatorOptions<M>);
     /** Get the current loading state. */
     get isLoading(): boolean;
     /** Set the loading state. */
     setLoading(state: boolean): void;
-    t: <Result = string>(key: InferTranslatorKey<M>, replacements?: Replacement | RichReplacement) => Result;
+    /** Check if a key exists in the specified locale or current locale. */
+    hasKey: <K = LocalizedLeafKeys<M, L>>(key: K, targetLocale?: Locale<M>) => boolean;
+    t: <Result = string, L_1 extends keyof M | "union" = "union", K = LocalizedLeafKeys<M, L_1>>(key: K, replacements?: Replacement) => Result;
 }
 
-declare class ScopeTranslator<M = unknown> extends CoreTranslator<M> {
-    constructor(options?: CoreTranslatorOptions<M>);
-    scoped<K extends NodeKeys<UnionLocaleMessages<M>> & string>(preKey: K): ScopedTranslatorMethods<M, K>;
-    scoped(): TranslatorMethods<M>;
+type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
+type ScopeTranslatorMethods<M, L extends keyof M | "union" = "union", K = LocalizedLeafKeys<M, L>> = {
+    hasKey: (key?: K, targetLocale?: Locale<M>) => boolean;
+    t: <Result = string>(key?: K, replacements?: Replacement) => Result;
+};
+
+declare class ScopeTranslator<M = unknown, L extends keyof M | "union" = "union"> extends CoreTranslator<M> {
+    constructor(options: ScopeTranslatorOptions<M>);
+    scoped<PK extends LocalizedNodeKeys<M, L> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, L, ScopedLeafKeys<M, PK, L>> : ScopeTranslatorMethods<M, L>;
 }
 
-export { type FallbackLocalesMap, type FormatMessage, type InferTranslatorKey, type IsLoadingRef, type LeafKeys, type Locale, type LocaleKey, type LocaleNamespaceMessages, type LocaleRef, type Message, type MessageRecord, type MessagesRef, type Namespace, type NamespaceMessages, type NestedMessage, type NodeKeys, type OnLoading, type OnMissing, type Replacement, type RichReplacement, type ScopedLeafKeys, type StrictLocaleKey, type TranslateConfig, type TranslateContext, type TranslateHandlers, ScopeTranslator as Translator, type UnionLocaleLeafKeys, type UnionLocaleMessages };
+export { type FallbackLocalesMap, type FormatHandler, type IsLoadingRef, type LeafKeys, type LoadingHandler, type Locale, type LocaleMessages, type LocaleRef, type LocalizedLeafKeys, type LocalizedMessagesUnion, type MessagesRef, type MissingHandler, type NestedMessage, type NodeKeys, type Replacement, ScopeTranslator, type ScopeTranslatorMethods, type ScopeTranslatorOptions, type ScopedLeafKeys, type TranslateHandlerContext, type TranslateHandlers, ScopeTranslator as Translator };