intor-translator 1.4.8 → 1.4.9

package/dist/index.cjs

@@ -332,7 +332,7 @@ var ScopeTranslator = class extends CoreTranslator {
           targetLocale
         });
       },
-      t: (key, ...args) => {
+      t: (key, replacements) => {
         const fullKey = getFullKey(preKey, key);
         return translate({
           hooks: this.hooks,
@@ -341,7 +341,7 @@ var ScopeTranslator = class extends CoreTranslator {
           isLoading: this._isLoading,
           translateConfig: this.translateConfig,
           key: fullKey,
-          replacements: args[0]
+          replacements
         });
       }
     };

package/dist/index.d.cts

@@ -82,163 +82,162 @@ type Locale<M = unknown> = M extends LocaleMessages ? keyof M & string : string;
  */
 type FallbackLocalesMap<L extends string = string> = Partial<Record<L, L[]>>;
 
-/**
- * Represents a replacement map used for interpolating values
- * in message templates.
- *
- * Replacement values are treated as plain data and interpreted
- * by the message formatter at runtime.
- *
- * @example
- * const replacements: Replacement = {
- *   name: "Alice",
- *   count: 5,
- *   nested: {
- *     score: 100,
- *   },
- * };
- */
-type Replacement = Record<string, MessageValue>;
-
 /**
  * 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 15 levels). */
-type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
+type PrevDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
+/** Detects `any` to prevent infinite type recursion. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** Detects `never` for safe conditional branching in type pipelines. */
+type IsNever<T> = [T] extends [never] ? true : false;
 /**
- * Gets all dot-separated keys of a nested object, stopping at message leaf values.
+ * Expands a single object property into its dot-separated path form.
  *
  * @example
  * ```ts
- * NodeKeys<{ a: { b: { c: string }, d: string } }> // → "a" | "a.b" | "a.b.c" | "a.d"
+ * ExpandPath<"user", { name: string }>; // => "user" | "user.name"
  * ```
+ *
  */
-type NodeKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never : M extends object ? {
-    [K in keyof M]: M[K] extends MessageLeaf ? `${K & string}` : M[K] extends object ? `${K & string}` | `${K & string}.${NodeKeys<M[K], Prev[D]>}` : never;
+type ExpandPath<K extends PropertyKey, V, IncludeSelf extends boolean = true, D extends number = DefaultDepth> = V extends MessageLeaf ? `${K & string}` : V extends MessageObject ? IncludeSelf extends true ? `${K & string}` | `${K & string}.${GeneratePaths<V, IncludeSelf, PrevDepth[D]>}` : `${K & string}.${GeneratePaths<V, IncludeSelf, PrevDepth[D]>}` : never;
+/**
+ * Generates dot-separated path strings from a nested message object.
+ * @example
+ * ```ts
+ * GeneratePaths<{ user: { name: "Ivan" } }>; // => "user" | "user.name"
+ * ```
+ */
+type GeneratePaths<M, IncludeSelf extends boolean = true, D extends number = DefaultDepth> = IsAny<M> extends true ? never : [D] extends [never] ? never : M extends MessageObject ? {
+    [K in keyof M]: ExpandPath<K, M[K], IncludeSelf, D>;
 }[keyof M] : never;
 /**
- * Gets dot-separated keys that resolve to message leaf values in a nested object.
+ * Resolves the type located at a dot-separated path.
  *
  * @example
  * ```ts
- * LeafKeys<{ a: { b: { c: string }, d: string } }> // → "a.d" | "a.b.c"
+ * AtPath<{ a: { b: { c: string } } }, "a.b">; // => { c: string };
  * ```
  */
-type LeafKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never : M extends object ? {
-    [K in keyof M]: M[K] extends MessageLeaf ? `${K & string}` : M[K] extends object ? `${K & string}.${LeafKeys<M[K], Prev[D]>}` : never;
-}[keyof M] : never;
+type AtPath<MessageSchema, PK extends string> = PK extends `${infer Head}.${infer Tail}` ? Head extends keyof MessageSchema ? AtPath<MessageSchema[Head], Tail> : never : PK extends keyof MessageSchema ? MessageSchema[PK] : never;
+/** Conditional helper for branching on `LocaleMessages`. */
+type IfLocaleMessages<T, Then, Else> = T extends LocaleMessages ? Then : Else;
+/** Narrows a type to `MessageObject`, otherwise resolves to never. */
+type IfMessageObject<T> = T extends MessageObject ? T : never;
+
 /**
- * Resolves the value type at a given dot-separated leaf key
- * within a nested message object.
+ * Dot-separated leaf keys derived from a single message object.
  *
  * @example
  * ```ts
- * LeafValue<{ a: { b: { c: string } } }, "a.b.c"> // → string
+ * Key<{ a: { b: { c: string }; z: string } }>; // => "a.z" | "a.b.c"
  * ```
  */
-type LeafValue<M, K extends string> = K extends `${infer Seg}.${infer Rest}` ? Seg extends keyof M ? LeafValue<M[Seg], Rest> : never : K extends keyof M ? M[K] : never;
+type Key<M> = GeneratePaths<M, false>;
 /**
- * Resolves the type located at a dot-separated path.
+ * Leaf keys resolved from localized messages (union of all locales).
  *
- * The resolved type may be a subtree or a leaf value.
+ * @example
+ * ```ts
+ * LocalizedKey<{ en: { a: { b: { c: string }; z: string } } }>; // =>  "a.z" | "a.b.c"
+ * ```
+ */
+type LocalizedKey<M> = IfLocaleMessages<M, Key<IfMessageObject<M[keyof M]>>, string>;
+/**
+ * Leaf keys scoped under a given prefix key.
  *
  * @example
  * ```ts
- * const messages = { a: { b: { c: "1" }, z: "2" } };
- * AtPath<typeof messages, "a">; // → { b: { c: string }; z: string };
- * AtPath<typeof messages, "a.b">; // → { c: string };
+ *  ScopedKey<{ en: { a: { b: { c: string }; z: string } } }, "a">; // => "b.c" | "z"
  * ```
  */
-type AtPath<MessageSchema, PK extends string> = PK extends `${infer Head}.${infer Tail}` ? Head extends keyof MessageSchema ? AtPath<MessageSchema[Head], Tail> : never : PK extends keyof MessageSchema ? MessageSchema[PK] : never;
+type ScopedKey<M, PK extends string> = IfLocaleMessages<M, Key<IfMessageObject<AtPath<M[keyof M], PK>>>, string>;
 
 /**
- * Extracts all **node keys** from the messages
- * of a specified locale (or union of locales).
+ * Prefix keys that may resolve to intermediate or leaf paths.
  *
  * @example
  * ```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
+ * PreKey<{ a: { b: { c: string }; z: string } }>; // → "a" | "a.b" | "a.z" | "a.b.c"
  * ```
  */
-type LocalizedNodeKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? NodeKeys<M[keyof M], D> : string;
+type PreKey<M> = GeneratePaths<M, true>;
 /**
- * Extracts all **leaf keys** from the messages
- * of a specified locale (or union of locales).
+ * Prefix keys resolved from localized messages (union of all locales).
  *
  * @example
  * ```ts
- * const messages = {
- *   en: { greeting: { morning: "morning" } },
- *   zh: { greeting: { evening: "晚上好" } },
- * };
- *
- * // 1. Union of all locales
- * LocalizedLeafKeys<typeof messages> // → "greeting.morning" | "greeting.evening"
+ * LocalizedPreKey<{ en: { a: { b: { c: string }; z: string } } }>; // →   "a" | "a.b" | "a.z" | "a.b.c"
+ * ```
+ */
+type LocalizedPreKey<M> = IfLocaleMessages<M, PreKey<IfMessageObject<M[keyof M]>>, string>;
+
+/**
+ * Resolves the value type at a dot-separated path.
  *
- * // 2. For a specified locale
- * LocalizedLeafKeys<typeof messages, "en"> // → "greeting.morning"
- * LocalizedLeafKeys<typeof messages, "zh"> // → "greeting.evening"
+ * @example
+ * ```ts
+ * Value<{ a: { b: { c: string } } }, "a.b.c">; // => string
+ * ```
+ */
+type Value<M, K extends string> = K extends `${infer Head}.${infer Tail}` ? Head extends keyof M ? Value<M[Head], Tail> : never : K extends keyof M ? M[K] : never;
+/**
+ * Value resolved from localized messages (union of all locales).
  *
- * // 3. Fallback if M is not LocaleMessages
- * LocalizedLeafKeys // → string
+ * @example
+ * ```ts
+ * LocalizedValue<{ en: { a: { b: { c: string }; z: string } } }, "a.b.c">; // => string
  * ```
  */
-type LocalizedLeafKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? LeafKeys<M[keyof M], D> : string;
+type LocalizedValue<M, K extends string> = IfLocaleMessages<M, Value<M[keyof M], K>, MessageValue>;
 /**
- * Resolves the value type of a **localized leaf key**
- * from the messages of a specified locale (or union of locales).
+ * Value resolved under a scoped prefix key.
  *
- * - Fallback to `MessageValue` if M is not LocaleMessages
+ * @example
+ * ```ts
+ * ScopedValue<{ en: { a: { b: { c: string }; z: string } } }, "a", "b.c">; // => string
+ * ```
  */
-type LocalizedLeafValue<M = unknown, K extends string = string> = M extends LocaleMessages ? LeafValue<M[keyof M], K> : MessageValue;
+type ScopedValue<M, PK extends string, K extends string> = IfLocaleMessages<M, Value<AtPath<M[keyof M], PK>, K>, MessageValue>;
 
 /**
- * Extracts all **leaf keys** under a scoped path (`PK`) from the messages
- * of a specified locale (`L`) (or union of locales).
+ * Generic replacement object used when no schema is available.
+ *
+ * Acts as a safe fallback for dynamic or unknown replacement shapes.
+ */
+type Replacement = Record<string, unknown>;
+/**
+ * Replacement object resolved from a localized replacement schema.
+ *
+ * - If the key exists in the schema, resolves to the declared object shape
+ * - Otherwise falls back to generic `Replacement`
  *
  * @example
  * ```ts
- * const messages = {
- *   en: { a: { b: { c: "hello" }, z: "world" } },
- *   zh: { a: { b: "hello" },
- * };
- *
- * ScopedLeafKeys<typeof messages, "a">; // → "b.c" | "z"
- * ScopedLeafKeys<typeof messages, "a.b">; // → "c"
- * ScopedLeafKeys<typeof messages, "a", "zh">; // →  "b"
+ * type ReplacementSchema = { "{locale}": { greeting: { name: string } } };
+ * LocalizedReplacement<ReplacementSchema, "greeting">; // => { name: string }
+ * LocalizedReplacement<ReplacementSchema, "missing">;  // => Replacement
  * ```
  */
-type ScopedLeafKeys<M, PK extends string, D extends number = DefaultDepth> = M extends LocaleMessages ? M[Locale<M>] extends infer Messages ? Messages extends MessageValue ? AtPath<Messages, PK> extends infer Scoped ? Scoped extends MessageObject ? LeafKeys<Scoped, D> : never : never : never : never : string;
+type LocalizedReplacement<ReplacementSchema, K extends string> = ReplacementSchema extends {
+    "{locale}": infer LM;
+} ? IsNever<AtPath<LM, K>> extends true ? Replacement : AtPath<LM, K> extends MessageObject ? AtPath<LM, K> : Replacement : Replacement;
 /**
- * Resolves the value type of a scoped leaf key (`K`)
- * under a prefix path (`PK`) from localized messages.
+ * Replacement object resolved under a scoped prefix key.
+ *
+ * Internally composes the full dot-path (`"${PK}.${K}"`)
+ * and delegates resolution to `LocalizedReplacement`.
  *
  * @example
  * ```ts
- * const messages = {
- *   en: { a: { b: { c: "hello" }, z: [123] } },
- * };
- *
- * ScopedLeafValue<typeof messages, "a", "z">;  // number[]
- * ScopedLeafValue<typeof messages, "a.b", "c">;  // string
+ * type ReplacementSchema = { "{locale}": { user: { info: { name: string } } } };
+ * ScopedReplacement<ReplacementSchema, "user", "info">; // => { name: string }
+ * ScopedReplacement<ReplacementSchema, "user", "missing">; // => Replacement
  * ```
  */
-type ScopedLeafValue<M, PK extends string, K extends string> = M extends LocaleMessages ? M[Locale<M>] extends infer Messages ? Messages extends MessageValue ? AtPath<Messages, PK> extends infer Scoped ? Scoped extends MessageObject ? LeafValue<Scoped, K> : never : never : never : never : MessageValue;
+type ScopedReplacement<ReplacementSchema, PK extends string | undefined, K extends string> = LocalizedReplacement<ReplacementSchema, `${PK}.${K}`>;
 
 /**
  * Options for initializing a translator
@@ -389,7 +388,7 @@ interface TranslatorPlugin {
  *
  * @template M - Shape of the messages object.
  */
-declare class CoreTranslator<M extends LocaleMessages | unknown = unknown> extends BaseTranslator<M> {
+declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, ReplacementSchema = unknown> extends BaseTranslator<M> {
     /** User-provided options including messages, locale, and config. */
     protected translateConfig: TranslateConfig<M>;
     /** Active pipeline hooks applied during translation. */
@@ -402,21 +401,21 @@ declare class CoreTranslator<M extends LocaleMessages | unknown = unknown> exten
     /** Outputs a debug overview of the active pipeline. */
     debugHooks(): void;
     /** Check if a key exists in the specified locale or current locale. */
-    hasKey: <K extends LocalizedLeafKeys<M>>(key: K, targetLocale?: Locale<M>) => boolean;
+    hasKey: <K extends LocalizedKey<M>>(key: K, targetLocale?: Locale<M>) => boolean;
     /** Get the translated message for a key, with optional replacements. */
-    t: <K extends LocalizedLeafKeys<M> = LocalizedLeafKeys<M>>(key: K, replacements?: Replacement) => LocalizedLeafValue<M, K>;
+    t: <K extends LocalizedKey<M> = LocalizedKey<M>>(key: K, replacements?: LocalizedReplacement<ReplacementSchema, K>) => LocalizedValue<M, K>;
 }
 
 type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
-type ScopeTranslatorMethods<M extends LocaleMessages | unknown = unknown, PK extends string | undefined = undefined, K extends string = PK extends string ? ScopedLeafKeys<M, PK> : LocalizedLeafKeys<M>> = {
+type ScopeTranslatorMethods<M extends LocaleMessages | unknown = unknown, ReplacementSchema = unknown, PK extends string | undefined = undefined, K extends string = PK extends string ? ScopedKey<M, PK> : LocalizedKey<M>> = {
     hasKey: (key?: K, targetLocale?: Locale<M>) => boolean;
-    t: (key?: K, replacements?: Replacement) => PK extends string ? ScopedLeafValue<M, PK, K> : LocalizedLeafValue<M, K>;
+    t: <Key extends K>(key?: Key, replacements?: ScopedReplacement<ReplacementSchema, PK, K>) => PK extends string ? ScopedValue<M, PK, Key> : LocalizedValue<M, Key>;
 };
 
-declare class ScopeTranslator<M extends LocaleMessages | unknown = unknown> extends CoreTranslator<M> {
+declare class ScopeTranslator<M extends LocaleMessages | unknown = unknown, ReplacementSchema = unknown> extends CoreTranslator<M, ReplacementSchema> {
     constructor(options: ScopeTranslatorOptions<M>);
     /** Create a scoped translator with a prefix key for resolving nested message paths. */
-    scoped<PK extends LocalizedNodeKeys<M> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, PK> : ScopeTranslatorMethods<M>;
+    scoped<PK extends LocalizedPreKey<M> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, ReplacementSchema, PK> : ScopeTranslatorMethods<M, ReplacementSchema>;
 }
 
 /** Semantic tag attributes map. */
@@ -491,4 +490,4 @@ interface Renderer<Output> {
  */
 declare function renderRichMessage<Output>(message: MessageValue, renderer: Renderer<Output>): Output[];
 
-export { type ASTNode, type AtPath, type Attributes, type DefaultDepth, type FallbackLocalesMap, type FormatHandler, type HandlerContext, type LeafKeys, type LeafValue, type LoadingHandler, type Locale, type LocaleMessages, type LocalizedLeafKeys, type LocalizedLeafValue, type LocalizedNodeKeys, type MessageObject, type MessageValue, type MissingHandler, type NodeKeys, type Renderer, type Replacement, type ScopedLeafKeys, type ScopedLeafValue, type TranslateConfig, type TranslateContext, type TranslateHandlers, type TranslateHook, ScopeTranslator as Translator, type ScopeTranslatorMethods as TranslatorMethods, type ScopeTranslatorOptions as TranslatorOptions, type TranslatorPlugin, parseRichMessage, renderRichMessage };
+export { type ASTNode, type AtPath, type Attributes, type FallbackLocalesMap, type FormatHandler, type GeneratePaths, type HandlerContext, type IfLocaleMessages, type IfMessageObject, type Key, type LoadingHandler, type Locale, type LocaleMessages, type LocalizedKey, type LocalizedPreKey, type LocalizedReplacement, type LocalizedValue, type MessageObject, type MessageValue, type MissingHandler, type PreKey, type Renderer, type Replacement, type ScopedKey, type ScopedReplacement, type ScopedValue, type TranslateConfig, type TranslateContext, type TranslateHandlers, type TranslateHook, ScopeTranslator as Translator, type ScopeTranslatorMethods as TranslatorMethods, type ScopeTranslatorOptions as TranslatorOptions, type TranslatorPlugin, type Value, parseRichMessage, renderRichMessage };

package/dist/index.d.ts

@@ -82,163 +82,162 @@ type Locale<M = unknown> = M extends LocaleMessages ? keyof M & string : string;
  */
 type FallbackLocalesMap<L extends string = string> = Partial<Record<L, L[]>>;
 
-/**
- * Represents a replacement map used for interpolating values
- * in message templates.
- *
- * Replacement values are treated as plain data and interpreted
- * by the message formatter at runtime.
- *
- * @example
- * const replacements: Replacement = {
- *   name: "Alice",
- *   count: 5,
- *   nested: {
- *     score: 100,
- *   },
- * };
- */
-type Replacement = Record<string, MessageValue>;
-
 /**
  * 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 15 levels). */
-type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
+type PrevDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
+/** Detects `any` to prevent infinite type recursion. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/** Detects `never` for safe conditional branching in type pipelines. */
+type IsNever<T> = [T] extends [never] ? true : false;
 /**
- * Gets all dot-separated keys of a nested object, stopping at message leaf values.
+ * Expands a single object property into its dot-separated path form.
  *
  * @example
  * ```ts
- * NodeKeys<{ a: { b: { c: string }, d: string } }> // → "a" | "a.b" | "a.b.c" | "a.d"
+ * ExpandPath<"user", { name: string }>; // => "user" | "user.name"
  * ```
+ *
  */
-type NodeKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never : M extends object ? {
-    [K in keyof M]: M[K] extends MessageLeaf ? `${K & string}` : M[K] extends object ? `${K & string}` | `${K & string}.${NodeKeys<M[K], Prev[D]>}` : never;
+type ExpandPath<K extends PropertyKey, V, IncludeSelf extends boolean = true, D extends number = DefaultDepth> = V extends MessageLeaf ? `${K & string}` : V extends MessageObject ? IncludeSelf extends true ? `${K & string}` | `${K & string}.${GeneratePaths<V, IncludeSelf, PrevDepth[D]>}` : `${K & string}.${GeneratePaths<V, IncludeSelf, PrevDepth[D]>}` : never;
+/**
+ * Generates dot-separated path strings from a nested message object.
+ * @example
+ * ```ts
+ * GeneratePaths<{ user: { name: "Ivan" } }>; // => "user" | "user.name"
+ * ```
+ */
+type GeneratePaths<M, IncludeSelf extends boolean = true, D extends number = DefaultDepth> = IsAny<M> extends true ? never : [D] extends [never] ? never : M extends MessageObject ? {
+    [K in keyof M]: ExpandPath<K, M[K], IncludeSelf, D>;
 }[keyof M] : never;
 /**
- * Gets dot-separated keys that resolve to message leaf values in a nested object.
+ * Resolves the type located at a dot-separated path.
  *
  * @example
  * ```ts
- * LeafKeys<{ a: { b: { c: string }, d: string } }> // → "a.d" | "a.b.c"
+ * AtPath<{ a: { b: { c: string } } }, "a.b">; // => { c: string };
  * ```
  */
-type LeafKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never : M extends object ? {
-    [K in keyof M]: M[K] extends MessageLeaf ? `${K & string}` : M[K] extends object ? `${K & string}.${LeafKeys<M[K], Prev[D]>}` : never;
-}[keyof M] : never;
+type AtPath<MessageSchema, PK extends string> = PK extends `${infer Head}.${infer Tail}` ? Head extends keyof MessageSchema ? AtPath<MessageSchema[Head], Tail> : never : PK extends keyof MessageSchema ? MessageSchema[PK] : never;
+/** Conditional helper for branching on `LocaleMessages`. */
+type IfLocaleMessages<T, Then, Else> = T extends LocaleMessages ? Then : Else;
+/** Narrows a type to `MessageObject`, otherwise resolves to never. */
+type IfMessageObject<T> = T extends MessageObject ? T : never;
+
 /**
- * Resolves the value type at a given dot-separated leaf key
- * within a nested message object.
+ * Dot-separated leaf keys derived from a single message object.
  *
  * @example
  * ```ts
- * LeafValue<{ a: { b: { c: string } } }, "a.b.c"> // → string
+ * Key<{ a: { b: { c: string }; z: string } }>; // => "a.z" | "a.b.c"
  * ```
  */
-type LeafValue<M, K extends string> = K extends `${infer Seg}.${infer Rest}` ? Seg extends keyof M ? LeafValue<M[Seg], Rest> : never : K extends keyof M ? M[K] : never;
+type Key<M> = GeneratePaths<M, false>;
 /**
- * Resolves the type located at a dot-separated path.
+ * Leaf keys resolved from localized messages (union of all locales).
  *
- * The resolved type may be a subtree or a leaf value.
+ * @example
+ * ```ts
+ * LocalizedKey<{ en: { a: { b: { c: string }; z: string } } }>; // =>  "a.z" | "a.b.c"
+ * ```
+ */
+type LocalizedKey<M> = IfLocaleMessages<M, Key<IfMessageObject<M[keyof M]>>, string>;
+/**
+ * Leaf keys scoped under a given prefix key.
  *
  * @example
  * ```ts
- * const messages = { a: { b: { c: "1" }, z: "2" } };
- * AtPath<typeof messages, "a">; // → { b: { c: string }; z: string };
- * AtPath<typeof messages, "a.b">; // → { c: string };
+ *  ScopedKey<{ en: { a: { b: { c: string }; z: string } } }, "a">; // => "b.c" | "z"
  * ```
  */
-type AtPath<MessageSchema, PK extends string> = PK extends `${infer Head}.${infer Tail}` ? Head extends keyof MessageSchema ? AtPath<MessageSchema[Head], Tail> : never : PK extends keyof MessageSchema ? MessageSchema[PK] : never;
+type ScopedKey<M, PK extends string> = IfLocaleMessages<M, Key<IfMessageObject<AtPath<M[keyof M], PK>>>, string>;
 
 /**
- * Extracts all **node keys** from the messages
- * of a specified locale (or union of locales).
+ * Prefix keys that may resolve to intermediate or leaf paths.
  *
  * @example
  * ```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
+ * PreKey<{ a: { b: { c: string }; z: string } }>; // → "a" | "a.b" | "a.z" | "a.b.c"
  * ```
  */
-type LocalizedNodeKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? NodeKeys<M[keyof M], D> : string;
+type PreKey<M> = GeneratePaths<M, true>;
 /**
- * Extracts all **leaf keys** from the messages
- * of a specified locale (or union of locales).
+ * Prefix keys resolved from localized messages (union of all locales).
  *
  * @example
  * ```ts
- * const messages = {
- *   en: { greeting: { morning: "morning" } },
- *   zh: { greeting: { evening: "晚上好" } },
- * };
- *
- * // 1. Union of all locales
- * LocalizedLeafKeys<typeof messages> // → "greeting.morning" | "greeting.evening"
+ * LocalizedPreKey<{ en: { a: { b: { c: string }; z: string } } }>; // →   "a" | "a.b" | "a.z" | "a.b.c"
+ * ```
+ */
+type LocalizedPreKey<M> = IfLocaleMessages<M, PreKey<IfMessageObject<M[keyof M]>>, string>;
+
+/**
+ * Resolves the value type at a dot-separated path.
  *
- * // 2. For a specified locale
- * LocalizedLeafKeys<typeof messages, "en"> // → "greeting.morning"
- * LocalizedLeafKeys<typeof messages, "zh"> // → "greeting.evening"
+ * @example
+ * ```ts
+ * Value<{ a: { b: { c: string } } }, "a.b.c">; // => string
+ * ```
+ */
+type Value<M, K extends string> = K extends `${infer Head}.${infer Tail}` ? Head extends keyof M ? Value<M[Head], Tail> : never : K extends keyof M ? M[K] : never;
+/**
+ * Value resolved from localized messages (union of all locales).
  *
- * // 3. Fallback if M is not LocaleMessages
- * LocalizedLeafKeys // → string
+ * @example
+ * ```ts
+ * LocalizedValue<{ en: { a: { b: { c: string }; z: string } } }, "a.b.c">; // => string
  * ```
  */
-type LocalizedLeafKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? LeafKeys<M[keyof M], D> : string;
+type LocalizedValue<M, K extends string> = IfLocaleMessages<M, Value<M[keyof M], K>, MessageValue>;
 /**
- * Resolves the value type of a **localized leaf key**
- * from the messages of a specified locale (or union of locales).
+ * Value resolved under a scoped prefix key.
  *
- * - Fallback to `MessageValue` if M is not LocaleMessages
+ * @example
+ * ```ts
+ * ScopedValue<{ en: { a: { b: { c: string }; z: string } } }, "a", "b.c">; // => string
+ * ```
  */
-type LocalizedLeafValue<M = unknown, K extends string = string> = M extends LocaleMessages ? LeafValue<M[keyof M], K> : MessageValue;
+type ScopedValue<M, PK extends string, K extends string> = IfLocaleMessages<M, Value<AtPath<M[keyof M], PK>, K>, MessageValue>;
 
 /**
- * Extracts all **leaf keys** under a scoped path (`PK`) from the messages
- * of a specified locale (`L`) (or union of locales).
+ * Generic replacement object used when no schema is available.
+ *
+ * Acts as a safe fallback for dynamic or unknown replacement shapes.
+ */
+type Replacement = Record<string, unknown>;
+/**
+ * Replacement object resolved from a localized replacement schema.
+ *
+ * - If the key exists in the schema, resolves to the declared object shape
+ * - Otherwise falls back to generic `Replacement`
  *
  * @example
  * ```ts
- * const messages = {
- *   en: { a: { b: { c: "hello" }, z: "world" } },
- *   zh: { a: { b: "hello" },
- * };
- *
- * ScopedLeafKeys<typeof messages, "a">; // → "b.c" | "z"
- * ScopedLeafKeys<typeof messages, "a.b">; // → "c"
- * ScopedLeafKeys<typeof messages, "a", "zh">; // →  "b"
+ * type ReplacementSchema = { "{locale}": { greeting: { name: string } } };
+ * LocalizedReplacement<ReplacementSchema, "greeting">; // => { name: string }
+ * LocalizedReplacement<ReplacementSchema, "missing">;  // => Replacement
  * ```
  */
-type ScopedLeafKeys<M, PK extends string, D extends number = DefaultDepth> = M extends LocaleMessages ? M[Locale<M>] extends infer Messages ? Messages extends MessageValue ? AtPath<Messages, PK> extends infer Scoped ? Scoped extends MessageObject ? LeafKeys<Scoped, D> : never : never : never : never : string;
+type LocalizedReplacement<ReplacementSchema, K extends string> = ReplacementSchema extends {
+    "{locale}": infer LM;
+} ? IsNever<AtPath<LM, K>> extends true ? Replacement : AtPath<LM, K> extends MessageObject ? AtPath<LM, K> : Replacement : Replacement;
 /**
- * Resolves the value type of a scoped leaf key (`K`)
- * under a prefix path (`PK`) from localized messages.
+ * Replacement object resolved under a scoped prefix key.
+ *
+ * Internally composes the full dot-path (`"${PK}.${K}"`)
+ * and delegates resolution to `LocalizedReplacement`.
  *
  * @example
  * ```ts
- * const messages = {
- *   en: { a: { b: { c: "hello" }, z: [123] } },
- * };
- *
- * ScopedLeafValue<typeof messages, "a", "z">;  // number[]
- * ScopedLeafValue<typeof messages, "a.b", "c">;  // string
+ * type ReplacementSchema = { "{locale}": { user: { info: { name: string } } } };
+ * ScopedReplacement<ReplacementSchema, "user", "info">; // => { name: string }
+ * ScopedReplacement<ReplacementSchema, "user", "missing">; // => Replacement
  * ```
  */
-type ScopedLeafValue<M, PK extends string, K extends string> = M extends LocaleMessages ? M[Locale<M>] extends infer Messages ? Messages extends MessageValue ? AtPath<Messages, PK> extends infer Scoped ? Scoped extends MessageObject ? LeafValue<Scoped, K> : never : never : never : never : MessageValue;
+type ScopedReplacement<ReplacementSchema, PK extends string | undefined, K extends string> = LocalizedReplacement<ReplacementSchema, `${PK}.${K}`>;
 
 /**
  * Options for initializing a translator
@@ -389,7 +388,7 @@ interface TranslatorPlugin {
  *
  * @template M - Shape of the messages object.
  */
-declare class CoreTranslator<M extends LocaleMessages | unknown = unknown> extends BaseTranslator<M> {
+declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, ReplacementSchema = unknown> extends BaseTranslator<M> {
     /** User-provided options including messages, locale, and config. */
     protected translateConfig: TranslateConfig<M>;
     /** Active pipeline hooks applied during translation. */
@@ -402,21 +401,21 @@ declare class CoreTranslator<M extends LocaleMessages | unknown = unknown> exten
     /** Outputs a debug overview of the active pipeline. */
     debugHooks(): void;
     /** Check if a key exists in the specified locale or current locale. */
-    hasKey: <K extends LocalizedLeafKeys<M>>(key: K, targetLocale?: Locale<M>) => boolean;
+    hasKey: <K extends LocalizedKey<M>>(key: K, targetLocale?: Locale<M>) => boolean;
     /** Get the translated message for a key, with optional replacements. */
-    t: <K extends LocalizedLeafKeys<M> = LocalizedLeafKeys<M>>(key: K, replacements?: Replacement) => LocalizedLeafValue<M, K>;
+    t: <K extends LocalizedKey<M> = LocalizedKey<M>>(key: K, replacements?: LocalizedReplacement<ReplacementSchema, K>) => LocalizedValue<M, K>;
 }
 
 type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
-type ScopeTranslatorMethods<M extends LocaleMessages | unknown = unknown, PK extends string | undefined = undefined, K extends string = PK extends string ? ScopedLeafKeys<M, PK> : LocalizedLeafKeys<M>> = {
+type ScopeTranslatorMethods<M extends LocaleMessages | unknown = unknown, ReplacementSchema = unknown, PK extends string | undefined = undefined, K extends string = PK extends string ? ScopedKey<M, PK> : LocalizedKey<M>> = {
     hasKey: (key?: K, targetLocale?: Locale<M>) => boolean;
-    t: (key?: K, replacements?: Replacement) => PK extends string ? ScopedLeafValue<M, PK, K> : LocalizedLeafValue<M, K>;
+    t: <Key extends K>(key?: Key, replacements?: ScopedReplacement<ReplacementSchema, PK, K>) => PK extends string ? ScopedValue<M, PK, Key> : LocalizedValue<M, Key>;
 };
 
-declare class ScopeTranslator<M extends LocaleMessages | unknown = unknown> extends CoreTranslator<M> {
+declare class ScopeTranslator<M extends LocaleMessages | unknown = unknown, ReplacementSchema = unknown> extends CoreTranslator<M, ReplacementSchema> {
     constructor(options: ScopeTranslatorOptions<M>);
     /** Create a scoped translator with a prefix key for resolving nested message paths. */
-    scoped<PK extends LocalizedNodeKeys<M> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, PK> : ScopeTranslatorMethods<M>;
+    scoped<PK extends LocalizedPreKey<M> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, ReplacementSchema, PK> : ScopeTranslatorMethods<M, ReplacementSchema>;
 }
 
 /** Semantic tag attributes map. */
@@ -491,4 +490,4 @@ interface Renderer<Output> {
  */
 declare function renderRichMessage<Output>(message: MessageValue, renderer: Renderer<Output>): Output[];
 
-export { type ASTNode, type AtPath, type Attributes, type DefaultDepth, type FallbackLocalesMap, type FormatHandler, type HandlerContext, type LeafKeys, type LeafValue, type LoadingHandler, type Locale, type LocaleMessages, type LocalizedLeafKeys, type LocalizedLeafValue, type LocalizedNodeKeys, type MessageObject, type MessageValue, type MissingHandler, type NodeKeys, type Renderer, type Replacement, type ScopedLeafKeys, type ScopedLeafValue, type TranslateConfig, type TranslateContext, type TranslateHandlers, type TranslateHook, ScopeTranslator as Translator, type ScopeTranslatorMethods as TranslatorMethods, type ScopeTranslatorOptions as TranslatorOptions, type TranslatorPlugin, parseRichMessage, renderRichMessage };
+export { type ASTNode, type AtPath, type Attributes, type FallbackLocalesMap, type FormatHandler, type GeneratePaths, type HandlerContext, type IfLocaleMessages, type IfMessageObject, type Key, type LoadingHandler, type Locale, type LocaleMessages, type LocalizedKey, type LocalizedPreKey, type LocalizedReplacement, type LocalizedValue, type MessageObject, type MessageValue, type MissingHandler, type PreKey, type Renderer, type Replacement, type ScopedKey, type ScopedReplacement, type ScopedValue, type TranslateConfig, type TranslateContext, type TranslateHandlers, type TranslateHook, ScopeTranslator as Translator, type ScopeTranslatorMethods as TranslatorMethods, type ScopeTranslatorOptions as TranslatorOptions, type TranslatorPlugin, type Value, parseRichMessage, renderRichMessage };

package/dist/index.js

@@ -330,7 +330,7 @@ var ScopeTranslator = class extends CoreTranslator {
           targetLocale
         });
       },
-      t: (key, ...args) => {
+      t: (key, replacements) => {
         const fullKey = getFullKey(preKey, key);
         return translate({
           hooks: this.hooks,
@@ -339,7 +339,7 @@ var ScopeTranslator = class extends CoreTranslator {
           isLoading: this._isLoading,
           translateConfig: this.translateConfig,
           key: fullKey,
-          replacements: args[0]
+          replacements
         });
       }
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intor-translator",
-  "version": "1.4.8",
+  "version": "1.4.9",
   "description": "🤖 A modern, type-safe i18n engine.",
   "author": {
     "name": "Yiming Liao",