intor-translator 1.4.7 → 1.4.9

package/dist/index.cjs

@@ -295,7 +295,7 @@ var CoreTranslator = class extends BaseTranslator {
     });
   };
   /** Get the translated message for a key, with optional replacements. */
-  t = (key, ...replacementArgs) => {
+  t = (key, replacements) => {
     return translate({
       hooks: this.hooks,
       messages: this._messages,
@@ -303,7 +303,7 @@ var CoreTranslator = class extends BaseTranslator {
       isLoading: this._isLoading,
       translateConfig: this.translateConfig,
       key,
-      replacements: replacementArgs[0]
+      replacements
     });
   };
 };
@@ -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

@@ -88,182 +88,156 @@ type FallbackLocalesMap<L extends string = string> = Partial<Record<L, L[]>>;
  */
 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;
-}[keyof M] : 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;
 /**
- * Gets dot-separated keys that resolve to message leaf values in a nested object.
- *
+ * Generates dot-separated path strings from a nested message object.
  * @example
  * ```ts
- * LeafKeys<{ a: { b: { c: string }, d: string } }> // → "a.d" | "a.b.c"
+ * GeneratePaths<{ user: { name: "Ivan" } }>; // => "user" | "user.name"
  * ```
  */
-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;
+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;
 /**
- * Resolves the value type at a given dot-separated leaf key
- * within a nested message object.
+ * Resolves the type located at a dot-separated path.
  *
  * @example
  * ```ts
- * LeafValue<{ a: { b: { c: string } } }, "a.b.c"> // → string
+ * AtPath<{ a: { b: { c: string } } }, "a.b">; // => { c: string };
  * ```
  */
-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 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 type located at a dot-separated path.
- *
- * The resolved type may be a subtree or a leaf value.
+ * Dot-separated leaf keys derived from a single message object.
  *
  * @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 };
+ * Key<{ a: { b: { c: string }; z: string } }>; // => "a.z" | "a.b.c"
  * ```
  */
-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 Key<M> = GeneratePaths<M, false>;
 /**
- * Extracts all **node keys** from the messages
- * of a specified locale (or union of locales).
+ * Leaf 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
- * 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
+ * LocalizedKey<{ en: { a: { b: { c: string }; z: string } } }>; // =>  "a.z" | "a.b.c"
  * ```
  */
-type LocalizedNodeKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? NodeKeys<M[keyof M], D> : string;
+type LocalizedKey<M> = IfLocaleMessages<M, Key<IfMessageObject<M[keyof M]>>, string>;
 /**
- * Extracts all **leaf keys** from the messages
- * of a specified locale (or union of locales).
+ * Leaf keys scoped under a given prefix key.
  *
  * @example
  * ```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"
+ *  ScopedKey<{ en: { a: { b: { c: string }; z: string } } }, "a">; // => "b.c" | "z"
+ * ```
+ */
+type ScopedKey<M, PK extends string> = IfLocaleMessages<M, Key<IfMessageObject<AtPath<M[keyof M], PK>>>, string>;
+
+/**
+ * Prefix keys that may resolve to intermediate or leaf paths.
  *
- * // 3. Fallback if M is not LocaleMessages
- * LocalizedLeafKeys // → string
+ * @example
+ * ```ts
+ * PreKey<{ a: { b: { c: string }; z: string } }>; // → "a" | "a.b" | "a.z" | "a.b.c"
  * ```
  */
-type LocalizedLeafKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? LeafKeys<M[keyof M], D> : string;
+type PreKey<M> = GeneratePaths<M, true>;
 /**
- * Resolves the value type of a **localized leaf key**
- * from the messages of a specified locale (or union of locales).
+ * Prefix keys resolved from localized messages (union of all locales).
  *
- * - Fallback to `MessageValue` if M is not LocaleMessages
+ * @example
+ * ```ts
+ * LocalizedPreKey<{ en: { a: { b: { c: string }; z: string } } }>; // →   "a" | "a.b" | "a.z" | "a.b.c"
+ * ```
  */
-type LocalizedLeafValue<M = unknown, K extends string = string> = M extends LocaleMessages ? LeafValue<M[keyof M], K> : MessageValue;
+type LocalizedPreKey<M> = IfLocaleMessages<M, PreKey<IfMessageObject<M[keyof M]>>, string>;
 
 /**
- * Extracts all **leaf keys** under a scoped path (`PK`) from the messages
- * of a specified locale (`L`) (or union of locales).
+ * Resolves the value type at a dot-separated path.
  *
  * @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"
+ * Value<{ a: { b: { c: string } } }, "a.b.c">; // => string
  * ```
  */
