intor-translator 1.3.1 → 1.4.0

package/dist/index.cjs

@@ -11,19 +11,19 @@ var findMessageInLocales = ({
   key
 }) => {
   for (const locale of candidateLocales) {
-    const localeMessages = messages[locale];
-    if (!localeMessages) continue;
-    let candidate = localeMessages;
+    const messagesForLocale = messages[locale];
+    if (!messagesForLocale) continue;
+    let candidate = messagesForLocale;
     const keys = key.split(".");
-    for (const k of keys) {
-      if (candidate && typeof candidate === "object" && k in candidate) {
-        candidate = candidate[k];
+    for (const key2 of keys) {
+      if (candidate !== null && typeof candidate === "object" && key2 in candidate) {
+        candidate = candidate[key2];
       } else {
         candidate = void 0;
         break;
       }
     }
-    if (typeof candidate === "string") return candidate;
+    if (candidate !== void 0) return candidate;
   }
 };
 
@@ -31,11 +31,15 @@ var findMessageInLocales = ({
 var findMessage = rura.rura.createHook(
   "findMessage",
   (ctx) => {
-    ctx.rawMessage = findMessageInLocales({
+    ctx.rawValue = void 0;
+    ctx.rawString = void 0;
+    const message = findMessageInLocales({
       messages: ctx.messages,
       candidateLocales: ctx.candidateLocales,
       key: ctx.key
     });
+    ctx.rawValue = message;
+    if (typeof message === "string") ctx.rawString = message;
   },
   200
 );
@@ -50,7 +54,8 @@ function makeHandlerContext(ctx) {
     key: ctx.key,
     replacements: ctx.replacements,
     candidateLocales: ctx.candidateLocales,
-    rawMessage: ctx.rawMessage,
+    rawValue: ctx.rawValue,
+    rawString: ctx.rawString,
     formattedMessage: ctx.formattedMessage,
     meta: ctx.meta
   });
@@ -60,9 +65,9 @@ function makeHandlerContext(ctx) {
 var format = rura.rura.createHook(
   "format",
   (ctx) => {
-    const { config, rawMessage } = ctx;
+    const { config, rawString } = ctx;
     const { formatHandler } = config.handlers || {};
-    if (!formatHandler || rawMessage === void 0) return;
+    if (!formatHandler || rawString === void 0) return;
     ctx.formattedMessage = formatHandler(
       makeHandlerContext(ctx)
     );
@@ -93,8 +98,8 @@ var replaceValues = (message, params) => {
 var interpolate = rura.rura.createHook(
   "interpolate",
   (ctx) => {
-    const { rawMessage, formattedMessage, replacements } = ctx;
-    const message = formattedMessage ?? rawMessage;
+    const { rawString, formattedMessage, replacements } = ctx;
+    const message = formattedMessage ?? rawString;
     if (typeof message !== "string" || !replacements) {
       ctx.finalMessage = message;
       return;
@@ -116,7 +121,7 @@ var loading = rura.rura.createHook(
       };
     }
     const { loadingMessage } = config;
-    if (loadingMessage) {
+    if ("loadingMessage" in config) {
       return { early: true, output: loadingMessage };
     }
   },
@@ -125,8 +130,8 @@ var loading = rura.rura.createHook(
 var missing = rura.rura.createHook(
   "missing",
   (ctx) => {
-    const { config, key, rawMessage } = ctx;
-    if (rawMessage !== void 0) return;
+    const { config, key, rawString } = ctx;
+    if (rawString !== void 0) return;
     const { missingHandler } = config.handlers || {};
     if (missingHandler) {
       return {
@@ -134,9 +139,9 @@ var missing = rura.rura.createHook(
         output: missingHandler(makeHandlerContext(ctx))
       };
     }
-    const { placeholder } = config;
-    if (placeholder) {
-      return { early: true, output: placeholder };
+    const { missingMessage } = config;
+    if ("missingMessage" in config) {
+      return { early: true, output: missingMessage };
     }
     return { early: true, output: key };
   },
@@ -229,20 +234,31 @@ var hasKey = ({
 }) => {
   const candidateLocales = resolveCandidateLocales(targetLocale || locale);
   const message = findMessageInLocales({ messages, candidateLocales, key });
-  return !!message;
+  return message !== void 0;
 };
-function translate(options) {
+function runTranslate(options) {
   const context = {
     ...options,
     config: options.translateConfig,
     candidateLocales: [],
     meta: {}
   };
-  const { early, ctx, output } = rura.rura.run(context, options.hooks);
+  return rura.rura.run(context, options.hooks);
+}
+
+// src/translators/methods/translate.ts
+function translate(options) {
+  const { early, ctx, output } = runTranslate(options);
   if (early === true) return output;
   return ctx.finalMessage;
 }
 
+// src/translators/methods/translate-raw.ts
+function translateRaw(options) {
+  const { ctx } = runTranslate(options);
+  return ctx.rawValue;
+}
+
 // src/translators/core-translator/core-translator.ts
 var CoreTranslator = class extends BaseTranslator {
   /** User-provided options including messages, locale, and config. */
@@ -298,6 +314,18 @@ var CoreTranslator = class extends BaseTranslator {
       replacements
     });
   };
+  /** Get the raw message value for a key without formatting or interpolation. */
+  tRaw = (key, replacements) => {
+    return translateRaw({
+      hooks: this.hooks,
+      messages: this._messages,
+      locale: this._locale,
+      isLoading: this._isLoading,
+      translateConfig: this.translateConfig,
+      key,
+      replacements
+    });
+  };
 };
 
 // src/translators/scope-translator/utils/get-full-key.ts

package/dist/index.d.cts

@@ -1,30 +1,24 @@
 import { RuraHook } from 'rura';
 
+type MessagePrimitive = string | number | boolean | null;
+type MessageArray = readonly MessageValue[];
+interface MessageObject {
+    [key: string]: MessageValue;
+}
+/** A message value in the locale message tree. */
+type MessageValue = MessagePrimitive | MessageObject | MessageArray;
 /**
- * A nested message structure or a simple string message.
- *
- * - Used to represent either a plain message or an object containing more nested messages.
+ * A non-traversable message value.
  *
- * @example
- * ```ts
- * const greeting: NestedMessage = "Hello";
- * const userMessages: NestedMessage = {
- *   profile: {
- *     greeting: "Hello, user!",
- *     farewell: "Goodbye!"
- *   }
- * };
- * ```
+ * Leaf values represent the end of a message path.
  */
-type NestedMessage = string | {
-    [key: string]: NestedMessage;
-};
+type MessageLeaf = MessagePrimitive | MessageArray;
 /**
  * Messages grouped by locale.
  * Used to structure all available messages for multiple locales.
  *
  * - The root-level keys are locale identifiers, e.g., "en" or "zh-TW".
- * - Each value is a `NestedMessage`, allowing for deeply nested message objects.
+ * - Each value is a `MessageObject`, allowing for deeply nested message objects.
  *
  * @example
  * ```ts
@@ -37,22 +31,11 @@ type NestedMessage = string | {
  *         failure: "Login failed"
  *       }
  *     }
- *   },
- *   "zh-TW": {
- *     welcome: "歡迎",
- *     auth: {
- *       login: {
- *         success: "登入成功",
- *         failure: "登入失敗"
- *       }
- *     }
  *   }
  * };
  * ```
  */
-type LocaleMessages = Record<string, {
-    [x: string]: NestedMessage;
-}>;
+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.
@@ -144,7 +127,7 @@ 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];
 /**
- * Gets all dot-separated keys (including non-leaf nodes) from a nested object.
+ * Gets all dot-separated keys of a nested object, stopping at message leaf values.
  *
  * @example
  * ```ts
@@ -152,10 +135,10 @@ type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
  * ```
  */
 type NodeKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never : M extends object ? {
-    [K in keyof M]: K extends string ? `${K}` | `${K}.${NodeKeys<M[K], Prev[D]>}` : never;
+    [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;
 /**
- * Gets dot-separated keys to string leaf nodes in a nested object.
+ * Gets dot-separated keys that resolve to message leaf values in a nested object.
  *
  * @example
  * ```ts
@@ -163,7 +146,7 @@ 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 string ? `${K & string}` : M[K] extends object ? `${K & string}.${LeafKeys<M[K], Prev[D]>}` : never;
+    [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;
 
 /**
@@ -246,7 +229,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 NestedMessage ? LeafKeys<MessagesAtPreKey<messages, PK>, D> : never : never : string;
+type ScopedLeafKeys<M, PK extends string, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends infer Messages ? Messages extends MessageValue ? MessagesAtPreKey<Messages, PK> extends infer Scoped ? Scoped extends MessageObject ? LeafKeys<Scoped, D> : never : never : never : never : string;
 
 /**
  * Configuration options for translation behavior.
@@ -258,8 +241,8 @@ type TranslateConfig<M = unknown> = {
     fallbackLocales?: FallbackLocalesMap<Locale<M>>;
     /** Optional message to display while translations are still loading. */
     loadingMessage?: string;
-    /** Optional placeholder to use when a message cannot be found. */
-    placeholder?: string;
+    /** Optional message used when a translation is missing. */
+    missingMessage?: string;
     /** Optional set of handler functions for customizing translation behavior. */
     handlers?: TranslateHandlers;
 };
@@ -278,7 +261,7 @@ type LoadingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
 type MissingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
 /** Function to format a resolved message. */
 type FormatHandler<Result = unknown> = (ctx: HandlerContext & {
-    rawMessage: string;
+    rawString: string;
 }) => Result;
 /**
  * Snapshot of the translate pipeline context exposed to handlers.
@@ -310,8 +293,10 @@ interface TranslateContext<Result = unknown> {
     replacements?: Replacement;
     /** Ordered list of locales to try, including fallbacks */
     candidateLocales: string[];
-    /** Raw message string found in the messages map, before formatting */
-    rawMessage?: string;
+    /** Raw message value resolved from the message tree. */
+    rawValue?: MessageValue;
+    /** Raw string message before formatting. */
+    rawString?: string;
     /** Message after formatting (e.g. ICU, custom formatters) */
     formattedMessage?: unknown;
     /** Final value produced by the pipeline */
@@ -416,6 +401,8 @@ declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, L ext
     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;
+    /** 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;
 }
 
 type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
@@ -496,4 +483,4 @@ interface Renderer<Output> {
  */
 declare function renderRichMessage<Output>(message: string, 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 MissingHandler, type NestedMessage, 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 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 };

package/dist/index.d.ts

@@ -1,30 +1,24 @@
 import { RuraHook } from 'rura';
 
+type MessagePrimitive = string | number | boolean | null;
+type MessageArray = readonly MessageValue[];
+interface MessageObject {
+    [key: string]: MessageValue;
+}
+/** A message value in the locale message tree. */
+type MessageValue = MessagePrimitive | MessageObject | MessageArray;
 /**
- * A nested message structure or a simple string message.
- *
- * - Used to represent either a plain message or an object containing more nested messages.
+ * A non-traversable message value.
  *
- * @example
- * ```ts
- * const greeting: NestedMessage = "Hello";
- * const userMessages: NestedMessage = {
- *   profile: {
- *     greeting: "Hello, user!",
- *     farewell: "Goodbye!"
- *   }
- * };
- * ```
+ * Leaf values represent the end of a message path.
  */
-type NestedMessage = string | {
-    [key: string]: NestedMessage;
-};
+type MessageLeaf = MessagePrimitive | MessageArray;
 /**
  * Messages grouped by locale.
  * Used to structure all available messages for multiple locales.
  *
  * - The root-level keys are locale identifiers, e.g., "en" or "zh-TW".
- * - Each value is a `NestedMessage`, allowing for deeply nested message objects.
+ * - Each value is a `MessageObject`, allowing for deeply nested message objects.
  *
  * @example
  * ```ts
@@ -37,22 +31,11 @@ type NestedMessage = string | {
  *         failure: "Login failed"
  *       }
  *     }
- *   },
- *   "zh-TW": {
- *     welcome: "歡迎",
- *     auth: {
- *       login: {
- *         success: "登入成功",
- *         failure: "登入失敗"
- *       }
- *     }
  *   }
  * };
  * ```
  */
-type LocaleMessages = Record<string, {
-    [x: string]: NestedMessage;
-}>;
+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.
@@ -144,7 +127,7 @@ 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];
 /**
- * Gets all dot-separated keys (including non-leaf nodes) from a nested object.
+ * Gets all dot-separated keys of a nested object, stopping at message leaf values.
  *
  * @example
  * ```ts
@@ -152,10 +135,10 @@ type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
  * ```
  */
 type NodeKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never : M extends object ? {
-    [K in keyof M]: K extends string ? `${K}` | `${K}.${NodeKeys<M[K], Prev[D]>}` : never;
+    [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;
 /**
- * Gets dot-separated keys to string leaf nodes in a nested object.
+ * Gets dot-separated keys that resolve to message leaf values in a nested object.
  *
  * @example
  * ```ts
@@ -163,7 +146,7 @@ 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 string ? `${K & string}` : M[K] extends object ? `${K & string}.${LeafKeys<M[K], Prev[D]>}` : never;
+    [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;
 
 /**
@@ -246,7 +229,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 NestedMessage ? LeafKeys<MessagesAtPreKey<messages, PK>, D> : never : never : string;
+type ScopedLeafKeys<M, PK extends string, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends infer Messages ? Messages extends MessageValue ? MessagesAtPreKey<Messages, PK> extends infer Scoped ? Scoped extends MessageObject ? LeafKeys<Scoped, D> : never : never : never : never : string;
 
 /**
  * Configuration options for translation behavior.
@@ -258,8 +241,8 @@ type TranslateConfig<M = unknown> = {
     fallbackLocales?: FallbackLocalesMap<Locale<M>>;
     /** Optional message to display while translations are still loading. */
     loadingMessage?: string;
-    /** Optional placeholder to use when a message cannot be found. */
-    placeholder?: string;
+    /** Optional message used when a translation is missing. */
+    missingMessage?: string;
     /** Optional set of handler functions for customizing translation behavior. */
     handlers?: TranslateHandlers;
 };
@@ -278,7 +261,7 @@ type LoadingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
 type MissingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
 /** Function to format a resolved message. */
 type FormatHandler<Result = unknown> = (ctx: HandlerContext & {
-    rawMessage: string;
+    rawString: string;
 }) => Result;
 /**
  * Snapshot of the translate pipeline context exposed to handlers.
@@ -310,8 +293,10 @@ interface TranslateContext<Result = unknown> {
     replacements?: Replacement;
     /** Ordered list of locales to try, including fallbacks */
     candidateLocales: string[];
-    /** Raw message string found in the messages map, before formatting */
-    rawMessage?: string;
+    /** Raw message value resolved from the message tree. */
+    rawValue?: MessageValue;
+    /** Raw string message before formatting. */
+    rawString?: string;
     /** Message after formatting (e.g. ICU, custom formatters) */
     formattedMessage?: unknown;
     /** Final value produced by the pipeline */
@@ -416,6 +401,8 @@ declare class CoreTranslator<M extends LocaleMessages | unknown = unknown, L ext
     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;
+    /** 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;
 }
 
 type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
@@ -496,4 +483,4 @@ interface Renderer<Output> {
  */
 declare function renderRichMessage<Output>(message: string, 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 MissingHandler, type NestedMessage, 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 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 };

package/dist/index.js

@@ -9,19 +9,19 @@ var findMessageInLocales = ({
   key
 }) => {
   for (const locale of candidateLocales) {
-    const localeMessages = messages[locale];
-    if (!localeMessages) continue;
-    let candidate = localeMessages;
+    const messagesForLocale = messages[locale];
+    if (!messagesForLocale) continue;
+    let candidate = messagesForLocale;
     const keys = key.split(".");
-    for (const k of keys) {
-      if (candidate && typeof candidate === "object" && k in candidate) {
-        candidate = candidate[k];
+    for (const key2 of keys) {
+      if (candidate !== null && typeof candidate === "object" && key2 in candidate) {
+        candidate = candidate[key2];
       } else {
         candidate = void 0;
         break;
       }
     }
-    if (typeof candidate === "string") return candidate;
+    if (candidate !== void 0) return candidate;
   }
 };
 
@@ -29,11 +29,15 @@ var findMessageInLocales = ({
 var findMessage = rura.createHook(
   "findMessage",
   (ctx) => {
-    ctx.rawMessage = findMessageInLocales({
+    ctx.rawValue = void 0;
+    ctx.rawString = void 0;
+    const message = findMessageInLocales({
       messages: ctx.messages,
       candidateLocales: ctx.candidateLocales,
       key: ctx.key
     });
+    ctx.rawValue = message;
+    if (typeof message === "string") ctx.rawString = message;
   },
   200
 );
@@ -48,7 +52,8 @@ function makeHandlerContext(ctx) {
     key: ctx.key,
     replacements: ctx.replacements,
     candidateLocales: ctx.candidateLocales,
-    rawMessage: ctx.rawMessage,
+    rawValue: ctx.rawValue,
+    rawString: ctx.rawString,
     formattedMessage: ctx.formattedMessage,
     meta: ctx.meta
   });
@@ -58,9 +63,9 @@ function makeHandlerContext(ctx) {
 var format = rura.createHook(
   "format",
   (ctx) => {
-    const { config, rawMessage } = ctx;
+    const { config, rawString } = ctx;
     const { formatHandler } = config.handlers || {};
-    if (!formatHandler || rawMessage === void 0) return;
+    if (!formatHandler || rawString === void 0) return;
     ctx.formattedMessage = formatHandler(
       makeHandlerContext(ctx)
     );
@@ -91,8 +96,8 @@ var replaceValues = (message, params) => {
 var interpolate = rura.createHook(
   "interpolate",
   (ctx) => {
-    const { rawMessage, formattedMessage, replacements } = ctx;
-    const message = formattedMessage ?? rawMessage;
+    const { rawString, formattedMessage, replacements } = ctx;
+    const message = formattedMessage ?? rawString;
     if (typeof message !== "string" || !replacements) {
       ctx.finalMessage = message;
       return;
@@ -114,7 +119,7 @@ var loading = rura.createHook(
       };
     }
     const { loadingMessage } = config;
-    if (loadingMessage) {
+    if ("loadingMessage" in config) {
       return { early: true, output: loadingMessage };
     }
   },
@@ -123,8 +128,8 @@ var loading = rura.createHook(
 var missing = rura.createHook(
   "missing",
   (ctx) => {
-    const { config, key, rawMessage } = ctx;
-    if (rawMessage !== void 0) return;
+    const { config, key, rawString } = ctx;
+    if (rawString !== void 0) return;
     const { missingHandler } = config.handlers || {};
     if (missingHandler) {
       return {
@@ -132,9 +137,9 @@ var missing = rura.createHook(
         output: missingHandler(makeHandlerContext(ctx))
       };
     }
-    const { placeholder } = config;
-    if (placeholder) {
-      return { early: true, output: placeholder };
+    const { missingMessage } = config;
+    if ("missingMessage" in config) {
+      return { early: true, output: missingMessage };
     }
     return { early: true, output: key };
   },
@@ -227,20 +232,31 @@ var hasKey = ({
 }) => {
   const candidateLocales = resolveCandidateLocales(targetLocale || locale);
   const message = findMessageInLocales({ messages, candidateLocales, key });
-  return !!message;
+  return message !== void 0;
 };
-function translate(options) {
+function runTranslate(options) {
   const context = {
     ...options,
     config: options.translateConfig,
     candidateLocales: [],
     meta: {}
   };
-  const { early, ctx, output } = rura.run(context, options.hooks);
+  return rura.run(context, options.hooks);
+}
+
+// src/translators/methods/translate.ts
+function translate(options) {
+  const { early, ctx, output } = runTranslate(options);
   if (early === true) return output;
   return ctx.finalMessage;
 }
 
+// src/translators/methods/translate-raw.ts
+function translateRaw(options) {
+  const { ctx } = runTranslate(options);
+  return ctx.rawValue;
+}
+
 // src/translators/core-translator/core-translator.ts
 var CoreTranslator = class extends BaseTranslator {
   /** User-provided options including messages, locale, and config. */
@@ -296,6 +312,18 @@ var CoreTranslator = class extends BaseTranslator {
       replacements
     });
   };
+  /** Get the raw message value for a key without formatting or interpolation. */
+  tRaw = (key, replacements) => {
+    return translateRaw({
+      hooks: this.hooks,
+      messages: this._messages,
+      locale: this._locale,
+      isLoading: this._isLoading,
+      translateConfig: this.translateConfig,
+      key,
+      replacements
+    });
+  };
 };
 
 // src/translators/scope-translator/utils/get-full-key.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intor-translator",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "🤖 A modern, type-safe i18n engine.",
   "author": {
     "name": "Yiming Liao",
@@ -50,13 +50,14 @@
     "node": ">=16.0.0"
   },
   "scripts": {
-    "build": "tsup",
-    "prepublishOnly": "yarn build",
-    "test": "vitest",
     "type": "tsc --noEmit",
     "lint": "eslint",
     "lint:debug": "eslint --debug",
+    "test": "vitest",
+    "test:types": "tsx scripts/test-types.ts",
     "knip": "knip --config .config/knip.config.ts",
+    "build": "tsup",
+    "prepublishOnly": "yarn build",
     "examples:html": "vite --config examples/html/basic/vite.config.ts",
     "examples:html:rich-message": "vite --config examples/html/rich-message/vite.config.ts"
   },