intor-translator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yiming Liao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# IntorTranslator
+
+A highly flexible and type-safe i18n translation engine for modern applications — supporting fallback locales, async loading states, scoped namespaces, and both simple and rich formatting.
+
+[![NPM version](https://img.shields.io/npm/v/intor-translator)](https://www.npmjs.com/package/intor-translator)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/intor-translator)](https://bundlephobia.com/package/intor-translator)
+[![License](https://img.shields.io/npm/l/intor-translator)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-%E2%9C%94-blue)](https://www.typescriptlang.org/)
+
+---
+
+## Features
+
+- 🌍 Fallback locale support
+- ⚡ Reactive translation logic
+- 🧠 Type-safe nested key paths
+- 🔁 Replacement support
+- 🎨 Rich replacement formatting
+- 🌀 Graceful loading state handling
+- 🔧 Configurable handlers for fallback, loading, and placeholder cases
+- 🧩 Scoped translator for modules or namespaces
+
+---
+
+## Installation
+
+```bash
+npm install intor-translator
+```
+
+or use **yarn**
+
+```bash
+yarn add intor-translator
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { createTranslator } from "intor-translator";
+
+// Create a translator instance
+const translator = createTranslator({
+  locale: "en",
+  messages: {
+    en: {
+      hello: "Hello World",
+      greeting: "Hello, {name}!", // Use curly braces for replacements
+    },
+  },
+});
+
+// Use the translator
+translator.t("hello"); // > Hello World
+translator.t("greeting", { name: "John doe" }); // > Hello, John doe!
+```
+
+---
+
+## Advanced Features
+
+- Fallback Locales, Placeholder & Custom Handlers
+
+```typescript
+const translator = createTranslator({
+  locale: "en",
+  messages: {
+    en: {
+      greeting: "Hello, {name}!",
+    },
+    zh: {
+      greeting: "哈囉, {name}!",
+      "only-in-zh": "This message is not exist in en",
+    },
+  },
+  fallbackLocales: { en: ["zh"] }, // Falls back to zh if message is missing in en
+  placeholder: "MESSAGE NOT FOUND", // Default text shown when a key is not found in any locale
+  handlers: {
+    messageFormatter: ({ locale, message }) =>
+      `${message}${locale === "en" ? "." : "。"}`, // Custom message formatter
+  },
+});
+
+translator.t("only-in-zh"); // > This message is not exist in en.
+```
+
+- With Custom ICU Formatter
+
+```typescript
+import IntlMessageFormat from "intl-messageformat";
+import { MessageFormatter } from "intor-translator";
+
+const formatter: MessageFormatter = ({ message, locale, replacements }) => {
+  const formatter = new IntlMessageFormat(message, locale);
+  return formatter.format(replacements);
+};
+
+const translator = createTranslator({
+  locale: "en",
+  messages: {
+    en: {
+      notification:
+        "{name} has {count, plural, =0 {no messages} one {1 message} other {# messages}}.",
+    },
+  },
+  handlers: {
+    messageFormatter: formatter,
+  },
+});
+
+translator.t("notification", { name: "John", count: 0 }); // > John has no messages.
+translator.t("notification", { name: "John", count: 5 }); // > John has 5 messages.
+```
+
+---
+
+## API Reference
+
+| Option            | Type                             | Description                                                               |
+| ----------------- | -------------------------------- | ------------------------------------------------------------------------- |
+| `messages`        | `Record<Locale, Messages>`       | Translation messages, structured by locale                                |
+| `locale`          | `string`                         | The active locale                                                         |
+| `fallbackLocales` | `Record<Locale, Locale[]>` (opt) | Fallback locales used when a message is missing in the active locale      |
+| `placeholder`     | `string`（opt）                  | Default message to display when a key is missing                          |
+| `isLoading`       | `boolean`（opt）                 | Indicates if the translator is in a loading state                         |
+| `loadingMessage`  | `string`（opt）                  | Message to show when inLoading is true.                                   |
+| `handlers`        | `TranslatorHandlers`（opt）      | Custom handler functions for formatting, loading, or placeholder messages |
+|                   |
+
+**translator.t(key, replacements?)**
+
+- Fully type-safe key access
+- Supports nested keys
+- Supports both string and rich replacements
+
+**translator.scope(preKey)**
+
+- Returns a scoped translator instance based on a message subtree
+- Useful for organizing large sets of translations with shared prefixes
+
+---
+
+## Project Structure
+
+```bash
+src/
+├── index.ts                  # Main entry point and API
+├── create-translator.ts      # Translator factory function
+├── methods/                  # Helper methods for locale, messages, keys, etc.
+│   ├── get-locale/
+│   ├── set-locale/
+│   ├── get-messages/
+│   └── translate/
+│   ├── has-key/
+│   ├── scoped/
+├── types/                    # Type definitions
+└── utils/                    # Utility functions
+```

package/dist/index.cjs

@@ -0,0 +1,268 @@
+'use strict';
+
+var intorCache = require('intor-cache');
+
+// src/methods/get-locale/get-locale.ts
+var getLocale = (localeRef) => {
+  return localeRef.current;
+};
+
+// src/methods/get-locale/create-get-locale.ts
+var createGetLocale = (localeRef) => {
+  return () => getLocale(localeRef);
+};
+
+// src/methods/get-messages/get-messages.ts
+var getMessages = (messagesRef) => {
+  return messagesRef.current;
+};
+
+// src/methods/get-messages/create-get-messages.ts
+var createGetMessages = (messagesRef) => {
+  return () => getMessages(messagesRef);
+};
+var getValueByKey = (locale, messages, key, useCache = true) => {
+  const cache = intorCache.getMessageKeyCache();
+  useCache = Boolean(useCache && cache);
+  const cacheKey = `${key}`;
+  const currentLocale = cache == null ? void 0 : cache.get("locale");
+  if (currentLocale !== locale) {
+    cache == null ? void 0 : cache.clear();
+    cache == null ? void 0 : cache.set("locale", locale);
+  }
+  if (useCache && (cache == null ? void 0 : cache.has(cacheKey))) {
+    return cache == null ? void 0 : cache.get(cacheKey);
+  }
+  const value = key.split(".").reduce((acc, key2) => {
+    if (acc && typeof acc === "object" && key2 in acc) {
+      return acc[key2];
+    }
+    return void 0;
+  }, messages);
+  if (useCache && value !== void 0) {
+    cache == null ? void 0 : cache.set(cacheKey, value);
+  }
+  return value;
+};
+
+// src/utils/find-message-in-locales.ts
+var findMessageInLocales = ({
+  messages,
+  localesToTry,
+  key
+}) => {
+  for (const loc of localesToTry) {
+    const localeMessages = messages[loc];
+    if (!localeMessages) {
+      continue;
+    }
+    const candidate = getValueByKey(loc, localeMessages, key);
+    if (typeof candidate === "string") {
+      return candidate;
+    }
+  }
+  return void 0;
+};
+
+// src/utils/resolve-locales-to-try.ts
+var resolveLocalesToTry = (locale, fallbackLocales) => {
+  const fallbacks = (fallbackLocales == null ? void 0 : fallbackLocales[locale]) || [];
+  return [
+    locale,
+    ...fallbacks.filter((l) => l !== locale)
+  ];
+};
+
+// src/methods/has-key/has-key.ts
+var hasKey = ({
+  messagesRef,
+  localeRef,
+  translatorOptions,
+  key,
+  locale
+}) => {
+  const messages = messagesRef.current;
+  const { fallbackLocales } = translatorOptions;
+  const targetLocale = locale != null ? locale : localeRef.current;
+  const localesToTry = resolveLocalesToTry(targetLocale, fallbackLocales);
+  const message = findMessageInLocales({ messages, localesToTry, key });
+  return message ? true : false;
+};
+
+// src/methods/has-key/create-has-key.ts
+var createHasKey = (messagesRef, localeRef, translatorOptions) => {
+  return (key, locale) => hasKey({
+    messagesRef,
+    localeRef,
+    translatorOptions,
+    key,
+    locale
+  });
+};
+
+// src/utils/get-full-key.ts
+var getFullKey = (preKey, key) => {
+  if (!preKey) {
+    return key;
+  }
+  if (!key) {
+    return preKey;
+  }
+  return `${preKey}.${key}`;
+};
+
+// src/utils/replace-values.ts
+var replaceValues = (message, params) => {
+  if (!params || typeof params !== "object" || Object.keys(params).length === 0) {
+    return message;
+  }
+  const replaced = message.replace(/{([^}]+)}/g, (match, key) => {
+    const keys = key.split(".");
+    let value = params;
+    for (const k of keys) {
+      if (value == null || typeof value !== "object" || !(k in value)) {
+        return match;
+      }
+      value = value[k];
+    }
+    return typeof value === "string" || typeof value === "number" ? String(value) : match;
+  });
+  return replaced;
+};
+
+// src/methods/translate/translate.ts
+var translate = ({
+  messagesRef,
+  localeRef,
+  translatorOptions,
+  key,
+  replacements
+}) => {
+  const messages = messagesRef.current;
+  const { fallbackLocales, isLoading, loadingMessage, placeholder } = translatorOptions;
+  const { messageFormatter, loadingMessageHandler, placeholderHandler } = translatorOptions.handlers || {};
+  const localesToTry = resolveLocalesToTry(localeRef.current, fallbackLocales);
+  const message = findMessageInLocales({ messages, localesToTry, key });
+  if (isLoading) {
+    if (loadingMessageHandler) {
+      return loadingMessageHandler({
+        key,
+        locale: localeRef.current,
+        replacements
+      });
+    }
+    if (loadingMessage) {
+      return loadingMessage;
+    }
+  }
+  if (!message) {
+    if (placeholderHandler) {
+      return placeholderHandler({
+        key,
+        locale: localeRef.current,
+        replacements
+      });
+    }
+    if (placeholder) {
+      return placeholder;
+    }
+    return key;
+  }
+  if (messageFormatter) {
+    return messageFormatter({
+      message,
+      key,
+      locale: localeRef.current,
+      replacements
+    });
+  } else {
+    return replacements ? replaceValues(message, replacements) : message;
+  }
+};
+
+// src/methods/translate/create-translate.ts
+var createTranslate = (messagesRef, localeRef, translatorOptions) => {
+  return (key, replacements) => translate({
+    messagesRef,
+    localeRef,
+    translatorOptions,
+    key,
+    replacements
+  });
+};
+
+// src/methods/scoped/scoped.ts
+var scoped = ({
+  messagesRef,
+  localeRef,
+  translatorOptions,
+  preKey
+}) => {
+  const baseTranslate = createTranslate(
+    messagesRef,
+    localeRef,
+    translatorOptions
+  );
+  const baseHasKey = createHasKey(
+    messagesRef,
+    localeRef,
+    translatorOptions
+  );
+  return {
+    // t (Scoped)
+    t: (key, replacements) => {
+      const fullKey = getFullKey(preKey, key);
+      return baseTranslate(fullKey, replacements);
+    },
+    // hasKey (Scoped)
+    hasKey: (key, locale) => {
+      const fullKey = getFullKey(preKey, key);
+      return baseHasKey(fullKey, locale);
+    }
+  };
+};
+
+// src/methods/scoped/create-scoped.ts
+var createScoped = (messagesRef, localeRef, translatorOptions) => {
+  return (preKey) => scoped({ messagesRef, localeRef, translatorOptions, preKey });
+};
+
+// src/methods/set-locale/set-locale.ts
+var setLocale = ({
+  messagesRef,
+  localeRef,
+  newLocale
+}) => {
+  const messages = messagesRef.current;
+  if (newLocale in messages) {
+    localeRef.current = newLocale;
+  }
+};
+
+// src/methods/set-locale/create-set-locale.ts
+var createSetLocale = (messagesRef, localeRef) => {
+  return (newLocale) => setLocale({ messagesRef, localeRef, newLocale });
+};
+
+// src/create-translator.ts
+function createTranslator(translatorOptions) {
+  const { locale } = translatorOptions;
+  const messagesRef = { current: translatorOptions.messages };
+  const localeRef = { current: locale };
+  const getLocale2 = createGetLocale(localeRef);
+  const setLocale2 = createSetLocale(messagesRef, localeRef);
+  const getMessages2 = createGetMessages(messagesRef);
+  const hasKey2 = createHasKey(messagesRef, localeRef, translatorOptions);
+  const t = createTranslate(messagesRef, localeRef, translatorOptions);
+  const scoped2 = createScoped(messagesRef, localeRef, translatorOptions);
+  return {
+    getLocale: getLocale2,
+    setLocale: setLocale2,
+    getMessages: getMessages2,
+    hasKey: hasKey2,
+    t,
+    scoped: scoped2
+  };
+}
+
+exports.createTranslator = createTranslator;

package/dist/index.d.cts

@@ -0,0 +1,265 @@
+import { LocaleNamespaceMessages, Locale, RichReplacement, FallbackLocalesMap, Replacement } from 'intor-types';
+
+/**
+ * Represents the available locale namespaces from the message map.
+ *
+ * Extracts top-level keys from the entire localized message structure,
+ * which are typically used as namespace identifiers (e.g., "common", "home", "dashboard").
+ *
+ * @template Messages - The type of the locale message map.
+ */
+type RawLocale<Messages extends LocaleNamespaceMessages> = keyof Messages & string;
+/**
+ * Computes all possible nested key paths of a deeply nested object.
+ *
+ * Example:
+ * ```ts
+ * {
+ *   a: {
+ *     b: {
+ *       c: "hello";
+ *     };
+ *   };
+ * }
+ * ```
+ * Will generate: `"a" | "a.b" | "a.b.c"`
+ *
+ * Useful for type-safe translation key autocompletion and validation.
+ *
+ * @template Messages - The message object to extract nested key paths from.
+ */
+type NestedKeyPaths<Messages> = Messages extends object ? {
+    [Key in keyof Messages]: `${Key & string}` | `${Key & string}.${NestedKeyPaths<Messages[Key]>}`;
+}[keyof Messages] : never;
+
+type TranslatorHandlers = {
+    /**
+     * A custom formatter function to format translation messages.
+     * You can use this to integrate ICU libraries like `intl-messageformat`.
+     */
+    messageFormatter?: MessageFormatter;
+    /**
+     * Handler for loading state of the translation message.
+     * Useful when translations are loaded asynchronously.
+     */
+    loadingMessageHandler?: LoadingMessageHandler;
+    /**
+     * Handler for placeholders in translation messages.
+     * Useful for handling missing or fallback placeholders.
+     */
+    placeholderHandler?: PlaceholderHandler;
+};
+/**
+ * Custom formatter for translation messages.
+ *
+ * This function receives the raw message and context to produce a formatted result.
+ * You can use this to integrate ICU-style formatting or other complex message processing.
+ *
+ * @template Result - The type of the formatted result.
+ *
+ * @param ctx - The context object containing information for formatting.
+ * @param ctx.message - The raw message string to format.
+ * @param ctx.locale - The currently active locale string (e.g. 'en-US').
+ * @param ctx.key - The translation key associated with this message.
+ * @param ctx.replacements - Optional replacement values for variables inside the message.
+ *
+ * @returns The formatted message, usually a string but can be any type.
+ */
+type MessageFormatter<Result = unknown> = (ctx: TranslatorHandlerContext & {
+    message: string;
+}) => Result;
+/**
+ * Handler function called when translation message is loading.
+ *
+ * @template Result - The type of the loading handler result.
+ *
+ * @param ctx - The context object containing locale, key, and replacements.
+ * @returns Result to display during loading (e.g. a placeholder string or React element).
+ */
+type LoadingMessageHandler<Result = unknown> = (ctx: TranslatorHandlerContext) => Result;
+/**
+ * Handler function for placeholders in translation messages.
+ *
+ * @template Result - The type of the placeholder handler result.
+ *
+ * @param ctx - The context object containing locale, key, and replacements.
+ * @returns Result to display for placeholders (e.g. a default string or React element).
+ */
+type PlaceholderHandler<Result = unknown> = (ctx: TranslatorHandlerContext) => Result;
+/**
+ * Context object passed to translation handlers.
+ * Contains necessary information for formatting or handling translation messages.
+ */
+type TranslatorHandlerContext = {
+    locale: Locale;
+    key: string;
+    replacements?: RichReplacement;
+};
+
+/**
+ * - Options for creating a translator instance.
+ *
+ * @example
+ * ```ts
+ * const options: TranslatorOptions = {
+ *   locale: 'en',
+ *   messages: {
+ *     en: { common: { hello: "Hello" } },
+ *     zh: { common: { hello: "你好" } },
+ *   },
+ *   fallbackLocales: { zh: ['en'] },
+ *   handlers: {
+ *     messageFormatter: ({ message }) => message.toUpperCase(),
+ *   },
+ * };
+ * ```
+ */
+type TranslatorOptions<Messages extends LocaleNamespaceMessages> = {
+    /**
+     * - The message definitions to be used by the translator.
+     * - These should be pre-loaded and structured by locale and namespace.
+     */
+    messages: Readonly<Messages>;
+    /**
+     * - The current active locale, e.g., "en" or "zh-TW".
+     */
+    locale: RawLocale<Messages>;
+    /**
+     * - Optional fallback locale(s) to use when a message is missing in the primary locale.
+     */
+    fallbackLocales?: FallbackLocalesMap;
+    /**
+     * - Whether the translator is currently in a loading state.
+     * - Useful for SSR or async loading scenarios.
+     */
+    isLoading?: boolean;
+    /**
+     * - The message string to return while in loading state.
+     * - Will be overridden if you provide a `loadingMessageHandler` in handlers.
+     */
+    loadingMessage?: string;
+    /**
+     * - A fallback string to show when the message key is missing.
+     * - Will be overridden if you provide a `placeholderHandler` in handlers.
+     */
+    placeholder?: string;
+    /**
+     * - Optional handlers to customize translation behavior (formatting, placeholders, etc).
+     */
+    handlers?: TranslatorHandlers;
+};
+
+type GetLocale<Messages extends LocaleNamespaceMessages> = () => RawLocale<Messages>;
+
+type GetMessages<Messages extends LocaleNamespaceMessages> = () => Readonly<Messages>;
+
+type HasKey<Messages extends LocaleNamespaceMessages> = {
+    <Locale extends RawLocale<Messages>>(key: NestedKeyPaths<Messages[Locale]>, locale?: Locale): boolean;
+    (key: string, locale?: Locale): boolean;
+};
+type LooseHasKey = (key?: string, locale?: Locale) => boolean;
+
+type Translate<Messages extends LocaleNamespaceMessages> = {
+    <Locale extends RawLocale<Messages>>(key: NestedKeyPaths<Messages[Locale]>, replacements?: Replacement | RichReplacement): string;
+    (key: string, replacements?: Replacement | RichReplacement): string;
+};
+type LooseTranslate = (key?: string, replacements?: Replacement | RichReplacement) => string;
+
+type Scoped<Messages extends LocaleNamespaceMessages> = <Locale extends RawLocale<Messages>>(preKey?: NestedKeyPaths<Messages[Locale]>) => {
+    t: LooseTranslate;
+    hasKey: LooseHasKey;
+};
+
+type SetLocale<Messages extends LocaleNamespaceMessages> = (newLocale: RawLocale<Messages>) => void;
+
+/**
+ * The main Translator interface providing all core i18n methods.
+ *
+ * This interface is the foundation of the `intor` i18n engine, giving access
+ * to all translation utilities and state management.
+ *
+ * @typeParam Messages - The full shape of all available locale messages.
+ *                       Defaults to `LocaleNamespaceMessages`.
+ */
+type Translator<Messages extends LocaleNamespaceMessages = LocaleNamespaceMessages> = {
+    /**
+     * Get the current active locale.
+     *
+     * @returns The current locale string (e.g., "en", "zh-TW").
+     */
+    getLocale: GetLocale<Messages>;
+    /**
+     * Set the current locale.
+     *
+     * @param locale - The new locale to switch to.
+     */
+    setLocale: SetLocale<Messages>;
+    /**
+     * Get all messages for the current locale.
+     *
+     * @returns The messages object containing all translation namespaces and keys.
+     */
+    getMessages: GetMessages<Messages>;
+    /**
+     * Translate a message by its key with optional replacements.
+     *
+     * This function is fully type-safe, ensuring that translation keys are valid
+     * according to the loaded locale messages.
+     *
+     * You can use autocompletion and strict checking for nested message keys
+     * by providing the locale type.
+     *
+     * @example
+     * ```ts
+     * t("home.welcome.title"); // Fully typed with key autocompletion
+     * t("dashboard.stats.count", { count: 5 });
+     * ```
+     *
+     * @param key - A dot-separated translation key (e.g., `"common.hello"`).
+     * @param replacements - Optional values to replace placeholders in the message.
+     * @returns The translated message string.
+     */
+    t: Translate<Messages>;
+    /**
+     * Check whether a strongly-typed translation key exists in the loaded messages.
+     *
+     * This method ensures the key path is valid according to the message schema
+     * for a given locale.
+     *
+     * @example
+     * ```ts
+     * hasKey("home.welcome.title"); // true or false
+     * hasKey("dashboard.stats.count", "zh");
+     * ```
+     *
+     * @param key - A dot-separated message key defined in the locale messages.
+     * @param locale - Optional locale to check against. If omitted, defaults to current locale.
+     * @returns A boolean indicating whether the key exists.
+     */
+    hasKey: HasKey<Messages>;
+    /**
+     * Create a scoped translator bound to a specific namespace.
+     *
+     * Useful for modular translation logic (e.g., per-page or per-component).
+     *
+     * @param namespace - The namespace to scope to (e.g., "auth").
+     * @returns A new translator with scoped `t()` and helpers.
+     */
+    scoped: Scoped<Messages>;
+};
+
+/**
+ * Factory function to create a translator instance.
+ *
+ * This function sets up a full-featured translator object based on the provided options,
+ * including locale management, message retrieval, key existence checking, translation,
+ * and scoped translations with prefixes.
+ *
+ * @template Messages - The shape of the locale namespace messages supported by this translator.
+ *
+ * @param translatorOptions - Configuration options including initial locale and messages.
+ * @returns A translator instance exposing locale control and translation methods.
+ */
+declare function createTranslator<Messages extends LocaleNamespaceMessages>(translatorOptions: TranslatorOptions<Messages>): Translator<Messages>;
+
+export { type LoadingMessageHandler, type MessageFormatter, type PlaceholderHandler, type Translator, createTranslator };

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+import { LocaleNamespaceMessages, Locale, RichReplacement, FallbackLocalesMap, Replacement } from 'intor-types';
+
+/**
+ * Represents the available locale namespaces from the message map.
+ *
+ * Extracts top-level keys from the entire localized message structure,
+ * which are typically used as namespace identifiers (e.g., "common", "home", "dashboard").
+ *
+ * @template Messages - The type of the locale message map.
+ */
+type RawLocale<Messages extends LocaleNamespaceMessages> = keyof Messages & string;
+/**
+ * Computes all possible nested key paths of a deeply nested object.
+ *
+ * Example:
+ * ```ts
+ * {
+ *   a: {
+ *     b: {
+ *       c: "hello";
+ *     };
+ *   };
+ * }
+ * ```
+ * Will generate: `"a" | "a.b" | "a.b.c"`
+ *
+ * Useful for type-safe translation key autocompletion and validation.
+ *
+ * @template Messages - The message object to extract nested key paths from.
+ */
+type NestedKeyPaths<Messages> = Messages extends object ? {
+    [Key in keyof Messages]: `${Key & string}` | `${Key & string}.${NestedKeyPaths<Messages[Key]>}`;
+}[keyof Messages] : never;
+
+type TranslatorHandlers = {
+    /**
+     * A custom formatter function to format translation messages.
+     * You can use this to integrate ICU libraries like `intl-messageformat`.
+     */
+    messageFormatter?: MessageFormatter;
+    /**
+     * Handler for loading state of the translation message.
+     * Useful when translations are loaded asynchronously.
+     */
+    loadingMessageHandler?: LoadingMessageHandler;
+    /**
+     * Handler for placeholders in translation messages.
+     * Useful for handling missing or fallback placeholders.
+     */
+    placeholderHandler?: PlaceholderHandler;
+};
+/**
+ * Custom formatter for translation messages.
+ *
+ * This function receives the raw message and context to produce a formatted result.
+ * You can use this to integrate ICU-style formatting or other complex message processing.
+ *
+ * @template Result - The type of the formatted result.
+ *
+ * @param ctx - The context object containing information for formatting.
+ * @param ctx.message - The raw message string to format.
+ * @param ctx.locale - The currently active locale string (e.g. 'en-US').
+ * @param ctx.key - The translation key associated with this message.
+ * @param ctx.replacements - Optional replacement values for variables inside the message.
+ *
+ * @returns The formatted message, usually a string but can be any type.
+ */
+type MessageFormatter<Result = unknown> = (ctx: TranslatorHandlerContext & {
+    message: string;
+}) => Result;
+/**
+ * Handler function called when translation message is loading.
+ *
+ * @template Result - The type of the loading handler result.
+ *
+ * @param ctx - The context object containing locale, key, and replacements.
+ * @returns Result to display during loading (e.g. a placeholder string or React element).
+ */
+type LoadingMessageHandler<Result = unknown> = (ctx: TranslatorHandlerContext) => Result;
+/**
+ * Handler function for placeholders in translation messages.
+ *
+ * @template Result - The type of the placeholder handler result.
+ *
+ * @param ctx - The context object containing locale, key, and replacements.
+ * @returns Result to display for placeholders (e.g. a default string or React element).
+ */
+type PlaceholderHandler<Result = unknown> = (ctx: TranslatorHandlerContext) => Result;
+/**
+ * Context object passed to translation handlers.
+ * Contains necessary information for formatting or handling translation messages.
+ */
+type TranslatorHandlerContext = {
+    locale: Locale;
+    key: string;
+    replacements?: RichReplacement;
+};
+
+/**
+ * - Options for creating a translator instance.
+ *
+ * @example
+ * ```ts
+ * const options: TranslatorOptions = {
+ *   locale: 'en',
+ *   messages: {
+ *     en: { common: { hello: "Hello" } },
+ *     zh: { common: { hello: "你好" } },
+ *   },
+ *   fallbackLocales: { zh: ['en'] },
+ *   handlers: {
+ *     messageFormatter: ({ message }) => message.toUpperCase(),
+ *   },
+ * };
+ * ```
+ */
+type TranslatorOptions<Messages extends LocaleNamespaceMessages> = {
+    /**
+     * - The message definitions to be used by the translator.
+     * - These should be pre-loaded and structured by locale and namespace.
+     */
+    messages: Readonly<Messages>;
+    /**
+     * - The current active locale, e.g., "en" or "zh-TW".
+     */
+    locale: RawLocale<Messages>;
+    /**
+     * - Optional fallback locale(s) to use when a message is missing in the primary locale.
+     */
+    fallbackLocales?: FallbackLocalesMap;
+    /**
+     * - Whether the translator is currently in a loading state.
+     * - Useful for SSR or async loading scenarios.
+     */
+    isLoading?: boolean;
+    /**
+     * - The message string to return while in loading state.
+     * - Will be overridden if you provide a `loadingMessageHandler` in handlers.
+     */
+    loadingMessage?: string;
+    /**
+     * - A fallback string to show when the message key is missing.
+     * - Will be overridden if you provide a `placeholderHandler` in handlers.
+     */
+    placeholder?: string;
+    /**
+     * - Optional handlers to customize translation behavior (formatting, placeholders, etc).
+     */
+    handlers?: TranslatorHandlers;
+};
+
+type GetLocale<Messages extends LocaleNamespaceMessages> = () => RawLocale<Messages>;
+
+type GetMessages<Messages extends LocaleNamespaceMessages> = () => Readonly<Messages>;
+
+type HasKey<Messages extends LocaleNamespaceMessages> = {
+    <Locale extends RawLocale<Messages>>(key: NestedKeyPaths<Messages[Locale]>, locale?: Locale): boolean;
+    (key: string, locale?: Locale): boolean;
+};
+type LooseHasKey = (key?: string, locale?: Locale) => boolean;
+
+type Translate<Messages extends LocaleNamespaceMessages> = {
+    <Locale extends RawLocale<Messages>>(key: NestedKeyPaths<Messages[Locale]>, replacements?: Replacement | RichReplacement): string;
+    (key: string, replacements?: Replacement | RichReplacement): string;
+};
+type LooseTranslate = (key?: string, replacements?: Replacement | RichReplacement) => string;
+
+type Scoped<Messages extends LocaleNamespaceMessages> = <Locale extends RawLocale<Messages>>(preKey?: NestedKeyPaths<Messages[Locale]>) => {
+    t: LooseTranslate;
+    hasKey: LooseHasKey;
+};
+
+type SetLocale<Messages extends LocaleNamespaceMessages> = (newLocale: RawLocale<Messages>) => void;
+
+/**
+ * The main Translator interface providing all core i18n methods.
+ *
+ * This interface is the foundation of the `intor` i18n engine, giving access
+ * to all translation utilities and state management.
+ *
+ * @typeParam Messages - The full shape of all available locale messages.
+ *                       Defaults to `LocaleNamespaceMessages`.
+ */
+type Translator<Messages extends LocaleNamespaceMessages = LocaleNamespaceMessages> = {
+    /**
+     * Get the current active locale.
+     *
+     * @returns The current locale string (e.g., "en", "zh-TW").
+     */
+    getLocale: GetLocale<Messages>;
+    /**
+     * Set the current locale.
+     *
+     * @param locale - The new locale to switch to.
+     */
+    setLocale: SetLocale<Messages>;
+    /**
+     * Get all messages for the current locale.
+     *
+     * @returns The messages object containing all translation namespaces and keys.
+     */
+    getMessages: GetMessages<Messages>;
+    /**
+     * Translate a message by its key with optional replacements.
+     *
+     * This function is fully type-safe, ensuring that translation keys are valid
+     * according to the loaded locale messages.
+     *
+     * You can use autocompletion and strict checking for nested message keys
+     * by providing the locale type.
+     *
+     * @example
+     * ```ts
+     * t("home.welcome.title"); // Fully typed with key autocompletion
+     * t("dashboard.stats.count", { count: 5 });
+     * ```
+     *
+     * @param key - A dot-separated translation key (e.g., `"common.hello"`).
+     * @param replacements - Optional values to replace placeholders in the message.
+     * @returns The translated message string.
+     */
+    t: Translate<Messages>;
+    /**
+     * Check whether a strongly-typed translation key exists in the loaded messages.
+     *
+     * This method ensures the key path is valid according to the message schema
+     * for a given locale.
+     *
+     * @example
+     * ```ts
+     * hasKey("home.welcome.title"); // true or false
+     * hasKey("dashboard.stats.count", "zh");
+     * ```
+     *
+     * @param key - A dot-separated message key defined in the locale messages.
+     * @param locale - Optional locale to check against. If omitted, defaults to current locale.
+     * @returns A boolean indicating whether the key exists.
+     */
+    hasKey: HasKey<Messages>;
+    /**
+     * Create a scoped translator bound to a specific namespace.
+     *
+     * Useful for modular translation logic (e.g., per-page or per-component).
+     *
+     * @param namespace - The namespace to scope to (e.g., "auth").
+     * @returns A new translator with scoped `t()` and helpers.
+     */
+    scoped: Scoped<Messages>;
+};
+
+/**
+ * Factory function to create a translator instance.
+ *
+ * This function sets up a full-featured translator object based on the provided options,
+ * including locale management, message retrieval, key existence checking, translation,
+ * and scoped translations with prefixes.
+ *
+ * @template Messages - The shape of the locale namespace messages supported by this translator.
+ *
+ * @param translatorOptions - Configuration options including initial locale and messages.
+ * @returns A translator instance exposing locale control and translation methods.
+ */
+declare function createTranslator<Messages extends LocaleNamespaceMessages>(translatorOptions: TranslatorOptions<Messages>): Translator<Messages>;
+
+export { type LoadingMessageHandler, type MessageFormatter, type PlaceholderHandler, type Translator, createTranslator };

package/dist/index.js

@@ -0,0 +1,266 @@
+import { getMessageKeyCache } from 'intor-cache';
+
+// src/methods/get-locale/get-locale.ts
+var getLocale = (localeRef) => {
+  return localeRef.current;
+};
+
+// src/methods/get-locale/create-get-locale.ts
+var createGetLocale = (localeRef) => {
+  return () => getLocale(localeRef);
+};
+
+// src/methods/get-messages/get-messages.ts
+var getMessages = (messagesRef) => {
+  return messagesRef.current;
+};
+
+// src/methods/get-messages/create-get-messages.ts
+var createGetMessages = (messagesRef) => {
+  return () => getMessages(messagesRef);
+};
+var getValueByKey = (locale, messages, key, useCache = true) => {
+  const cache = getMessageKeyCache();
+  useCache = Boolean(useCache && cache);
+  const cacheKey = `${key}`;
+  const currentLocale = cache == null ? void 0 : cache.get("locale");
+  if (currentLocale !== locale) {
+    cache == null ? void 0 : cache.clear();
+    cache == null ? void 0 : cache.set("locale", locale);
+  }
+  if (useCache && (cache == null ? void 0 : cache.has(cacheKey))) {
+    return cache == null ? void 0 : cache.get(cacheKey);
+  }
+  const value = key.split(".").reduce((acc, key2) => {
+    if (acc && typeof acc === "object" && key2 in acc) {
+      return acc[key2];
+    }
+    return void 0;
+  }, messages);
+  if (useCache && value !== void 0) {
+    cache == null ? void 0 : cache.set(cacheKey, value);
+  }
+  return value;
+};
+
+// src/utils/find-message-in-locales.ts
+var findMessageInLocales = ({
+  messages,
+  localesToTry,
+  key
+}) => {
+  for (const loc of localesToTry) {
+    const localeMessages = messages[loc];
+    if (!localeMessages) {
+      continue;
+    }
+    const candidate = getValueByKey(loc, localeMessages, key);
+    if (typeof candidate === "string") {
+      return candidate;
+    }
+  }
+  return void 0;
+};
+
+// src/utils/resolve-locales-to-try.ts
+var resolveLocalesToTry = (locale, fallbackLocales) => {
+  const fallbacks = (fallbackLocales == null ? void 0 : fallbackLocales[locale]) || [];
+  return [
+    locale,
+    ...fallbacks.filter((l) => l !== locale)
+  ];
+};
+
+// src/methods/has-key/has-key.ts
+var hasKey = ({
+  messagesRef,
+  localeRef,
+  translatorOptions,
+  key,
+  locale
+}) => {
+  const messages = messagesRef.current;
+  const { fallbackLocales } = translatorOptions;
+  const targetLocale = locale != null ? locale : localeRef.current;
+  const localesToTry = resolveLocalesToTry(targetLocale, fallbackLocales);
+  const message = findMessageInLocales({ messages, localesToTry, key });
+  return message ? true : false;
+};
+
+// src/methods/has-key/create-has-key.ts
+var createHasKey = (messagesRef, localeRef, translatorOptions) => {
+  return (key, locale) => hasKey({
+    messagesRef,
+    localeRef,
+    translatorOptions,
+    key,
+    locale
+  });
+};
+
+// src/utils/get-full-key.ts
+var getFullKey = (preKey, key) => {
+  if (!preKey) {
+    return key;
+  }
+  if (!key) {
+    return preKey;
+  }
+  return `${preKey}.${key}`;
+};
+
+// src/utils/replace-values.ts
+var replaceValues = (message, params) => {
+  if (!params || typeof params !== "object" || Object.keys(params).length === 0) {
+    return message;
+  }
+  const replaced = message.replace(/{([^}]+)}/g, (match, key) => {
+    const keys = key.split(".");
+    let value = params;
+    for (const k of keys) {
+      if (value == null || typeof value !== "object" || !(k in value)) {
+        return match;
+      }
+      value = value[k];
+    }
+    return typeof value === "string" || typeof value === "number" ? String(value) : match;
+  });
+  return replaced;
+};
+
+// src/methods/translate/translate.ts
+var translate = ({
+  messagesRef,
+  localeRef,
+  translatorOptions,
+  key,
+  replacements
+}) => {
+  const messages = messagesRef.current;
+  const { fallbackLocales, isLoading, loadingMessage, placeholder } = translatorOptions;
+  const { messageFormatter, loadingMessageHandler, placeholderHandler } = translatorOptions.handlers || {};
+  const localesToTry = resolveLocalesToTry(localeRef.current, fallbackLocales);
+  const message = findMessageInLocales({ messages, localesToTry, key });
+  if (isLoading) {
+    if (loadingMessageHandler) {
+      return loadingMessageHandler({
+        key,
+        locale: localeRef.current,
+        replacements
+      });
+    }
+    if (loadingMessage) {
+      return loadingMessage;
+    }
+  }
+  if (!message) {
+    if (placeholderHandler) {
+      return placeholderHandler({
+        key,
+        locale: localeRef.current,
+        replacements
+      });
+    }
+    if (placeholder) {
+      return placeholder;
+    }
+    return key;
+  }
+  if (messageFormatter) {
+    return messageFormatter({
+      message,
+      key,
+      locale: localeRef.current,
+      replacements
+    });
+  } else {
+    return replacements ? replaceValues(message, replacements) : message;
+  }
+};
+
+// src/methods/translate/create-translate.ts
+var createTranslate = (messagesRef, localeRef, translatorOptions) => {
+  return (key, replacements) => translate({
+    messagesRef,
+    localeRef,
+    translatorOptions,
+    key,
+    replacements
+  });
+};
+
+// src/methods/scoped/scoped.ts
+var scoped = ({
+  messagesRef,
+  localeRef,
+  translatorOptions,
+  preKey
+}) => {
+  const baseTranslate = createTranslate(
+    messagesRef,
+    localeRef,
+    translatorOptions
+  );
+  const baseHasKey = createHasKey(
+    messagesRef,
+    localeRef,
+    translatorOptions
+  );
+  return {
+    // t (Scoped)
+    t: (key, replacements) => {
+      const fullKey = getFullKey(preKey, key);
+      return baseTranslate(fullKey, replacements);
+    },
+    // hasKey (Scoped)
+    hasKey: (key, locale) => {
+      const fullKey = getFullKey(preKey, key);
+      return baseHasKey(fullKey, locale);
+    }
+  };
+};
+
+// src/methods/scoped/create-scoped.ts
+var createScoped = (messagesRef, localeRef, translatorOptions) => {
+  return (preKey) => scoped({ messagesRef, localeRef, translatorOptions, preKey });
+};
+
+// src/methods/set-locale/set-locale.ts
+var setLocale = ({
+  messagesRef,
+  localeRef,
+  newLocale
+}) => {
+  const messages = messagesRef.current;
+  if (newLocale in messages) {
+    localeRef.current = newLocale;
+  }
+};
+
+// src/methods/set-locale/create-set-locale.ts
+var createSetLocale = (messagesRef, localeRef) => {
+  return (newLocale) => setLocale({ messagesRef, localeRef, newLocale });
+};
+
+// src/create-translator.ts
+function createTranslator(translatorOptions) {
+  const { locale } = translatorOptions;
+  const messagesRef = { current: translatorOptions.messages };
+  const localeRef = { current: locale };
+  const getLocale2 = createGetLocale(localeRef);
+  const setLocale2 = createSetLocale(messagesRef, localeRef);
+  const getMessages2 = createGetMessages(messagesRef);
+  const hasKey2 = createHasKey(messagesRef, localeRef, translatorOptions);
+  const t = createTranslate(messagesRef, localeRef, translatorOptions);
+  const scoped2 = createScoped(messagesRef, localeRef, translatorOptions);
+  return {
+    getLocale: getLocale2,
+    setLocale: setLocale2,
+    getMessages: getMessages2,
+    hasKey: hasKey2,
+    t,
+    scoped: scoped2
+  };
+}
+
+export { createTranslator };

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "intor-translator",
+  "version": "1.0.0",
+  "description": "A lightweight, type-safe i18n translator for JavaScript and TypeScript. Provides runtime translation, scoped messages, ICU formatting, and custom handlers.",
+  "author": "Yiming Liao",
+  "license": "MIT",
+  "homepage": "https://github.com/yiming-liao/intor-translator#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yiming-liao/intor-translator"
+  },
+  "bugs": {
+    "url": "https://github.com/yiming-liao/intor-translator/issues"
+  },
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "translation",
+    "typescript",
+    "node",
+    "nextjs",
+    "react",
+    "translator",
+    "i18n core",
+    "custom messages"
+  ],
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint",
+    "type-check": "tsc --noEmit",
+    "test": "jest",
+    "test:coverage": "jest --coverage && open coverage/lcov-report/index.html",
+    "prepublishOnly": "yarn build"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "intor-cache": "^1.0.1",
+    "intor-types": "^1.0.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.27.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.1.4",
+    "@types/react-dom": "^19.1.5",
+    "eslint": "^9.27.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-prettier": "^5.4.0",
+    "eslint-plugin-unused-imports": "^4.1.4",
+    "globals": "^16.1.0",
+    "intl-messageformat": "^10.7.16",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jest-fetch-mock": "^3.0.3",
+    "next": "^15.3.2",
+    "prettier": "^3.5.3",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "ts-jest": "^29.3.2",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.32.1"
+  }
+}