-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 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;
 /**
- * Resolves the value type of a scoped leaf key (`K`)
- * under a prefix path (`PK`) from localized messages.
+ * Value resolved from localized messages (union of all locales).
  *
  * @example
  * ```ts
- * const messages = {
- *   en: { a: { b: { c: "hello" }, z: [123] } },
- * };
+ * LocalizedValue<{ en: { a: { b: { c: string }; z: string } } }, "a.b.c">; // => string
+ * ```
+ */
+type LocalizedValue<M, K extends string> = IfLocaleMessages<M, Value<M[keyof M], K>, MessageValue>;
+/**
+ * Value resolved under a scoped prefix key.
  *
- * ScopedLeafValue<typeof messages, "a", "z">;  // number[]
- * ScopedLeafValue<typeof messages, "a.b", "c">;  // string
+ * @example
+ * ```ts
+ * ScopedValue<{ en: { a: { b: { c: string }; z: string } } }, "a", "b.c">; // => string
  * ```
  */
-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 ScopedValue<M, PK extends string, K extends string> = IfLocaleMessages<M, Value<AtPath<M[keyof M], PK>, K>, MessageValue>;
 
 /**
- * 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.
+ * Generic replacement object used when no schema is available.
  *
- * @example
- * const replacements: Replacement = {
- *   name: "Alice",
- *   count: 5,
- *   nested: {
- *     score: 100,
- *   },
- * };
+ * Acts as a safe fallback for dynamic or unknown replacement shapes.
  */
 type Replacement = Record<string, unknown>;
 /**
- * Resolves the expected replacement type for a localized message key.
+ * Replacement object resolved from a localized replacement schema.
  *
- * Uses the canonical (default-locale) replacement schema when available,
- * otherwise falls back to `Replacement`.
+ * - If the key exists in the schema, resolves to the declared object shape
+ * - Otherwise falls back to generic `Replacement`
  *
  * @example
  * ```ts
- * type RMap = {
- *   "{locale}": {
- *     welcome: { name: MessageValue };
- *     total: { count: MessageValue };
- *   };
- * };
- *
- * type WelcomeReplacement = LocalizedReplacement<RMap, "welcome">;
- * // => { name: MessageValue }
- *
- * type UnknownReplacement = LocalizedReplacement<RMap, "unknown">;
- * // => Replacement
+ * type ReplacementSchema = { "{locale}": { greeting: { name: string } } };
+ * LocalizedReplacement<ReplacementSchema, "greeting">; // => { name: string }
+ * LocalizedReplacement<ReplacementSchema, "missing">;  // => Replacement
  * ```
  */
 type LocalizedReplacement<ReplacementSchema, K extends string> = ReplacementSchema extends {
     "{locale}": infer LM;
-} ? AtPath<LM, K> extends infer R ? R extends MessageObject ? R : Replacement : Replacement : Replacement;
+} ? IsNever<AtPath<LM, K>> extends true ? Replacement : AtPath<LM, K> extends MessageObject ? AtPath<LM, K> : Replacement : Replacement;
+/**
+ * Replacement object resolved under a scoped prefix key.
+ *
+ * Internally composes the full dot-path (`"${PK}.${K}"`)
+ * and delegates resolution to `LocalizedReplacement`.
+ *
+ * @example
+ * ```ts
+ * type ReplacementSchema = { "{locale}": { user: { info: { name: string } } } };
+ * ScopedReplacement<ReplacementSchema, "user", "info">; // => { name: string }
+ * ScopedReplacement<ReplacementSchema, "user", "missing">; // => Replacement
+ * ```
+ */
+type ScopedReplacement<ReplacementSchema, PK extends string | undefined, K extends string> = LocalizedReplacement<ReplacementSchema, `${PK}.${K}`>;
 
 /**
  * Options for initializing a translator
@@ -427,23 +401,21 @@ declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, Repla
     /** 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, ...replacementArgs: [LocalizedReplacement<ReplacementSchema, K>?]) => 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, ReplacementSchema = 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 extends K>(key?: Key, ...replacementArgs: [
-        LocalizedReplacement<ReplacementSchema, PK extends string ? `${PK}.${Key & string}` : Key>?
-    ]) => PK extends string ? ScopedLeafValue<M, PK, Key> : LocalizedLeafValue<M, Key>;
+    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, 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, ReplacementSchema, PK> : ScopeTranslatorMethods<M, ReplacementSchema>;
+    scoped<PK extends LocalizedPreKey<M> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, ReplacementSchema, PK> : ScopeTranslatorMethods<M, ReplacementSchema>;
 }
 
 /** Semantic tag attributes map. */
@@ -518,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 LocalizedReplacement, 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

