intor-translator 1.4.6 → 1.4.7

package/dist/index.cjs

@@ -3,6 +3,15 @@
 var rura = require('rura');
 
 // src/translators/core-translator/core-translator.ts
+function runTranslate(options) {
+  const context = {
+    ...options,
+    config: options.translateConfig,
+    candidateLocales: [],
+    meta: {}
+  };
+  return rura.rura.run(context, options.hooks);
+}
 
 // src/shared/utils/find-message-in-locales.ts
 var findMessageInLocales = ({
@@ -231,15 +240,6 @@ var hasKey = ({
   const message = findMessageInLocales({ messages, candidateLocales, key });
   return message !== void 0;
 };
-function runTranslate(options) {
-  const context = {
-    ...options,
-    config: options.translateConfig,
-    candidateLocales: [],
-    meta: {}
-  };
-  return rura.rura.run(context, options.hooks);
-}
 
 // src/translators/methods/translate.ts
 function translate(options) {
@@ -295,7 +295,7 @@ var CoreTranslator = class extends BaseTranslator {
     });
   };
   /** Get the translated message for a key, with optional replacements. */
-  t = (key, replacements) => {
+  t = (key, ...replacementArgs) => {
     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
+      replacements: replacementArgs[0]
     });
   };
 };
@@ -332,7 +332,7 @@ var ScopeTranslator = class extends CoreTranslator {
           targetLocale
         });
       },
-      t: (key, replacements) => {
+      t: (key, ...args) => {
         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
+          replacements: args[0]
         });
       }
     };

package/dist/index.d.cts

@@ -42,30 +42,6 @@ type MessageLeaf = MessagePrimitive | MessageArray;
  * ```
  */
 type LocaleMessages = Record<string, MessageObject>;
-/**
- * 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: { greeting: { morning: "morning" } },
- *   zh: { greeting: { evening: "晚上好" } },
- * };
- *
- * // 1. Union of all locales
- * UnionLocaleMessages<typeof messages>;
- * // → { greeting: { morning: string; }; } | { greeting: { evening: string; }; }
- *
- * // 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 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.
@@ -106,25 +82,6 @@ type Locale<M = unknown> = M extends LocaleMessages ? keyof M & string : string;
  */
 type FallbackLocalesMap<L extends string = string> = Partial<Record<L, L[]>>;
 
-/**
- * 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
- * const replacements: Replacement = {
- *   name: "Alice",
- *   count: 5,
- *   nested: {
- *     score: 100
- *   },
- *   formatter: (value: unknown) => `<b>${value}</b>`
- * };
- */
-type Replacement = Record<string, unknown>;
-
 /**
  * Default maximum recursive depth for nested key type computations,
  * balancing type safety and compiler performance.
@@ -164,6 +121,19 @@ type LeafKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never
  * ```
  */
 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;
+/**
+ * Resolves the type located at a dot-separated path.
+ *
+ * The resolved type may be a subtree or a leaf value.
+ *
+ * @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 };
+ * ```
+ */
+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;
 
 /**
  * Extracts all **node keys** from the messages
@@ -187,7 +157,7 @@ type LeafValue<M, K extends string> = K extends `${infer Seg}.${infer Rest}` ? S
  * LocalizedNodeKeys // → string
  * ```
  */
-type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? L extends "union" ? NodeKeys<M[keyof M], D> : NodeKeys<M[Extract<L, keyof M>], D> : string;
+type LocalizedNodeKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? NodeKeys<M[keyof M], D> : string;
 /**
  * Extracts all **leaf keys** from the messages
  * of a specified locale (or union of locales).
@@ -210,32 +180,15 @@ type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D ext
  * LocalizedLeafKeys // → string
  * ```
  */
-type LocalizedLeafKeys<M = unknown, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? L extends "union" ? LeafKeys<M[keyof M], D> : LeafKeys<M[Extract<L, keyof M>], D> : string;
+type LocalizedLeafKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? LeafKeys<M[keyof M], D> : string;
 /**
  * Resolves the value type of a **localized leaf key**
  * from the messages of a specified locale (or union of locales).
  *
  * - Fallback to `MessageValue` if M is not LocaleMessages
  */
