intor-translator 1.4.2 → 1.4.4

package/dist/index.cjs

@@ -121,7 +121,7 @@ var loading = rura.rura.createHook(
       };
     }
     const { loadingMessage } = config;
-    if ("loadingMessage" in config) {
+    if (loadingMessage !== void 0) {
       return { early: true, output: loadingMessage };
     }
   },
@@ -140,7 +140,7 @@ var missing = rura.rura.createHook(
       };
     }
     const { missingMessage } = config;
-    if ("missingMessage" in config) {
+    if (missingMessage !== void 0) {
       return { early: true, output: missingMessage };
     }
     return { early: true, output: key };
@@ -176,6 +176,7 @@ var DEFAULT_HOOKS = [
   format,
   interpolate
 ];
+rura.rura.createPipeline(DEFAULT_HOOKS).debugHooks();
 
 // src/translators/base-translator/base-translator.ts
 var BaseTranslator = class {
@@ -250,12 +251,18 @@ function runTranslate(options) {
 function translate(options) {
   const { early, ctx, output } = runTranslate(options);
   if (early === true) return output;
+  if (ctx.finalMessage === void 0) {
+    throw new Error("Invariant violated: missing hook did not produce output");
+  }
   return ctx.finalMessage;
 }
 
 // src/translators/methods/translate-raw.ts
 function translateRaw(options) {
   const { ctx } = runTranslate(options);
+  if (ctx.rawValue === void 0) {
+    throw new Error("Invariant violated: missing hook did not produce output");
+  }
   return ctx.rawValue;
 }
 
@@ -502,18 +509,44 @@ function buildAST(tokens) {
 
 // src/message/parse-rich-message.ts
 function parseRichMessage(message) {
-  const tokens = tokenize(message);
-  return buildAST(tokens);
+  if (message == null) return [];
+  if (typeof message === "string") {
+    const tokens = tokenize(message);
+    return buildAST(tokens);
+  }
+  if (typeof message === "number" || typeof message === "boolean") {
+    const tokens = tokenize(String(message));
+    return buildAST(tokens);
+  }
+  if (Array.isArray(message)) {
+    return message.flatMap((m) => parseRichMessage(m));
+  }
+  return [
+    {
+      type: "raw",
+      value: message
+    }
+  ];
 }
 
 // src/message/render/render.ts
 function render(nodes, renderer) {
   return nodes.map((node) => {
-    if (node.type === "text") {
-      return renderer.text(node.value);
+    switch (node.type) {
+      // Plain text node
+      case "text": {
+        return renderer.text(node.value);
+      }
+      // Semantic tag node
+      case "tag": {
+        const children = render(node.children, renderer);
+        return renderer.tag(node.name, node.attributes, children);
+      }
+      // Raw message value
+      case "raw": {
+        return renderer.raw(node.value);
+      }
     }
-    const children = render(node.children, renderer);
-    return renderer.tag(node.name, node.attributes, children);
   });
 }
 

package/dist/index.d.cts

@@ -1,19 +1,5 @@
 import { RuraHook } from 'rura';
 
-type MessagePrimitive$1 = string | number | boolean | null;
-type MessageArray$1 = readonly MessageValue$1[];
-/**
- * A recursive message tree object.
- *
- * Represents the root message structure for a single locale
- * (i.e. the value of `LocaleMessages[locale]`).
- */
-interface MessageObject$1 {
-    [key: string]: MessageValue$1;
-}
-/** A message value in the locale message tree. */
-type MessageValue$1 = MessagePrimitive$1 | MessageObject$1 | MessageArray$1;
-
 type MessagePrimitive = string | number | boolean | null;
 type MessageArray = readonly MessageValue[];
 /**
@@ -168,6 +154,16 @@ type NodeKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never
 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;
+/**
+ * Resolves the value type at a given dot-separated leaf key
+ * within a nested message object.
+ *
+ * @example
+ * ```ts
+ * LeafValue<{ 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;
 
 /**
  * Extracts all **node keys** from the messages
@@ -215,6 +211,13 @@ type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D ext
  * ```
  */
 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;
+/**
+ * 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;
 
 /**
  * Resolves the type at a dot-separated key in a nested object.
@@ -250,6 +253,21 @@ type MessagesAtPreKey<T, PK extends string> = PK extends `${infer Head}.${infer
  * ```
  */
 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;
+/**
+ * Resolves the value type of a scoped leaf key (`K`)
+ * under a prefix path (`PK`) from localized messages.
+ *
+ * @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 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;
 
 /**
  * Configuration options for translation behavior.
@@ -276,13 +294,13 @@ type TranslateHandlers = {
     formatHandler?: FormatHandler;
 };
 /** Function called when translation is still loading. */
-type LoadingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
+type LoadingHandler = (ctx: HandlerContext) => MessageValue;
 /** Function called when no message is found for the given key. */
-type MissingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
+type MissingHandler = (ctx: HandlerContext) => MessageValue;
 /** Function to format a resolved message. */
-type FormatHandler<Result = unknown> = (ctx: HandlerContext & {
+type FormatHandler = (ctx: HandlerContext & {
     rawString: string;
-}) => Result;
+}) => MessageValue;
 /**
  * Snapshot of the translate pipeline context exposed to handlers.
  *
@@ -295,10 +313,8 @@ type HandlerContext = Readonly<Omit<TranslateContext, "finalMessage">>;
 
 /**
  * Context object shared across the translate pipeline.
- *
- * @template Result - Final translated value type.
  */
-interface TranslateContext<Result = unknown> {
+interface TranslateContext {
     /** Configuration for the translate pipeline. */
     config: TranslateConfig;
     /** Current messages for translation */
@@ -318,16 +334,16 @@ interface TranslateContext<Result = unknown> {
     /** Raw string message before formatting. */
     rawString?: string;
     /** Message after formatting (e.g. ICU, custom formatters) */
-    formattedMessage?: unknown;
+    formattedMessage?: MessageValue;
     /** Final value produced by the pipeline */
-    finalMessage?: Result;
+    finalMessage?: MessageValue;
     /** Free-form metadata shared between hooks. */
     meta: Record<string, unknown>;
 }
 /**
  * A single step in the translate pipeline.
  */
-type TranslateHook = RuraHook<TranslateContext>;
+type TranslateHook = RuraHook<TranslateContext, MessageValue>;
 
 /**
  * Options for initializing a translator
@@ -420,29 +436,29 @@ declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, L ext
     /** Check if a key exists in the specified locale or current locale. */
     hasKey: <K extends LocalizedLeafKeys<M, L>>(key: K, targetLocale?: Locale<M>) => boolean;
     /** Get the translated message for a key, with optional replacements. */
-    t: <Result = string, K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => Result;
+    t: <K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => LocalizedLeafValue<M, K, L>;
     /** Get the raw message value for a key without formatting or interpolation. */
-    tRaw: <K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => MessageValue | undefined;
+    tRaw: <K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => LocalizedLeafValue<M, K, L>;
 }
 
 type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
-type ScopeTranslatorMethods<M extends LocaleMessages | unknown = unknown, L extends keyof M | "union" = "union", K = LocalizedLeafKeys<M, L>> = {
+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>> = {
     hasKey: (key?: K, targetLocale?: Locale<M>) => boolean;
-    t: <Result = string>(key?: K, replacements?: Replacement) => Result;
-    tRaw: (key?: K, replacements?: Replacement) => MessageValue$1 | undefined;
+    t: <Key extends K>(key?: Key, replacements?: Replacement) => PK extends string ? ScopedLeafValue<M, PK, Key, L> : LocalizedLeafValue<M, Key, L>;
+    tRaw: <Key extends K>(key?: Key, replacements?: Replacement) => PK extends string ? ScopedLeafValue<M, PK, Key, L> : LocalizedLeafValue<M, Key, L>;
 };
 
 declare class ScopeTranslator<M extends LocaleMessages | unknown = unknown, L extends keyof M | "union" = "union"> extends CoreTranslator<M> {
     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, ScopedLeafKeys<M, PK, L>> : ScopeTranslatorMethods<M, L>;
+    scoped<PK extends LocalizedNodeKeys<M, L> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, L, PK> : ScopeTranslatorMethods<M, L>;
 }
 
 /** Semantic tag attributes map. */
 type Attributes = Record<string, string>;
 
 /** Semantic node produced by the AST builder. */
-type ASTNode = TextNode | TagNode;
+type ASTNode = TextNode | TagNode | RawNode;
 /** Plain text node in the semantic AST. */
 interface TextNode {
     type: "text";
@@ -455,23 +471,27 @@ interface TagNode {
     attributes: Attributes;
     children: ASTNode[];
 }
+/** Raw node representing a non-tokenizable message value. */
+interface RawNode {
+    type: "raw";
+    value: Exclude<MessageValue, string>;
+}
 
 /**
- * Parse a rich-formatted message string into a semantic AST.
- *
- * This function is a high-level entry point for processing translated
- * messages that contain semantic tags (e.g. <b>, <a>, <i>).
+ * Parse a rich message value into a semantic AST.
  *
- * Internally, it performs the following steps:
+ * This is the main entry point for processing translated messages that may
+ * contain semantic markup (e.g. <b>, <a>, <i>) or non-string values.
  *
- * - message (string) ⬇
- *   - tokenize
- *   - build AST
+ * Behavior by message type:
+ * - string        → tokenized and parsed into semantic AST
+ * - number/boolean → stringified, then tokenized and parsed
+ * - array         → recursively flattened and parsed
+ * - object        → preserved as a raw AST node
  *
- * The returned AST represents the semantic structure of the message
- * and is intended to be consumed by renderers or further processing stages.
+ * The returned AST is renderer-agnostic and represents semantic structure only.
  */
-declare function parseRichMessage(message: string): ASTNode[];
+declare function parseRichMessage(message: MessageValue): ASTNode[];
 
 /**
  * Renderer interface for semantic message ASTs.
@@ -487,21 +507,23 @@ interface Renderer<Output> {
     text(value: string): Output;
     /** Render a semantic tag node with attributes and rendered children. */
     tag(name: string, attributes: Attributes, children: Output[]): Output;
+    /** Render a raw (non-tokenized) message value. */
+    raw(value: Exclude<MessageValue, string>): Output;
 }
 
 /**
- * Render a rich-formatted message into a concrete output using a renderer.
+ * Render a rich message value into a concrete output using the given renderer.
  *
- * This function orchestrates the full rich message pipeline:
+ * This function is the main entry point of the rich message pipeline.
+ * It orchestrates the full flow from message value to rendered output:
  *
- * - message (string) ⬇
- *   - tokenize
- *   - build AST
- *   - render via provided renderer
+ * - MessageValue ⬇
+ *   - parse into semantic AST
+ *   - render AST via the provided renderer
  *
- * All rendering behavior is defined by the given renderer, making this
- * function environment-agnostic (string, DOM, React, etc.).
+ * All rendering behavior is delegated to the renderer, making this function
+ * fully environment-agnostic (e.g. string, DOM, React).
  */
-declare function renderRichMessage<Output>(message: string, renderer: Renderer<Output>): 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 LoadingHandler, type Locale, type LocaleMessages, type LocalizedLeafKeys, type LocalizedMessagesUnion, type LocalizedNodeKeys, type MessageObject, type MessageValue, type MissingHandler, type NodeKeys, type Renderer, type Replacement, type ScopedLeafKeys, 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 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 };

package/dist/index.d.ts

@@ -1,19 +1,5 @@
 import { RuraHook } from 'rura';
 
-type MessagePrimitive$1 = string | number | boolean | null;
-type MessageArray$1 = readonly MessageValue$1[];
-/**
- * A recursive message tree object.
- *
- * Represents the root message structure for a single locale
- * (i.e. the value of `LocaleMessages[locale]`).
- */
-interface MessageObject$1 {
-    [key: string]: MessageValue$1;
-}
-/** A message value in the locale message tree. */
-type MessageValue$1 = MessagePrimitive$1 | MessageObject$1 | MessageArray$1;
-
 type MessagePrimitive = string | number | boolean | null;
 type MessageArray = readonly MessageValue[];
 /**
@@ -168,6 +154,16 @@ type NodeKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never
 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;
+/**
+ * Resolves the value type at a given dot-separated leaf key
+ * within a nested message object.
+ *
+ * @example
+ * ```ts
+ * LeafValue<{ 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;
 
 /**
  * Extracts all **node keys** from the messages
@@ -215,6 +211,13 @@ type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D ext
  * ```
  */
 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;
+/**
+ * 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;
 
 /**
  * Resolves the type at a dot-separated key in a nested object.
@@ -250,6 +253,21 @@ type MessagesAtPreKey<T, PK extends string> = PK extends `${infer Head}.${infer
  * ```
  */
 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;
+/**
+ * Resolves the value type of a scoped leaf key (`K`)
+ * under a prefix path (`PK`) from localized messages.
+ *
+ * @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 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;
 
 /**
  * Configuration options for translation behavior.
@@ -276,13 +294,13 @@ type TranslateHandlers = {
     formatHandler?: FormatHandler;
 };
 /** Function called when translation is still loading. */
-type LoadingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
+type LoadingHandler = (ctx: HandlerContext) => MessageValue;
 /** Function called when no message is found for the given key. */
-type MissingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
+type MissingHandler = (ctx: HandlerContext) => MessageValue;
 /** Function to format a resolved message. */
-type FormatHandler<Result = unknown> = (ctx: HandlerContext & {
+type FormatHandler = (ctx: HandlerContext & {
     rawString: string;
-}) => Result;
+}) => MessageValue;
 /**
  * Snapshot of the translate pipeline context exposed to handlers.
  *
@@ -295,10 +313,8 @@ type HandlerContext = Readonly<Omit<TranslateContext, "finalMessage">>;
 
 /**
  * Context object shared across the translate pipeline.
- *
- * @template Result - Final translated value type.
  */
-interface TranslateContext<Result = unknown> {
+interface TranslateContext {
     /** Configuration for the translate pipeline. */
     config: TranslateConfig;
     /** Current messages for translation */
@@ -318,16 +334,16 @@ interface TranslateContext<Result = unknown> {
     /** Raw string message before formatting. */
     rawString?: string;
     /** Message after formatting (e.g. ICU, custom formatters) */
-    formattedMessage?: unknown;
+    formattedMessage?: MessageValue;
     /** Final value produced by the pipeline */
-    finalMessage?: Result;
+    finalMessage?: MessageValue;
     /** Free-form metadata shared between hooks. */
     meta: Record<string, unknown>;
 }
 /**
  * A single step in the translate pipeline.
  */
-type TranslateHook = RuraHook<TranslateContext>;
+type TranslateHook = RuraHook<TranslateContext, MessageValue>;
 
 /**
  * Options for initializing a translator
@@ -420,29 +436,29 @@ declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, L ext
     /** Check if a key exists in the specified locale or current locale. */
     hasKey: <K extends LocalizedLeafKeys<M, L>>(key: K, targetLocale?: Locale<M>) => boolean;
     /** Get the translated message for a key, with optional replacements. */
-    t: <Result = string, K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => Result;
+    t: <K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => LocalizedLeafValue<M, K, L>;
     /** Get the raw message value for a key without formatting or interpolation. */
-    tRaw: <K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => MessageValue | undefined;
+    tRaw: <K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => LocalizedLeafValue<M, K, L>;
 }
 
 type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
-type ScopeTranslatorMethods<M extends LocaleMessages | unknown = unknown, L extends keyof M | "union" = "union", K = LocalizedLeafKeys<M, L>> = {
+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>> = {
     hasKey: (key?: K, targetLocale?: Locale<M>) => boolean;
-    t: <Result = string>(key?: K, replacements?: Replacement) => Result;
-    tRaw: (key?: K, replacements?: Replacement) => MessageValue$1 | undefined;
+    t: <Key extends K>(key?: Key, replacements?: Replacement) => PK extends string ? ScopedLeafValue<M, PK, Key, L> : LocalizedLeafValue<M, Key, L>;
+    tRaw: <Key extends K>(key?: Key, replacements?: Replacement) => PK extends string ? ScopedLeafValue<M, PK, Key, L> : LocalizedLeafValue<M, Key, L>;
 };
 
 declare class ScopeTranslator<M extends LocaleMessages | unknown = unknown, L extends keyof M | "union" = "union"> extends CoreTranslator<M> {
     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, ScopedLeafKeys<M, PK, L>> : ScopeTranslatorMethods<M, L>;
+    scoped<PK extends LocalizedNodeKeys<M, L> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, L, PK> : ScopeTranslatorMethods<M, L>;
 }
 
 /** Semantic tag attributes map. */
 type Attributes = Record<string, string>;
 
 /** Semantic node produced by the AST builder. */
-type ASTNode = TextNode | TagNode;
+type ASTNode = TextNode | TagNode | RawNode;
 /** Plain text node in the semantic AST. */
 interface TextNode {
     type: "text";
@@ -455,23 +471,27 @@ interface TagNode {
     attributes: Attributes;
     children: ASTNode[];
 }
+/** Raw node representing a non-tokenizable message value. */
+interface RawNode {
+    type: "raw";
+    value: Exclude<MessageValue, string>;
+}
 
 /**
- * Parse a rich-formatted message string into a semantic AST.
- *
- * This function is a high-level entry point for processing translated
- * messages that contain semantic tags (e.g. <b>, <a>, <i>).
+ * Parse a rich message value into a semantic AST.
  *
- * Internally, it performs the following steps:
+ * This is the main entry point for processing translated messages that may
+ * contain semantic markup (e.g. <b>, <a>, <i>) or non-string values.
  *
- * - message (string) ⬇
- *   - tokenize
- *   - build AST
+ * Behavior by message type:
+ * - string        → tokenized and parsed into semantic AST
+ * - number/boolean → stringified, then tokenized and parsed
+ * - array         → recursively flattened and parsed
+ * - object        → preserved as a raw AST node
  *
- * The returned AST represents the semantic structure of the message
- * and is intended to be consumed by renderers or further processing stages.
+ * The returned AST is renderer-agnostic and represents semantic structure only.
  */
-declare function parseRichMessage(message: string): ASTNode[];
+declare function parseRichMessage(message: MessageValue): ASTNode[];
 
 /**
  * Renderer interface for semantic message ASTs.
@@ -487,21 +507,23 @@ interface Renderer<Output> {
     text(value: string): Output;
     /** Render a semantic tag node with attributes and rendered children. */
     tag(name: string, attributes: Attributes, children: Output[]): Output;
+    /** Render a raw (non-tokenized) message value. */
+    raw(value: Exclude<MessageValue, string>): Output;
 }
 
 /**
- * Render a rich-formatted message into a concrete output using a renderer.
+ * Render a rich message value into a concrete output using the given renderer.
  *
- * This function orchestrates the full rich message pipeline:
+ * This function is the main entry point of the rich message pipeline.
+ * It orchestrates the full flow from message value to rendered output:
  *
- * - message (string) ⬇
- *   - tokenize
- *   - build AST
- *   - render via provided renderer
+ * - MessageValue ⬇
+ *   - parse into semantic AST
+ *   - render AST via the provided renderer
  *
- * All rendering behavior is defined by the given renderer, making this
- * function environment-agnostic (string, DOM, React, etc.).
+ * All rendering behavior is delegated to the renderer, making this function
+ * fully environment-agnostic (e.g. string, DOM, React).
  */
-declare function renderRichMessage<Output>(message: string, renderer: Renderer<Output>): 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 LoadingHandler, type Locale, type LocaleMessages, type LocalizedLeafKeys, type LocalizedMessagesUnion, type LocalizedNodeKeys, type MessageObject, type MessageValue, type MissingHandler, type NodeKeys, type Renderer, type Replacement, type ScopedLeafKeys, 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 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 };

package/dist/index.js

@@ -119,7 +119,7 @@ var loading = rura.createHook(
       };
     }
     const { loadingMessage } = config;
-    if ("loadingMessage" in config) {
+    if (loadingMessage !== void 0) {
       return { early: true, output: loadingMessage };
     }
   },
@@ -138,7 +138,7 @@ var missing = rura.createHook(
       };
     }
     const { missingMessage } = config;
-    if ("missingMessage" in config) {
+    if (missingMessage !== void 0) {
       return { early: true, output: missingMessage };
     }
     return { early: true, output: key };
@@ -174,6 +174,7 @@ var DEFAULT_HOOKS = [
   format,
   interpolate
 ];
+rura.createPipeline(DEFAULT_HOOKS).debugHooks();
 
 // src/translators/base-translator/base-translator.ts
 var BaseTranslator = class {
@@ -248,12 +249,18 @@ function runTranslate(options) {
 function translate(options) {
   const { early, ctx, output } = runTranslate(options);
   if (early === true) return output;
+  if (ctx.finalMessage === void 0) {
+    throw new Error("Invariant violated: missing hook did not produce output");
+  }
   return ctx.finalMessage;
 }
 
 // src/translators/methods/translate-raw.ts
 function translateRaw(options) {
   const { ctx } = runTranslate(options);
+  if (ctx.rawValue === void 0) {
+    throw new Error("Invariant violated: missing hook did not produce output");
+  }
   return ctx.rawValue;
 }
 
@@ -500,18 +507,44 @@ function buildAST(tokens) {
 
 // src/message/parse-rich-message.ts
 function parseRichMessage(message) {
-  const tokens = tokenize(message);
-  return buildAST(tokens);
+  if (message == null) return [];
+  if (typeof message === "string") {
+    const tokens = tokenize(message);
+    return buildAST(tokens);
+  }
+  if (typeof message === "number" || typeof message === "boolean") {
+    const tokens = tokenize(String(message));
+    return buildAST(tokens);
+  }
+  if (Array.isArray(message)) {
+    return message.flatMap((m) => parseRichMessage(m));
+  }
+  return [
+    {
+      type: "raw",
+      value: message
+    }
+  ];
 }
 
 // src/message/render/render.ts
 function render(nodes, renderer) {
   return nodes.map((node) => {
-    if (node.type === "text") {
-      return renderer.text(node.value);
+    switch (node.type) {
+      // Plain text node
+      case "text": {
+        return renderer.text(node.value);
+      }
+      // Semantic tag node
+      case "tag": {
+        const children = render(node.children, renderer);
+        return renderer.tag(node.name, node.attributes, children);
+      }
+      // Raw message value
+      case "raw": {
+        return renderer.raw(node.value);
+      }
     }
-    const children = render(node.children, renderer);
-    return renderer.tag(node.name, node.attributes, children);
   });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intor-translator",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "description": "🤖 A modern, type-safe i18n engine.",
   "author": {
     "name": "Yiming Liao",
@@ -62,7 +62,7 @@
     "examples:html:rich-message": "vite --config examples/html/rich-message/vite.config.ts"
   },
   "dependencies": {
-    "rura": "1.0.7"
+    "rura": "^1.0.8"
   },
   "devDependencies": {
     "@types/node": "24.10.1",