@@ -88,182 +88,156 @@ type FallbackLocalesMap<L extends string = string> = Partial<Record<L, L[]>>;
  */
 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;
-}[keyof M] : 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;
 /**
- * Gets dot-separated keys that resolve to message leaf values in a nested object.
- *
+ * Generates dot-separated path strings from a nested message object.
  * @example
  * ```ts
- * LeafKeys<{ a: { b: { c: string }, d: string } }> // → "a.d" | "a.b.c"
+ * GeneratePaths<{ user: { name: "Ivan" } }>; // => "user" | "user.name"
  * ```
  */
-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;
+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;
 /**
- * Resolves the value type at a given dot-separated leaf key
- * within a nested message object.
+ * Resolves the type located at a dot-separated path.
  *
  * @example
  * ```ts
- * LeafValue<{ a: { b: { c: string } } }, "a.b.c"> // → string
+ * AtPath<{ a: { b: { c: string } } }, "a.b">; // => { c: string };
  * ```
  */
-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 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 type located at a dot-separated path.
- *
- * The resolved type may be a subtree or a leaf value.
+ * Dot-separated leaf keys derived from a single message object.
  *
  * @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 };
+ * Key<{ a: { b: { c: string }; z: string } }>; // => "a.z" | "a.b.c"
  * ```
  */
-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 Key<M> = GeneratePaths<M, false>;
 /**
- * Extracts all **node keys** from the messages
- * of a specified locale (or union of locales).
+ * Leaf 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
- * 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
+ * LocalizedKey<{ en: { a: { b: { c: string }; z: string } } }>; // =>  "a.z" | "a.b.c"
  * ```
  */
-type LocalizedNodeKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? NodeKeys<M[keyof M], D> : string;
+type LocalizedKey<M> = IfLocaleMessages<M, Key<IfMessageObject<M[keyof M]>>, string>;
 /**
- * Extracts all **leaf keys** from the messages
- * of a specified locale (or union of locales).
+ * Leaf keys scoped under a given prefix key.
  *
  * @example
  * ```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"
+ *  ScopedKey<{ en: { a: { b: { c: string }; z: string } } }, "a">; // => "b.c" | "z"
+ * ```
+ */
+type ScopedKey<M, PK extends string> = IfLocaleMessages<M, Key<IfMessageObject<AtPath<M[keyof M], PK>>>, string>;
+
+/**
+ * Prefix keys that may resolve to intermediate or leaf paths.
  *
- * // 3. Fallback if M is not LocaleMessages
- * LocalizedLeafKeys // → string
+ * @example
+ * ```ts
+ * PreKey<{ a: { b: { c: string }; z: string } }>; // → "a" | "a.b" | "a.z" | "a.b.c"
  * ```
  */
-type LocalizedLeafKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? LeafKeys<M[keyof M], D> : string;
+type PreKey<M> = GeneratePaths<M, true>;
 /**
- * Resolves the value type of a **localized leaf key**
- * from the messages of a specified locale (or union of locales).
+ * Prefix keys resolved from localized messages (union of all locales).
  *
- * - Fallback to `MessageValue` if M is not LocaleMessages
+ * @example
+ * ```ts
+ * LocalizedPreKey<{ en: { a: { b: { c: string }; z: string } } }>; // →   "a" | "a.b" | "a.z" | "a.b.c"
+ * ```
  */
-type LocalizedLeafValue<M = unknown, K extends string = string> = M extends LocaleMessages ? LeafValue<M[keyof M], K> : MessageValue;
+type LocalizedPreKey<M> = IfLocaleMessages<M, PreKey<IfMessageObject<M[keyof M]>>, string>;
 
 /**
- * Extracts all **leaf keys** under a scoped path (`PK`) from the messages
- * of a specified locale (`L`) (or union of locales).
+ * Resolves the value type at a dot-separated path.
  *
  * @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"
+ * Value<{ a: { b: { c: string } } }, "a.b.c">; // => string
  * ```
  */
-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 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;
 /**
- * Resolves the value type of a scoped leaf key (`K`)
- * under a prefix path (`PK`) from localized messages.
+ * Value resolved from localized messages (union of all locales).
  *
  * @example
  * ```ts
- * const messages = {
- *   en: { a: { b: { c: "hello" }, z: [123] } },
- * };
+ * LocalizedValue<{ en: { a: { b: { c: string }; z: string } } }, "a.b.c">; // => string
+ * ```
+ */
+type LocalizedValue<M, K extends string> = IfLocaleMessages<M, Value<M[keyof M], K>, MessageValue>;
+/**
+ * Value resolved under a scoped prefix key.
  *
- * ScopedLeafValue<typeof messages, "a", "z">;  // number[]
- * ScopedLeafValue<typeof messages, "a.b", "c">;  // string
+ * @example
+ * ```ts
+ * ScopedValue<{ en: { a: { b: { c: string }; z: string } } }, "a", "b.c">; // => string
  * ```
  */
