intor-translator 1.1.5 → 1.2.0

package/dist/index.js

@@ -1,4 +1,4 @@
-// src/utils/find-message-in-locales.ts
+// src/translators/shared/utils/find-message-in-locales.ts
 var findMessageInLocales = ({
   messages,
   candidateLocales,
@@ -21,28 +21,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;
@@ -61,63 +83,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.
@@ -126,7 +202,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.
@@ -134,30 +210,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
     });
@@ -165,17 +296,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;
@@ -193,8 +325,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
         });
@@ -202,10 +334,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
         });
@@ -214,4 +347,4 @@ var ScopeTranslator = class extends CoreTranslator {
   }
 };
 
-export { ScopeTranslator, ScopeTranslator as Translator };
+export { ScopeTranslator as Translator };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "intor-translator",
-  "version": "1.1.5",
-  "description": "A type safe translator that knows what to say and how to handle the rest. Supports custom messages, rich replacements, and async loading.",
+  "version": "1.2.0",
+  "description": "🤖 A modern, type-safe i18n engine.",
   "author": "Yiming Liao",
   "license": "MIT",
   "homepage": "https://github.com/yiming-liao/intor-translator#readme",
@@ -17,21 +17,9 @@
     "internationalization",
     "translation",
     "typescript",
-    "node",
-    "nextjs",
-    "react",
-    "translator",
-    "i18n core",
-    "custom messages",
-    "rich replacements",
-    "async loading",
-    "type safe",
     "type-safe",
-    "type safety",
-    "type-safe translator",
-    "type-safe i18n",
-    "type-safe translation",
-    "type-safe core"
+    "i18n engine",
+    "translator"
   ],
   "exports": {
     ".": {
@@ -56,7 +44,12 @@
     "type": "tsc --noEmit",
     "lint": "eslint",
     "lint:debug": "eslint --debug",
-    "knip": "knip --config .config/knip.config.ts"
+    "knip": "knip --config .config/knip.config.ts",
+    "examples:html": "vite --config examples/html/vite.config.ts"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16.0.0"
   },
   "dependencies": {},
   "devDependencies": {
@@ -77,10 +70,7 @@
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.6",
     "vitest": "^4.0.9"
-  },
-  "sideEffects": false,
-  "engines": {
-    "node": ">=16.0.0"
   }
 }