-type LocalizedLeafValue<M = unknown, K extends string = string, L extends keyof M | "union" = "union"> = M extends LocaleMessages ? L extends "union" ? LeafValue<M[keyof M], K> : LeafValue<M[Extract<L, keyof M>], K> : MessageValue;
+type LocalizedLeafValue<M = unknown, K extends string = string> = M extends LocaleMessages ? LeafValue<M[keyof M], K> : MessageValue;
 
-/**
- * Resolves the type at a dot-separated key in a nested object.
- *
- * @example
- * ```ts
- * const structure = {
- *   a: {
- *     b: { c: "hello" },
- *     z: "world",
- *   },
- * };
- *
- * MessagesAtPreKey<typeof structure, "a"> // → { b: { c: string; }; z: string;}
- * MessagesAtPreKey<typeof structure, "a.b"> // → { c: string; };
- * ```
- */
-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;
 /**
  * Extracts all **leaf keys** under a scoped path (`PK`) from the messages
  * of a specified locale (`L`) (or union of locales).
@@ -252,7 +205,7 @@ type MessagesAtPreKey<T, PK extends string> = PK extends `${infer Head}.${infer
  * ScopedLeafKeys<typeof messages, "a", "zh">; // →  "b"
  * ```
  */
-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 MessageValue ? MessagesAtPreKey<Messages, PK> extends infer Scoped ? Scoped extends MessageObject ? LeafKeys<Scoped, D> : never : never : never : never : 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;
 /**
  * Resolves the value type of a scoped leaf key (`K`)
  * under a prefix path (`PK`) from localized messages.
@@ -267,7 +220,108 @@ type ScopedLeafKeys<M, PK extends string, L extends keyof M | "union" = "union",
  * ScopedLeafValue<typeof messages, "a.b", "c">;  // string
  * ```
  */
-type ScopedLeafValue<M, PK extends string, K extends string, L extends keyof M | "union" = "union"> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends infer Messages ? Messages extends MessageValue ? MessagesAtPreKey<Messages, PK> extends infer Scoped ? Scoped extends MessageObject ? LeafValue<Scoped, K> : never : never : never : never : MessageValue;
+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;
+
+/**
+ * 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, unknown>;
+/**
+ * Resolves the expected replacement type for a localized message key.
+ *
+ * Uses the canonical (default-locale) replacement schema when available,
+ * otherwise falls back to `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 LocalizedReplacement<ReplacementSchema, K extends string> = ReplacementSchema extends {
+    "{locale}": infer LM;
+} ? AtPath<LM, K> extends infer R ? R extends MessageObject ? R : Replacement : Replacement : 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>;
+    /**
+     * Current locale key.
+     * - If `messages` is typed as `LocaleMessages`, this can be inferred automatically.
+     */
+    locale: Locale<M>;
+    /**
+     * Indicates whether the translator is in a loading state.
+     */
+    isLoading?: boolean;
+}
+
+/**
+ * The minimal, shared foundation for all translators.
+ *
+ * @template M - Shape of the messages object.
+ */
+declare class BaseTranslator<M extends LocaleMessages | unknown = unknown> {
+    /** Current messages for translation */
+    protected _messages: Readonly<M>;
+    /** Current active locale */
+    protected _locale: Locale<M>;
+    /** Current loading state */
+    protected _isLoading: boolean;
+    constructor(options: BaseTranslatorOptions<M>);
+    /** Get messages. */
+    get messages(): M;
+    /** Get the current active locale. */
+    get locale(): Locale<M>;
+    /** Get the current loading state. */
+    get isLoading(): boolean;
+    /**
+     * Replace messages with new ones.
+     *
+     * - 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 LocaleMessages>(messages: N): void;
+    /**
+     * Set the active locale.
+     *
+     * - Note: Unlike `setMessages`, the locale structure cannot be changed at runtime.
+     */
+    setLocale(newLocale: Locale<M>): void;
+    /** Set the loading state. */
+    setLoading(state: boolean): void;
+}
 
 /**
  * Configuration options for translation behavior.
@@ -343,64 +397,6 @@ interface TranslateContext {
  */
 type TranslateHook = RuraHook<TranslateContext, MessageValue>;
 