-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 ScopedValue<M, PK extends string, K extends string> = IfLocaleMessages<M, Value<AtPath<M[keyof M], PK>, K>, MessageValue>;
 
 /**
- * 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.
+ * Generic replacement object used when no schema is available.
  *
- * @example
- * const replacements: Replacement = {
- *   name: "Alice",
- *   count: 5,
- *   nested: {
- *     score: 100,
- *   },
- * };
+ * Acts as a safe fallback for dynamic or unknown replacement shapes.
  */
 type Replacement = Record<string, unknown>;
 /**
- * Resolves the expected replacement type for a localized message key.
+ * Replacement object resolved from a localized replacement schema.
  *
- * Uses the canonical (default-locale) replacement schema when available,
- * otherwise falls back to `Replacement`.
+ * - If the key exists in the schema, resolves to the declared object shape
+ * - Otherwise falls back to generic `Replacement`
  *
  * @example
  * ```ts
- * type RMap = {
- *   "{locale}": {
- *     welcome: { name: MessageValue };
- *     total: { count: MessageValue };
- *   };
- * };
- *
- * type WelcomeReplacement = LocalizedReplacement<RMap, "welcome">;
- * // => { name: MessageValue }
- *
- * type UnknownReplacement = LocalizedReplacement<RMap, "unknown">;
- * // => Replacement
+ * type ReplacementSchema = { "{locale}": { greeting: { name: string } } };
+ * LocalizedReplacement<ReplacementSchema, "greeting">; // => { name: string }
+ * LocalizedReplacement<ReplacementSchema, "missing">;  // => Replacement
  * ```
  */
 type LocalizedReplacement<ReplacementSchema, K extends string> = ReplacementSchema extends {
     "{locale}": infer LM;
-} ? AtPath<LM, K> extends infer R ? R extends MessageObject ? R : Replacement : Replacement : Replacement;
+} ? IsNever<AtPath<LM, K>> extends true ? Replacement : AtPath<LM, K> extends MessageObject ? AtPath<LM, K> : Replacement : Replacement;
+/**
+ * Replacement object resolved under a scoped prefix key.
+ *
+ * Internally composes the full dot-path (`"${PK}.${K}"`)
+ * and delegates resolution to `LocalizedReplacement`.
+ *
+ * @example
+ * ```ts
+ * type ReplacementSchema = { "{locale}": { user: { info: { name: string } } } };
+ * ScopedReplacement<ReplacementSchema, "user", "info">; // => { name: string }
+ * ScopedReplacement<ReplacementSchema, "user", "missing">; // => Replacement
+ * ```
+ */
+type ScopedReplacement<ReplacementSchema, PK extends string | undefined, K extends string> = LocalizedReplacement<ReplacementSchema, `${PK}.${K}`>;
 
 /**
  * Options for initializing a translator
@@ -427,23 +401,21 @@ declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, Repla
     /** 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, ...replacementArgs: [LocalizedReplacement<ReplacementSchema, K>?]) => 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, ReplacementSchema = 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 extends K>(key?: Key, ...replacementArgs: [
-        LocalizedReplacement<ReplacementSchema, PK extends string ? `${PK}.${Key & string}` : Key>?
-    ]) => PK extends string ? ScopedLeafValue<M, PK, Key> : LocalizedLeafValue<M, Key>;
+    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, 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, ReplacementSchema, PK> : ScopeTranslatorMethods<M, ReplacementSchema>;
+    scoped<PK extends LocalizedPreKey<M> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, ReplacementSchema, PK> : ScopeTranslatorMethods<M, ReplacementSchema>;
 }
 
 /** Semantic tag attributes map. */
@@ -518,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 LocalizedReplacement, 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

@@ -293,7 +293,7 @@ var CoreTranslator = class extends BaseTranslator {
     });
   };
   /** Get the translated message for a key, with optional replacements. */
-  t = (key, ...replacementArgs) => {
+  t = (key, replacements) => {
     return translate({
       hooks: this.hooks,
       messages: this._messages,
@@ -301,7 +301,7 @@ var CoreTranslator = class extends BaseTranslator {
       isLoading: this._isLoading,
       translateConfig: this.translateConfig,
       key,
-      replacements: replacementArgs[0]
+      replacements
     });
   };
 };
@@ -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.7",
+  "version": "1.4.9",
   "description": "🤖 A modern, type-safe i18n engine.",
   "author": {
     "name": "Yiming Liao",