intor-translator 1.1.5 → 1.2.0

package/README.md

@@ -2,7 +2,8 @@
 
 <div align="center">
 
-A type safe translator that knows what to say and how to handle the rest.
+A modern **i18n engine** powered by a customizable, type-safe translation pipeline.  
+Easy to adopt, modular at its core, and fully extensible.
 
 </div>
 
@@ -10,44 +11,32 @@ A type safe translator that knows what to say and how to handle the rest.
 
 [![NPM version](https://img.shields.io/npm/v/intor-translator?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/intor-translator)
 [![Bundle size](https://img.shields.io/bundlephobia/minzip/intor-translator?style=flat&colorA=000000&colorB=000000)](https://bundlephobia.com/package/intor-translator)
+[![Coverage Status](https://img.shields.io/coveralls/github/yiming-liao/intor-translator.svg?branch=main&style=flat&colorA=000000&colorB=000000)](https://coveralls.io/github/yiming-liao/intor-translator?branch=main)
 [![License](https://img.shields.io/npm/l/intor-translator?style=flat&colorA=000000&colorB=000000)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-%E2%9C%94-blue?style=flat&colorA=000000&colorB=000000)](https://www.typescriptlang.org/)
 
 </div>
 
-> Translate with confidence.  
-> A type-safe i18n engine with fallback, scoped namespaces, and graceful loading.
-
----
+> Structured 󠁯•󠁏 Predictable 󠁯•󠁏 Beautifully simple
 
 ## Features
 
-- 🌍 Fallback locale support for smooth language switching
-- ⚡ Reactive translation logic that updates on the fly
-- 🧠 Type-safe nested key paths with full autocomplete
-- 🔁 Flexible replacement and interpolation support
-- 🎨 Rich formatting for complex replacement content
-- 🌀 Graceful handling of loading and async states
-- 🔧 Configurable handlers for fallback, loading, and missing keys
-- 🧩 Scoped translators for modules and namespaces
-
----
+- 🔧 **Modular Pipeline** – A pluggable, hook-driven flow for any translation logic.
+- ✨ **Typed Autocomplete** – Inferred keys and locales with precise, reliable completion.
+- 🌐 **Framework-Agnostic** – A lightweight engine that runs anywhere in JavaScript.
 
-## <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Symbols/Triangular%20Flag.png" alt="Triangular Flag" width="16" height="16" /> Installation
+## Installation
 
 ```bash
+# npm
 npm install intor-translator
-```
-
-or use **yarn**
-
-```bash
+# yarn
 yarn add intor-translator
+# pnpm
+pnpm add intor-translator
 ```
 
----
-
-## <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Travel%20and%20places/Rocket.png" alt="Rocket" width="25" height="25" /> Quick Start
+## Quick Start
 
 ```typescript
 import { Translator } from "intor-translator";
@@ -67,134 +56,35 @@ translator.t("hello"); // -> Hello World
 translator.t("greeting", { name: "John doe" }); // -> Hello, John doe!
 ```
 
----
+## Handlers & Hooks
 
-## <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Activities/Sparkles.png" alt="Sparkles" width="25" height="25" /> Advanced Features
+Intor Translator is powered by **a flexible pipeline** that lets you control how translations behave and how they are rendered.
 
-- Fallback Locales, Placeholder & Custom Handlers
+### Handlers — format the final output
 
-```typescript
-const translator = new Translator({
-  locale: "en",
-  messages: {
-    en: {
-      welcome: "Welcome back, {name}",
-    },
-    zh: {
-      welcome: "歡迎回來，{name}",
-      notification: "你有 {count} 則新通知",
-    },
-  },
-  fallbackLocales: { en: ["zh"] }, // Use zh if message not found in en
-  placeholder: "Content unavailable", // Shown if key is missing in all locales
-  handlers: {
-    formatHandler: ({ locale, message }) =>
-      locale === "zh" ? `${message}。` : `${message}.`, // Auto punctuation per locale
-  },
-});
+<sup>_changing how translations look_.</sup>
 
-// en has 'welcome'
-console.log(translator.t("welcome", { name: "John" })); // -> Welcome back, John.
+Handlers operate on the resolved message, use them to:
 
-// en does not have 'notification', fallback to zh
-console.log(translator.t("notification", { count: 3 })); // -> 你有 3 則新通知。
+- format ICU messages
+- apply custom plural logic
+- post-process output
+- style or transform the final string
 
-// message does not exist in any locale
-console.log(translator.t("unknown.key")); // -> Content unavailable
-```
+### Hooks — shape the translation flow
 
-- With Custom ICU Formatter
+<sup>_changing how translations work_.</sup>
 
-```typescript
-import { Translator, FormatMessage } from "intor-translator";
-import { IntlMessageFormat } from "intl-messageformat";
+Hooks run through the pipeline and can intercept any stage, use them to:
 
-// Create a custom handler
-const formatHandler: FormatMessage = ({ message, locale, replacements }) => {
-  const formatter = new IntlMessageFormat(message, locale);
-  return formatter.format(replacements);
-};
+- transform keys or messages
+- adjust fallback behavior
+- implement loading or missing logic
+- attach metadata or analytics
 
-const messages = {
-  en: {
-    notification:
-      "{name} has {count, plural, =0 {no messages} one {1 message} other {# messages}}.",
-  },
-};
-
-// Create a translator instance
-const translator = new Translator({
-  locale: "en",
-  messages,
-  handlers: { formatHandler },
-});
-
-translator.t("notification", { name: "John", count: 0 }); // -> John has no messages.
-translator.t("notification", { name: "John", count: 5 }); // -> John has 5 messages.
-```
-
----
-
-## API Reference
-
-### Translator Parameters
-
-| Option            | Type                                  | Description                                                              |
-| ----------------- | ------------------------------------- | ------------------------------------------------------------------------ |
-| `messages`        | `Readonly<LocaleMessages>`            | Translation messages grouped by locale and namespace                     |
-| `locale`          | `string`                              | Active locale key                                                        |
-| `fallbackLocales` | `Record<Locale, Locale[]>` (optional) | Locales to fallback to when a key is missing                             |
-| `placeholder`     | `string` (optional)                   | Message to display when a key is missing in all locales                  |
-| `loadingMessage`  | `string` (optional)                   | Message to display during loading or async state                         |
-| `handlers`        | `TranslateHandlers` (optional)        | Custom functions for formatting, loading state, and missing key handling |
-
-**TranslateHandlers :**
-
-```ts
-type TranslateHandlers = {
-  formatHandler?: (
-    ctx: TranslateHandlerContext & { message: string },
-  ) => unknown;
-  LoadingHandler?: (ctx: TranslateHandlerContext) => unknown;
-  MissingHandler?: (ctx: TranslateHandlerContext) => unknown;
-};
-```
-
-> Use handlers to control how messages are formatted, what to show during loading, and how to respond to missing keys.  
-> Each handler receives a full translation context, including the current locale, key, and replacement values.
+> Together, they form a customizable translation pipeline — structured, predictable, beautifully simple.
 
 ---
 
-### Instance Properties
-
-| Property    | Type        | Description                                |
-| ----------- | ----------- | ------------------------------------------ |
-| `messages`  | `M`         | Current messages object                    |
-| `locale`    | `Locale<M>` | Currently active locale                    |
-| `isLoading` | `boolean`   | Whether the translator is in loading state |
-
----
-
-### Instance Methods
-
-| Method        | Signature                                         | Description                                                         |
-| ------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
-| `setMessages` | `(messages: M) => void`                           | Replaces the current message set                                    |
-| `setLocale`   | `(locale: Locale<M>) => boolean`                  | Sets a new locale and returns whether it changed                    |
-| `setLoading`  | `(state: boolean) => void`                        | Sets the loading state manually                                     |
-| `hasKey`      | `(key, targetLocale?) => boolean`                 | Checks whether the given key exists in the target or current locale |
-| `t`           | `<Result = string>(key, replacements?) => Result` | Translates a key with optional replacements                         |
-| `scoped`      | `(preKey: string) => { hasKey(), t() }`           | Creates a scoped translator with a namespace prefix                 |
-
-**translator.t(key, replacements?)**
-
-- Fully type-safe key access
-- Supports nested keys
-- Supports both string and rich replacements
-
-**translator.scoped(preKey)**
-
-- Returns a scoped translator instance based on a message subtree
-- Useful for organizing large sets of translations with shared prefixes
-
----
+**_For more advanced usage, see the full examples._**
+[View examples ↗](https://github.com/yiming-liao/intor-translator/tree/main/examples)

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-// src/utils/find-message-in-locales.ts
+// src/translators/shared/utils/find-message-in-locales.ts
 var findMessageInLocales = ({
   messages,
   candidateLocales,
@@ -23,28 +23,50 @@ var findMessageInLocales = ({
   }
 };
 
-// src/utils/resolve-candidate-locales.ts
-var resolveCandidateLocales = (locale, fallbackLocalesMap) => {
-  const fallbacks = fallbackLocalesMap?.[locale] || [];
-  const filteredFallbacks = fallbacks.filter((l) => l !== locale);
-  return [locale, ...filteredFallbacks];
+// src/pipeline/hooks/find-message.hook.ts
+var findMessageHook = {
+  name: "findMessage",
+  order: 200,
+  run(ctx) {
+    ctx.rawMessage = findMessageInLocales({
+      messages: ctx.messages,
+      candidateLocales: ctx.candidateLocales,
+      key: ctx.key
+    });
+  }
 };
 
-// src/translator-methods/has-key/has-key.ts
-var hasKey = ({
-  messagesRef,
-  localeRef,
-  key,
-  targetLocale
-}) => {
-  const messages = messagesRef.current;
-  const locale = localeRef.current;
-  const candidateLocales = resolveCandidateLocales(targetLocale || locale);
-  const message = findMessageInLocales({ messages, candidateLocales, key });
-  return !!message;
+// src/pipeline/utils/make-handler-context.ts
+function makeHandlerContext(ctx) {
+  return Object.freeze({
+    locale: ctx.locale,
+    key: ctx.key,
+    replacements: ctx.replacements,
+    messages: ctx.messages,
+    candidateLocales: ctx.candidateLocales,
+    config: ctx.config,
+    isLoading: ctx.isLoading,
+    rawMessage: ctx.rawMessage,
+    formattedMessage: ctx.formattedMessage,
+    meta: ctx.meta
+  });
+}
+
+// src/pipeline/hooks/format.hook.ts
+var formatHook = {
+  name: "format",
+  order: 500,
+  run(ctx) {
+    const { config, rawMessage } = ctx;
+    const { formatHandler } = config.handlers || {};
+    if (!formatHandler || rawMessage === void 0) return;
+    ctx.formattedMessage = formatHandler(
+      makeHandlerContext(ctx)
+    );
+  }
 };
 
-// src/utils/replace-values.ts
+// src/translators/shared/utils/replace-values.ts
 var replaceValues = (message, params) => {
   if (!params || typeof params !== "object" || Object.keys(params).length === 0) {
     return message;
@@ -63,63 +85,117 @@ var replaceValues = (message, params) => {
   return replaced;
 };
 
-// src/translator-methods/translate/translate.ts
-var translate = ({
-  messagesRef,
-  localeRef,
-  isLoadingRef,
-  translateConfig,
-  key,
-  replacements
-}) => {
-  const messages = messagesRef.current;
-  const locale = localeRef.current;
-  const isLoading = isLoadingRef.current;
-  const { fallbackLocales, loadingMessage, placeholder, handlers } = translateConfig;
-  const { formatHandler, loadingHandler, missingHandler } = handlers || {};
-  const candidateLocales = resolveCandidateLocales(locale, fallbackLocales);
-  const message = findMessageInLocales({ messages, candidateLocales, key });
-  if (isLoading && (loadingHandler || loadingMessage)) {
-    if (loadingHandler)
-      return loadingHandler({ key, locale, replacements });
-    if (loadingMessage) return loadingMessage;
-  }
-  if (message === void 0) {
-    if (missingHandler)
-      return missingHandler({ key, locale, replacements });
-    if (placeholder) return placeholder;
-    return key;
-  }
-  if (formatHandler) {
-    return formatHandler({ message, key, locale, replacements });
-  }
-  return replacements ? replaceValues(message, replacements) : message;
+// src/pipeline/hooks/interpolate.hook.ts
+var interpolateHook = {
+  name: "interpolate",
+  order: 600,
+  run(ctx) {
+    const { rawMessage, formattedMessage, replacements } = ctx;
+    const message = formattedMessage ?? rawMessage;
+    if (typeof message !== "string" || !replacements) {
+      ctx.finalMessage = message;
+      return;
+    }
+    ctx.finalMessage = replaceValues(message, replacements);
+  }
 };
 
+// src/pipeline/hooks/loading.hook.ts
+var loadingHook = {
+  name: "loading",
+  order: 300,
+  run(ctx) {
+    const { config, isLoading } = ctx;
+    if (!isLoading) return;
+    const { loadingHandler } = config.handlers || {};
+    if (loadingHandler) {
+      return {
+        done: true,
+        value: loadingHandler(makeHandlerContext(ctx))
+      };
+    }
+    const { loadingMessage } = config;
+    if (loadingMessage) {
+      return { done: true, value: loadingMessage };
+    }
+  }
+};
+
+// src/pipeline/hooks/missing.hook.ts
+var missingHook = {
+  name: "missing",
+  order: 400,
+  run(ctx) {
+    const { config, key, rawMessage } = ctx;
+    if (rawMessage !== void 0) return;
+    const { missingHandler } = config.handlers || {};
+    if (missingHandler) {
+      return {
+        done: true,
+        value: missingHandler(makeHandlerContext(ctx))
+      };
+    }
+    const { placeholder } = config;
+    if (placeholder) {
+      return { done: true, value: placeholder };
+    }
+    return { done: true, value: key };
+  }
+};
+
+// src/translators/shared/utils/resolve-candidate-locales.ts
+var resolveCandidateLocales = (locale, fallbackLocalesMap) => {
+  const fallbacks = fallbackLocalesMap?.[locale] || [];
+  const filteredFallbacks = fallbacks.filter((l) => l !== locale);
+  return [locale, ...filteredFallbacks];
+};
+
+// src/pipeline/hooks/resolve-locales.hook.ts
+var resolveLocalesHook = {
+  name: "resolveLocales",
+  order: 100,
+  run(ctx) {
+    ctx.candidateLocales = resolveCandidateLocales(
+      ctx.locale,
+      ctx.config.fallbackLocales
+    );
+  }
+};
+
+// src/pipeline/hooks/index.ts
+var DEFAULT_HOOKS = [
+  resolveLocalesHook,
+  findMessageHook,
+  loadingHook,
+  missingHook,
+  formatHook,
+  interpolateHook
+];
+
 // src/translators/base-translator/base-translator.ts
 var BaseTranslator = class {
   /** Current messages for translation */
-  messagesRef;
+  _messages;
   /** Current active locale */
-  localeRef;
+  _locale;
   /** Current loading state */
-  isLoadingRef;
+  _isLoading;
   constructor(options) {
-    this.messagesRef = { current: options.messages ?? {} };
-    this.localeRef = { current: options.locale };
-    this.isLoadingRef = { current: options.isLoading ?? false };
+    this._messages = options.messages ?? {};
+    this._locale = options.locale;
+    this._isLoading = options.isLoading ?? false;
   }
   /** Get messages. */
   get messages() {
-    return this.messagesRef.current;
+    return this._messages;
   }
   /** Get the current active locale. */
   get locale() {
-    return this.localeRef.current;
+    return this._locale;
   }
   /** Get the current loading state. */
   get isLoading() {
-    return this.isLoadingRef.current;
+    return this._isLoading;
   }
   /**
    * Replace messages with new ones.
@@ -128,7 +204,7 @@ var BaseTranslator = class {
    * The type cast bypasses TypeScript restrictions on dynamic messages.
    */
   setMessages(messages) {
-    this.messagesRef.current = messages;
+    this._messages = messages;
   }
   /**
    * Set the active locale.
@@ -136,30 +212,85 @@ var BaseTranslator = class {
    * - Note: Unlike `setMessages`, the locale structure cannot be changed at runtime.
    */
   setLocale(newLocale) {
-    this.localeRef.current = newLocale;
+    this._locale = newLocale;
   }
   /** Set the loading state. */
   setLoading(state) {
-    this.isLoadingRef.current = state;
+    this._isLoading = state;
   }
 };
 
+// src/translators/shared/has-key.ts
+var hasKey = ({
+  messages,
+  locale,
+  key,
+  targetLocale
+}) => {
+  const candidateLocales = resolveCandidateLocales(targetLocale || locale);
+  const message = findMessageInLocales({
+    messages,
+    candidateLocales,
+    key
+  });
+  return !!message;
+};
+
+// src/pipeline/run-pipeline.ts
+function runPipeline(ctx, hooks) {
+  for (const hook of hooks) {
+    const result = hook.run(ctx);
+    if (result?.done) {
+      return result.value;
+    }
+  }
+  return ctx.finalMessage ?? ctx.rawMessage;
+}
+
+// src/translators/shared/translate.ts
+function translate(options) {
+  const ctx = {
+    ...options,
+    config: options.translateConfig,
+    candidateLocales: [],
+    meta: {}
+  };
+  return runPipeline(ctx, options.hooks);
+}
+
 // src/translators/core-translator/core-translator.ts
 var CoreTranslator = class extends BaseTranslator {
-  options;
+  /** User-provided options including messages, locale, and config. */
+  translateConfig;
+  /** Active pipeline hooks applied during translation. */
+  hooks = [...DEFAULT_HOOKS];
   constructor(options) {
-    super({
-      locale: options.locale,
-      messages: options.messages,
-      isLoading: options.isLoading
-    });
-    this.options = options;
+    const { locale, messages, isLoading, plugins, ...translateConfig } = options;
+    super({ locale, messages, isLoading });
+    this.translateConfig = translateConfig;
+    if (plugins) {
+      for (const plugin of plugins) this.use(plugin);
+    }
+    this.sortHooks();
+  }
+  /** Sort hooks by order value (lower runs earlier). */
+  sortHooks() {
+    this.hooks.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  }
+  /** Register a plugin or a raw pipeline hook. */
+  use(plugin) {
+    if ("run" in plugin) this.hooks.push(plugin);
+    else if ("hook" in plugin && plugin.hook) {
+      const hooks = Array.isArray(plugin.hook) ? plugin.hook : [plugin.hook];
+      this.hooks.push(...hooks);
+    }
+    this.sortHooks();
   }
   /** Check if a key exists in the specified locale or current locale. */
   hasKey = (key, targetLocale) => {
     return hasKey({
-      messagesRef: this.messagesRef,
-      localeRef: this.localeRef,
+      messages: this._messages,
+      locale: this._locale,
       key,
       targetLocale
     });
@@ -167,17 +298,18 @@ var CoreTranslator = class extends BaseTranslator {
   /** Get the translated message for a key, with optional replacements. */
   t = (key, replacements) => {
     return translate({
-      messagesRef: this.messagesRef,
-      localeRef: this.localeRef,
-      isLoadingRef: this.isLoadingRef,
-      translateConfig: this.options,
+      hooks: this.hooks,
+      messages: this._messages,
+      locale: this._locale,
+      isLoading: this._isLoading,
+      translateConfig: this.translateConfig,
       key,
       replacements
     });
   };
 };
 
-// src/utils/get-full-key.ts
+// src/translators/scope-translator/utils/get-full-key.ts
 var getFullKey = (preKey = "", key = "") => {
   if (!preKey) return key;
   if (!key) return preKey;
@@ -195,8 +327,8 @@ var ScopeTranslator = class extends CoreTranslator {
       hasKey: (key, targetLocale) => {
         const fullKey = getFullKey(preKey, key);
         return hasKey({
-          messagesRef: this.messagesRef,
-          localeRef: this.localeRef,
+          messages: this._messages,
+          locale: this._locale,
           key: fullKey,
           targetLocale
         });
@@ -204,10 +336,11 @@ var ScopeTranslator = class extends CoreTranslator {
       t: (key, replacements) => {
         const fullKey = getFullKey(preKey, key);
         return translate({
-          messagesRef: this.messagesRef,
-          localeRef: this.localeRef,
-          isLoadingRef: this.isLoadingRef,
-          translateConfig: this.options,
+          hooks: this.hooks,
+          messages: this._messages,
+          locale: this._locale,
+          isLoading: this._isLoading,
+          translateConfig: this.translateConfig,
           key: fullKey,
           replacements
         });
@@ -216,5 +349,4 @@ var ScopeTranslator = class extends CoreTranslator {
   }
 };
 
-exports.ScopeTranslator = ScopeTranslator;
 exports.Translator = ScopeTranslator;