-/**
- * 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>;
-    /**
-     * Current locale key.
-     * - If `messages` is typed as `LocaleMessages`, this can be inferred automatically.
-     */
-    locale: Locale<M>;
-    /**
-     * Indicates whether the translator is in a loading state.
-     */
-    isLoading?: boolean;
-}
-
-/**
- * The minimal, shared foundation for all translators.
- *
- * @template M - Shape of the messages object.
- */
-declare class BaseTranslator<M extends LocaleMessages | unknown = unknown> {
-    /** Current messages for translation */
-    protected _messages: Readonly<M>;
-    /** Current active locale */
-    protected _locale: Locale<M>;
-    /** Current loading state */
-    protected _isLoading: boolean;
-    constructor(options: BaseTranslatorOptions<M>);
-    /** Get messages. */
-    get messages(): M;
-    /** Get the current active locale. */
-    get locale(): Locale<M>;
-    /** Get the current loading state. */
-    get isLoading(): boolean;
-    /**
-     * Replace messages with new ones.
-     *
-     * - 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 LocaleMessages>(messages: N): void;
-    /**
-     * Set the active locale.
-     *
-     * - Note: Unlike `setMessages`, the locale structure cannot be changed at runtime.
-     */
-    setLocale(newLocale: Locale<M>): void;
-    /** Set the loading state. */
-    setLoading(state: boolean): void;
-}
-
 interface CoreTranslatorOptions<M> extends BaseTranslatorOptions<M>, TranslateConfig<M> {
     /** Optional plugins or raw hooks to extend the translation pipeline */
     plugins?: Array<TranslatorPlugin | TranslateHook>;
@@ -417,9 +413,8 @@ interface TranslatorPlugin {
  * using the pipeline engine and built-in hooks.
  *
  * @template M - Shape of the messages object.
- * @template L - Locale selection strategy ("union" or specific locale keys).
  */
-declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, L extends keyof M | "union" = "union"> 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. */
@@ -432,21 +427,23 @@ declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, L ext
     /** 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, L>>(key: K, targetLocale?: Locale<M>) => boolean;
+    hasKey: <K extends LocalizedLeafKeys<M>>(key: K, targetLocale?: Locale<M>) => boolean;
     /** Get the translated message for a key, with optional replacements. */
-    t: <K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => LocalizedLeafValue<M, K, L>;
+    t: <K extends LocalizedLeafKeys<M> = LocalizedLeafKeys<M>>(key: K, ...replacementArgs: [LocalizedReplacement<ReplacementSchema, K>?]) => LocalizedLeafValue<M, K>;
 }
 
 type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
-type ScopeTranslatorMethods<M extends LocaleMessages | unknown = unknown, L extends keyof M | "union" = "union", PK extends string | undefined = undefined, K extends string = PK extends string ? ScopedLeafKeys<M, PK, L> : LocalizedLeafKeys<M, L>> = {
+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>> = {
     hasKey: (key?: K, targetLocale?: Locale<M>) => boolean;
-    t: <Key extends K>(key?: Key, replacements?: Replacement) => PK extends string ? ScopedLeafValue<M, PK, Key, L> : LocalizedLeafValue<M, Key, L>;
+    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>;
 };
 
-declare class ScopeTranslator<M extends LocaleMessages | unknown = unknown, L extends keyof M | "union" = "union"> 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, L> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, L, PK> : ScopeTranslatorMethods<M, L>;
+    scoped<PK extends LocalizedNodeKeys<M> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, ReplacementSchema, PK> : ScopeTranslatorMethods<M, ReplacementSchema>;
 }
 
 /** Semantic tag attributes map. */
@@ -521,4 +518,4 @@ interface Renderer<Output> {
  */
 declare function renderRichMessage<Output>(message: MessageValue, renderer: Renderer<Output>): Output[];
 
-export { type ASTNode, 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 LocalizedMessagesUnion, 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 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 };

package/dist/index.d.ts

@@ -42,30 +42,6 @@ type MessageLeaf = MessagePrimitive | MessageArray;
  * ```
  */
 type LocaleMessages = Record<string, MessageObject>;
-/**
- * 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: { greeting: { morning: "morning" } },
- *   zh: { greeting: { evening: "晚上好" } },
- * };
- *
- * // 1. Union of all locales
- * UnionLocaleMessages<typeof messages>;
- * // → { greeting: { morning: string; }; } | { greeting: { evening: string; }; }
- *
- * // 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 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.
@@ -106,25 +82,6 @@ type Locale<M = unknown> = M extends LocaleMessages ? keyof M & string : string;
  */
 type FallbackLocalesMap<L extends string = string> = Partial<Record<L, L[]>>;
 
-/**
- * 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
- * const replacements: Replacement = {
- *   name: "Alice",
- *   count: 5,
- *   nested: {
- *     score: 100
- *   },
- *   formatter: (value: unknown) => `<b>${value}</b>`
- * };
- */
-type Replacement = Record<string, unknown>;
-
 /**
  * Default maximum recursive depth for nested key type computations,
  * balancing type safety and compiler performance.
@@ -164,6 +121,19 @@ type LeafKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never
  * ```
  */
 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;
+/**
+ * Resolves the type located at a dot-separated path.
+ *
+ * The resolved type may be a subtree or a leaf value.
+ *
+ * @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 };
+ * ```
+ */
+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;
 
 /**
  * Extracts all **node keys** from the messages
@@ -187,7 +157,7 @@ type LeafValue<M, K extends string> = K extends `${infer Seg}.${infer Rest}` ? S
  * LocalizedNodeKeys // → string
  * ```
  */
-type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? L extends "union" ? NodeKeys<M[keyof M], D> : NodeKeys<M[Extract<L, keyof M>], D> : string;
+type LocalizedNodeKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? NodeKeys<M[keyof M], D> : string;
 /**
  * Extracts all **leaf keys** from the messages
  * of a specified locale (or union of locales).
@@ -210,32 +180,15 @@ type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D ext
  * LocalizedLeafKeys // → string
  * ```
  */
-type LocalizedLeafKeys<M = unknown, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? L extends "union" ? LeafKeys<M[keyof M], D> : LeafKeys<M[Extract<L, keyof M>], D> : string;
+type LocalizedLeafKeys<M = unknown, D extends number = DefaultDepth> = M extends LocaleMessages ? LeafKeys<M[keyof M], D> : string;
 /**
  * Resolves the value type of a **localized leaf key**
  * from the messages of a specified locale (or union of locales).
  *
  * - Fallback to `MessageValue` if M is not LocaleMessages
  */
-type LocalizedLeafValue<M = unknown, K extends string = string, L extends keyof M | "union" = "union"> = M extends LocaleMessages ? L extends "union" ? LeafValue<M[keyof M], K> : LeafValue<M[Extract<L, keyof M>], K> : MessageValue;
+type LocalizedLeafValue<M = unknown, K extends string = string> = M extends LocaleMessages ? LeafValue<M[keyof M], K> : MessageValue;
 
-/**
- * Resolves the type at a dot-separated key in a nested object.
- *
- * @example
- * ```ts
- * const structure = {
- *   a: {
- *     b: { c: "hello" },
- *     z: "world",
- *   },
- * };
- *
- * MessagesAtPreKey<typeof structure, "a"> // → { b: { c: string; }; z: string;}
- * MessagesAtPreKey<typeof structure, "a.b"> // → { c: string; };
- * ```
- */
-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;
 /**
  * Extracts all **leaf keys** under a scoped path (`PK`) from the messages
  * of a specified locale (`L`) (or union of locales).
@@ -252,7 +205,7 @@ type MessagesAtPreKey<T, PK extends string> = PK extends `${infer Head}.${infer
  * ScopedLeafKeys<typeof messages, "a", "zh">; // →  "b"
  * ```
  */
-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 MessageValue ? MessagesAtPreKey<Messages, PK> extends infer Scoped ? Scoped extends MessageObject ? LeafKeys<Scoped, D> : never : never : never : never : 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;
 /**
  * Resolves the value type of a scoped leaf key (`K`)
  * under a prefix path (`PK`) from localized messages.
@@ -267,7 +220,108 @@ type ScopedLeafKeys<M, PK extends string, L extends keyof M | "union" = "union",
  * ScopedLeafValue<typeof messages, "a.b", "c">;  // string
  * ```
  */
-type ScopedLeafValue<M, PK extends string, K extends string, L extends keyof M | "union" = "union"> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends infer Messages ? Messages extends MessageValue ? MessagesAtPreKey<Messages, PK> extends infer Scoped ? Scoped extends MessageObject ? LeafValue<Scoped, K> : never : never : never : never : MessageValue;
+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;
+
+/**
+ * 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, unknown>;
+/**
+ * Resolves the expected replacement type for a localized message key.
+ *
+ * Uses the canonical (default-locale) replacement schema when available,
+ * otherwise falls back to `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 LocalizedReplacement<ReplacementSchema, K extends string> = ReplacementSchema extends {
+    "{locale}": infer LM;
+} ? AtPath<LM, K> extends infer R ? R extends MessageObject ? R : Replacement : Replacement : 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>;
+    /**
+     * Current locale key.
+     * - If `messages` is typed as `LocaleMessages`, this can be inferred automatically.
+     */
+    locale: Locale<M>;
+    /**
+     * Indicates whether the translator is in a loading state.
+     */
+    isLoading?: boolean;
+}
+
+/**
+ * The minimal, shared foundation for all translators.
+ *
+ * @template M - Shape of the messages object.
+ */
+declare class BaseTranslator<M extends LocaleMessages | unknown = unknown> {
+    /** Current messages for translation */
+    protected _messages: Readonly<M>;
+    /** Current active locale */
+    protected _locale: Locale<M>;
+    /** Current loading state */
+    protected _isLoading: boolean;
+    constructor(options: BaseTranslatorOptions<M>);
+    /** Get messages. */
+    get messages(): M;
+    /** Get the current active locale. */
+    get locale(): Locale<M>;
+    /** Get the current loading state. */
+    get isLoading(): boolean;
+    /**
+     * Replace messages with new ones.
+     *
+     * - 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 LocaleMessages>(messages: N): void;
+    /**
+     * Set the active locale.
+     *
+     * - Note: Unlike `setMessages`, the locale structure cannot be changed at runtime.
+     */
+    setLocale(newLocale: Locale<M>): void;
+    /** Set the loading state. */
+    setLoading(state: boolean): void;
+}
 
 /**
  * Configuration options for translation behavior.
@@ -343,64 +397,6 @@ interface TranslateContext {
  */
 type TranslateHook = RuraHook<TranslateContext, MessageValue>;
 
-/**
- * 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>;
-    /**
-     * Current locale key.
-     * - If `messages` is typed as `LocaleMessages`, this can be inferred automatically.
-     */
-    locale: Locale<M>;
-    /**
-     * Indicates whether the translator is in a loading state.
-     */
-    isLoading?: boolean;
-}
-
-/**
- * The minimal, shared foundation for all translators.
- *
- * @template M - Shape of the messages object.
- */
-declare class BaseTranslator<M extends LocaleMessages | unknown = unknown> {
-    /** Current messages for translation */
-    protected _messages: Readonly<M>;
-    /** Current active locale */
-    protected _locale: Locale<M>;
-    /** Current loading state */
-    protected _isLoading: boolean;
-    constructor(options: BaseTranslatorOptions<M>);
-    /** Get messages. */
-    get messages(): M;
-    /** Get the current active locale. */
-    get locale(): Locale<M>;
-    /** Get the current loading state. */
-    get isLoading(): boolean;
-    /**
-     * Replace messages with new ones.
-     *
-     * - 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 LocaleMessages>(messages: N): void;
-    /**
-     * Set the active locale.
-     *
-     * - Note: Unlike `setMessages`, the locale structure cannot be changed at runtime.
-     */
-    setLocale(newLocale: Locale<M>): void;
-    /** Set the loading state. */
-    setLoading(state: boolean): void;
-}
-
 interface CoreTranslatorOptions<M> extends BaseTranslatorOptions<M>, TranslateConfig<M> {
     /** Optional plugins or raw hooks to extend the translation pipeline */
     plugins?: Array<TranslatorPlugin | TranslateHook>;
@@ -417,9 +413,8 @@ interface TranslatorPlugin {
  * using the pipeline engine and built-in hooks.
  *
  * @template M - Shape of the messages object.
- * @template L - Locale selection strategy ("union" or specific locale keys).
  */
-declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, L extends keyof M | "union" = "union"> 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. */
@@ -432,21 +427,23 @@ declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, L ext
     /** 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, L>>(key: K, targetLocale?: Locale<M>) => boolean;
+    hasKey: <K extends LocalizedLeafKeys<M>>(key: K, targetLocale?: Locale<M>) => boolean;
     /** Get the translated message for a key, with optional replacements. */
-    t: <K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => LocalizedLeafValue<M, K, L>;
+    t: <K extends LocalizedLeafKeys<M> = LocalizedLeafKeys<M>>(key: K, ...replacementArgs: [LocalizedReplacement<ReplacementSchema, K>?]) => LocalizedLeafValue<M, K>;
 }
 
 type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
-type ScopeTranslatorMethods<M extends LocaleMessages | unknown = unknown, L extends keyof M | "union" = "union", PK extends string | undefined = undefined, K extends string = PK extends string ? ScopedLeafKeys<M, PK, L> : LocalizedLeafKeys<M, L>> = {
+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>> = {
     hasKey: (key?: K, targetLocale?: Locale<M>) => boolean;
-    t: <Key extends K>(key?: Key, replacements?: Replacement) => PK extends string ? ScopedLeafValue<M, PK, Key, L> : LocalizedLeafValue<M, Key, L>;
+    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>;
 };
 
-declare class ScopeTranslator<M extends LocaleMessages | unknown = unknown, L extends keyof M | "union" = "union"> 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, L> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, L, PK> : ScopeTranslatorMethods<M, L>;
+    scoped<PK extends LocalizedNodeKeys<M> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, ReplacementSchema, PK> : ScopeTranslatorMethods<M, ReplacementSchema>;
 }
 
 /** Semantic tag attributes map. */
@@ -521,4 +518,4 @@ interface Renderer<Output> {
  */
 declare function renderRichMessage<Output>(message: MessageValue, renderer: Renderer<Output>): Output[];
 
-export { type ASTNode, 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 LocalizedMessagesUnion, 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 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 };

package/dist/index.js

@@ -1,6 +1,15 @@
 import { rura } from 'rura';
 
 // src/translators/core-translator/core-translator.ts
+function runTranslate(options) {
+  const context = {
+    ...options,
+    config: options.translateConfig,
+    candidateLocales: [],
+    meta: {}
+  };
+  return rura.run(context, options.hooks);
+}
 
 // src/shared/utils/find-message-in-locales.ts
 var findMessageInLocales = ({
@@ -229,15 +238,6 @@ var hasKey = ({
   const message = findMessageInLocales({ messages, candidateLocales, key });
   return message !== void 0;
 };
-function runTranslate(options) {
-  const context = {
-    ...options,
-    config: options.translateConfig,
-    candidateLocales: [],
-    meta: {}
-  };
-  return rura.run(context, options.hooks);
-}
 
 // src/translators/methods/translate.ts
 function translate(options) {
@@ -293,7 +293,7 @@ var CoreTranslator = class extends BaseTranslator {
     });
   };
   /** Get the translated message for a key, with optional replacements. */
-  t = (key, replacements) => {
+  t = (key, ...replacementArgs) => {
     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
+      replacements: replacementArgs[0]
     });
   };
 };
@@ -330,7 +330,7 @@ var ScopeTranslator = class extends CoreTranslator {
           targetLocale
         });
       },
-      t: (key, replacements) => {
+      t: (key, ...args) => {
         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
+          replacements: args[0]
         });
       }
     };

package/package.json

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