intor-translator 1.0.15 → 1.1.0

package/README.md

@@ -88,7 +88,7 @@ const translator = new Translator({
   fallbackLocales: { en: ["zh"] }, // Use zh if message not found in en
   placeholder: "Content unavailable", // Shown if key is missing in all locales
   handlers: {
-    formatMessage: ({ locale, message }) =>
+    formatHandler: ({ locale, message }) =>
       locale === "zh" ? `${message}。` : `${message}.`, // Auto punctuation per locale
   },
 });
@@ -110,7 +110,7 @@ import { Translator, FormatMessage } from "intor-translator";
 import { IntlMessageFormat } from "intl-messageformat";
 
 // Create a custom handler
-const formatMessage: FormatMessage = ({ message, locale, replacements }) => {
+const formatHandler: FormatMessage = ({ message, locale, replacements }) => {
   const formatter = new IntlMessageFormat(message, locale);
   return formatter.format(replacements);
 };
@@ -126,7 +126,7 @@ const messages = {
 const translator = new Translator({
   locale: "en",
   messages,
-  handlers: { formatMessage },
+  handlers: { formatHandler },
 });
 
 translator.t("notification", { name: "John", count: 0 }); // -> John has no messages.
@@ -141,7 +141,7 @@ translator.t("notification", { name: "John", count: 5 }); // -> John has 5 messa
 
 | Option            | Type                                  | Description                                                              |
 | ----------------- | ------------------------------------- | ------------------------------------------------------------------------ |
-| `messages`        | `Readonly<LocaleNamespaceMessages>`   | Translation messages grouped by locale and namespace                     |
+| `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                  |
@@ -152,9 +152,11 @@ translator.t("notification", { name: "John", count: 5 }); // -> John has 5 messa
 
 ```ts
 type TranslateHandlers = {
-  formatMessage?: (ctx: TranslateContext & { message: string }) => unknown;
-  onLoading?: (ctx: TranslateContext) => unknown;
-  onMissing?: (ctx: TranslateContext) => unknown;
+  formatHandler?: (
+    ctx: TranslateHandlerContext & { message: string },
+  ) => unknown;
+  LoadingHandler?: (ctx: TranslateHandlerContext) => unknown;
+  MissingHandler?: (ctx: TranslateHandlerContext) => unknown;
 };
 ```
 
@@ -165,11 +167,11 @@ type TranslateHandlers = {
 
 ### Instance Properties
 
-| Property    | Type           | Description                                |
-| ----------- | -------------- | ------------------------------------------ |
-| `messages`  | `M`            | Current messages object                    |
-| `locale`    | `LocaleKey<M>` | Currently active locale                    |
-| `isLoading` | `boolean`      | Whether the translator is in loading state |
+| Property    | Type        | Description                                |
+| ----------- | ----------- | ------------------------------------------ |
+| `messages`  | `M`         | Current messages object                    |
+| `locale`    | `Locale<M>` | Currently active locale                    |
+| `isLoading` | `boolean`   | Whether the translator is in loading state |
 
 ---
 
@@ -178,7 +180,7 @@ type TranslateHandlers = {
 | Method        | Signature                                         | Description                                                         |
 | ------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
 | `setMessages` | `(messages: M) => void`                           | Replaces the current message set                                    |
-| `setLocale`   | `(locale: LocaleKey<M>) => boolean`               | Sets a new locale and returns whether it changed                    |
+| `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                         |

package/dist/index.cjs

@@ -1,118 +1,31 @@
 'use strict';
 
-// src/cache/cache.ts
-var Cache = class {
-  constructor(maxSize = 100, ttl = 1e3 * 60 * 5) {
-    this.cache = /* @__PURE__ */ new Map();
-    this.maxSize = maxSize;
-    this.ttl = ttl;
-  }
-  // Clean up expired cache entries
-  cleanUp() {
-    const now = Date.now();
-    this.cache.forEach((entry, key) => {
-      if (now - entry.timestamp > this.ttl) {
-        this.cache.delete(key);
-      }
-    });
-  }
-  // Get cache data
-  get(key) {
-    this.cleanUp();
-    const entry = this.cache.get(key);
-    if (entry) {
-      entry.timestamp = Date.now();
-      return entry.value;
-    }
-    return void 0;
-  }
-  // Set cache data
-  set(key, value) {
-    this.cleanUp();
-    if (this.cache.size >= this.maxSize) {
-      const oldestKey = this.cache.keys().next().value;
-      if (oldestKey) this.cache.delete(oldestKey);
-    }
-    this.cache.set(key, { value, timestamp: Date.now() });
-  }
-  // Check if a key exists in the cache
-  has(key) {
-    this.cleanUp();
-    return this.cache.has(key);
-  }
-  // Clear all cache
-  clear() {
-    this.cache.clear();
-  }
-};
-
-// src/cache/message-key-cache.ts
-var MESSAGE_KEY_CACHE_MAX_SIZE = 100;
-var MESSAGE_KEY_CACHE_EXPIRES_TIME = 1e3 * 60 * 5;
-var messageKeyCache;
-var getMessageKeyCache = () => {
-  if (typeof window !== "undefined" && !messageKeyCache) {
-    messageKeyCache = new Cache(
-      MESSAGE_KEY_CACHE_MAX_SIZE,
-      MESSAGE_KEY_CACHE_EXPIRES_TIME
-    );
-  }
-  return messageKeyCache;
-};
-var clearMessageKeyCache = () => {
-  if (messageKeyCache) {
-    messageKeyCache.clear();
-    messageKeyCache = void 0;
-  }
-};
-
-// src/utils/get-value-by-key.ts
-var getValueByKey = (locale, messages, key, useCache = true) => {
-  const cache = getMessageKeyCache();
-  useCache = Boolean(useCache && cache);
-  const cacheKey = `${key}`;
-  const currentLocale = cache?.get("locale");
-  if (currentLocale !== locale) {
-    cache?.clear();
-    cache?.set("locale", locale);
-  }
-  if (useCache && cache?.has(cacheKey)) {
-    return 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?.set(cacheKey, value);
-  }
-  return value;
-};
-
 // src/utils/find-message-in-locales.ts
 var findMessageInLocales = ({
   messages,
-  localesToTry,
+  candidateLocales,
   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;
+  for (const locale of candidateLocales) {
+    const localeMessages = messages[locale];
+    if (!localeMessages) continue;
+    let candidate = localeMessages;
+    const keys = key.split(".");
+    for (const k of keys) {
+      if (candidate && typeof candidate === "object" && k in candidate) {
+        candidate = candidate[k];
+      } else {
+        candidate = void 0;
+        break;
+      }
     }
+    if (typeof candidate === "string") return candidate;
   }
-  return void 0;
 };
 
-// src/utils/resolve-locales-to-try.ts
-var resolveLocalesToTry = (locale, fallbackLocales) => {
-  const fallbacks = fallbackLocales?.[locale] || [];
+// src/utils/resolve-candidate-locales.ts
+var resolveCandidateLocales = (locale, fallbackLocalesMap) => {
+  const fallbacks = fallbackLocalesMap?.[locale] || [];
   const filteredFallbacks = fallbacks.filter((l) => l !== locale);
   return [locale, ...filteredFallbacks];
 };
@@ -129,11 +42,9 @@ var hasKey = ({
   if (!messages) {
     throw new Error("[intor-translator] 'messages' is required");
   }
-  if (!locale) {
-    throw new Error("[intor-translator] 'locale' is required");
-  }
-  const localesToTry = resolveLocalesToTry(targetLocale || locale);
-  return findMessageInLocales({ messages, localesToTry, key }) ? true : false;
+  const candidateLocales = resolveCandidateLocales(targetLocale || locale);
+  const message = findMessageInLocales({ messages, candidateLocales, key });
+  return !!message;
 };
 
 // src/utils/replace-values.ts
@@ -141,7 +52,7 @@ var replaceValues = (message, params) => {
   if (!params || typeof params !== "object" || Object.keys(params).length === 0) {
     return message;
   }
-  const replaced = message.replace(/{([^}]+)}/g, (match, key) => {
+  const replaced = message.replaceAll(/{([^}]+)}/g, (match, key) => {
     const keys = key.split(".");
     let value = params;
     for (const k of keys) {
@@ -166,85 +77,61 @@ var translate = ({
 }) => {
   const messages = messagesRef.current;
   const locale = localeRef.current;
+  const isLoading = isLoadingRef.current;
   if (!messages) {
     throw new Error("[intor-translator] 'messages' is required");
   }
-  if (!locale) {
-    throw new Error("[intor-translator] 'locale' is required");
-  }
-  const isLoading = isLoadingRef.current;
-  const {
-    fallbackLocales,
-    loadingMessage,
-    placeholder,
-    handlers = {}
-  } = translateConfig;
-  const { formatMessage, onLoading, onMissing } = handlers;
-  const localesToTry = resolveLocalesToTry(locale, fallbackLocales);
-  const message = findMessageInLocales({ messages, localesToTry, key });
-  if (isLoading) {
-    if (onLoading) {
-      return onLoading({
-        key,
-        locale,
-        replacements
-      });
-    }
-    if (loadingMessage) {
-      return loadingMessage;
-    }
-  }
-  if (message === void 0 || message === null) {
-    if (onMissing) {
-      return onMissing({ key, locale, replacements });
-    }
-    if (placeholder !== void 0 && placeholder !== null) {
-      return placeholder;
-    }
+  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 (formatMessage) {
-    return formatMessage({ message, key, locale, replacements });
-  } else {
-    return replacements ? replaceValues(message, replacements) : message;
+  if (formatHandler) {
+    return formatHandler({ message, key, locale, replacements });
   }
+  return replacements ? replaceValues(message, replacements) : message;
 };
 
 // src/translators/base-translator/base-translator.ts
 var BaseTranslator = class {
   constructor(options) {
+    /** Current messages for translation, updatable at runtime */
     this.messagesRef = { current: void 0 };
-    /** Check if a key exists in the specified locale or current locale. */
-    this.hasKey = (key, targetLocale) => {
-      return hasKey({
-        messagesRef: this.messagesRef,
-        localeRef: this.localeRef,
-        key,
-        targetLocale
-      });
-    };
     this.messagesRef = { current: options.messages };
     this.localeRef = { current: options.locale };
   }
-  /** Get all message data. */
+  /** Get messages. */
   get messages() {
     return this.messagesRef.current;
   }
+  /** Get the current active locale. */
+  get locale() {
+    return this.localeRef.current;
+  }
   /**
    * Replace messages with new ones.
    *
-   * Note: This allows runtime setting of messages even if M is inferred as `never` (uninitialized).
-   * Type cast is used to bypass TypeScript restrictions on dynamic messages.
+   * - Note: This allows runtime setting of messages even if `M` is inferred as `never`.
+   * The type cast bypasses TypeScript restrictions on dynamic messages.
    */
   setMessages(messages) {
     this.messagesRef.current = messages;
-    clearMessageKeyCache();
   }
-  /** Get the current active locale. */
-  get locale() {
-    return this.localeRef.current;
-  }
-  /** Change the active locale. */
+  /**
+   * Set the active locale.
+   *
+   * - Note: Unlike `setMessages`, the locale structure cannot be changed at runtime.
+   */
   setLocale(newLocale) {
     this.localeRef.current = newLocale;
   }
@@ -253,8 +140,17 @@ var BaseTranslator = class {
 // src/translators/core-translator/core-translator.ts
 var CoreTranslator = class extends BaseTranslator {
   constructor(options) {
-    super(options);
+    super({ locale: options.locale, messages: options.messages });
     this.isLoadingRef = { current: false };
+    /** Check if a key exists in the specified locale or current locale. */
+    this.hasKey = (key, targetLocale) => {
+      return hasKey({
+        messagesRef: this.messagesRef,
+        localeRef: this.localeRef,
+        key,
+        targetLocale
+      });
+    };
     this.t = (key, replacements) => {
       return translate({
         messagesRef: this.messagesRef,
@@ -279,12 +175,8 @@ var CoreTranslator = class extends BaseTranslator {
 
 // src/utils/get-full-key.ts
 var getFullKey = (preKey = "", key = "") => {
-  if (!preKey) {
-    return key;
-  }
-  if (!key) {
-    return preKey;
-  }
+  if (!preKey) return key;
+  if (!key) return preKey;
   return `${preKey}.${key}`;
 };
 
@@ -319,4 +211,5 @@ var ScopeTranslator = class extends CoreTranslator {
   }
 };
 
+exports.ScopeTranslator = ScopeTranslator;
 exports.Translator = ScopeTranslator;