intor 2.1.0 → 2.2.0

package/dist/next/index.cjs

@@ -4,8 +4,8 @@ var React7 = require('react');
 var logry = require('logry');
 var Keyv = require('keyv');
 var intorTranslator = require('intor-translator');
-var NextLink = require('next/link');
 var formatUrl = require('next/dist/shared/lib/router/utils/format-url');
+var NextLink = require('next/link');
 var navigation = require('next/navigation');
 var headers = require('next/headers');
 
@@ -48,66 +48,6 @@ function useConfig() {
   return context;
 }
 var LocaleContext = React7__namespace.createContext(void 0);
-
-// src/adapters/next/shared/utils/build-cookie-string.ts
-var buildCookieString = (cookie, locale) => {
-  const parts = [];
-  parts.push(`${cookie.name}=${encodeURIComponent(locale)}`);
-  if (cookie.maxAge) {
-    const expires = new Date(Date.now() + cookie.maxAge * 1e3).toUTCString();
-    parts.push(`expires=${expires}`);
-    parts.push(`max-age=${cookie.maxAge}`);
-  }
-  parts.push(`path=${cookie.path ?? "/"}`);
-  if (cookie.domain) {
-    parts.push(`domain=${cookie.domain}`);
-  }
-  if (cookie.sameSite) {
-    parts.push(
-      `SameSite=${cookie.sameSite[0].toUpperCase()}${cookie.sameSite.slice(1).toLowerCase()}`
-    );
-  }
-  if (cookie.secure !== false) {
-    parts.push(`Secure`);
-  }
-  return parts.join("; ");
-};
-
-// src/adapters/next/shared/utils/set-locale-cookie-browser.ts
-var setLocaleCookieBrowser = ({
-  cookie,
-  locale
-}) => {
-  if (typeof window === "undefined") return;
-  if (cookie.disabled || !cookie.autoSetCookie) return;
-  const cookieString = buildCookieString(cookie, locale);
-  document.cookie = cookieString;
-};
-
-// src/adapters/next/contexts/locale/utils/change-locale.ts
-var changeLocale = ({
-  currentLocale,
-  newLocale,
-  loaderOptions,
-  cookie,
-  setLocale,
-  refetchMessages
-}) => {
-  if (typeof document === "undefined") return;
-  const loaderType = loaderOptions?.type;
-  if (newLocale === currentLocale) return;
-  if (loaderType === "import") {
-    console.warn(
-      `[Intor] You are using dynamic import to switch languages. Please make sure to use the wrapped <Link> component to trigger a page reload, ensuring that the translation data is dynamically updated.`
-    );
-  }
-  setLocale(newLocale);
-  setLocaleCookieBrowser({ cookie, locale: newLocale });
-  document.documentElement.lang = newLocale;
-  if (loaderType === "api" && refetchMessages) {
-    void refetchMessages(newLocale);
-  }
-};
 var MessagesContext = React7__namespace.createContext(void 0);
 
 // src/modules/config/constants/cache.constants.ts
@@ -146,7 +86,7 @@ function getLogger({
     });
     pool.set(id, logger);
     if (pool.size > 1e3) {
-      const keys = Array.from(pool.keys());
+      const keys = [...pool.keys()];
       for (const key of keys.slice(0, 200)) pool.delete(key);
     }
   }
@@ -161,7 +101,7 @@ function getGlobalMessagesPool() {
 
 // src/shared/utils/merge-messages.ts
 var mergeMessages = (staticMessages = {}, loadedMessages = {}) => {
-  const result = Object.keys(staticMessages).length ? { ...staticMessages } : {};
+  const result = Object.keys(staticMessages).length > 0 ? { ...staticMessages } : {};
   for (const locale in loadedMessages) {
     const loaded = loadedMessages[locale];
     if (!result[locale]) {
@@ -180,7 +120,7 @@ var mergeMessages = (staticMessages = {}, loadedMessages = {}) => {
 var CACHE_KEY_DELIMITER = "|";
 var sanitize = (k) => k.replaceAll(/[\u200B-\u200D\uFEFF]/g, "").replaceAll(/[\r\n]/g, "").trim();
 var normalizeCacheKey = (key, delimiter = CACHE_KEY_DELIMITER) => {
-  if (!key) return null;
+  if (key === null || key === void 0) return null;
   if (Array.isArray(key)) {
     if (key.length === 0) return null;
     const normalized = key.map((k) => {
@@ -204,56 +144,44 @@ var resolveNamespaces = ({
   pathname
 }) => {
   const { loader } = config;
-  const {
-    routeNamespaces = {},
-    namespaces: fallbackNamespaces
-  } = loader;
-  const { unprefixedPathname } = extractPathname({ config, pathname });
-  const standardizedPathname = standardizePathname({
-    config,
-    pathname: unprefixedPathname
-  });
+  const { routeNamespaces = {}, namespaces } = loader || {};
+  const standardizedPathname = standardizePathname({ config, pathname });
   const placeholderRemovedPathname = standardizedPathname.replace(
     `/${PREFIX_PLACEHOLDER}`,
     ""
   );
-  const defaultNamespaces = routeNamespaces.default ?? [];
-  const exactMatchNamespaces = routeNamespaces[standardizedPathname] ?? routeNamespaces[placeholderRemovedPathname];
-  if (exactMatchNamespaces) {
-    return [...defaultNamespaces, ...exactMatchNamespaces];
-  }
-  let bestMatch = "";
-  let bestNamespaces;
+  const collected = [
+    ...routeNamespaces.default || [],
+    // default
+    ...namespaces || [],
+    // default
+    ...routeNamespaces[standardizedPathname] || [],
+    // exact match
+    ...routeNamespaces[placeholderRemovedPathname] || []
+    // exact match
+  ];
   const prefixPatterns = Object.keys(routeNamespaces).filter(
     (pattern) => pattern.endsWith("/*")
   );
   for (const pattern of prefixPatterns) {
     const basePath = pattern.replace(/\/\*$/, "");
-    if (standardizedPathname.startsWith(basePath)) {
-      if (basePath.length > bestMatch.length) {
-        bestMatch = basePath;
-        bestNamespaces = routeNamespaces[pattern];
-      }
+    if (standardizedPathname.startsWith(basePath) || placeholderRemovedPathname.startsWith(basePath)) {
+      collected.push(...routeNamespaces[pattern] || []);
     }
   }
-  const matchedNamespaces = bestNamespaces ?? routeNamespaces["/*"] ?? fallbackNamespaces ?? [];
-  if (matchedNamespaces.length > 0) {
-    return [...defaultNamespaces, ...matchedNamespaces];
-  } else {
-    return [...defaultNamespaces];
-  }
+  return [...new Set(collected)];
 };
 
 // src/shared/utils/locale/normalize-locale.ts
+var toCanonical = (input) => {
+  try {
+    return Intl.getCanonicalLocales(input)[0]?.toLowerCase();
+  } catch {
+    return;
+  }
+};
 var normalizeLocale = (locale = "", supportedLocales = []) => {
   if (!locale || supportedLocales.length === 0) return;
-  const toCanonical = (input) => {
-    try {
-      return Intl.getCanonicalLocales(input)[0]?.toLowerCase();
-    } catch {
-      return;
-    }
-  };
   const canonicalLocale = toCanonical(locale);
   if (!canonicalLocale) return;
   const supportedCanonicalMap = /* @__PURE__ */ new Map();
@@ -284,12 +212,12 @@ var resolvePreferredLocale = (acceptLanguageHeader, supportedLocales) => {
   const supportedLocalesSet = new Set(supportedLocales);
   const preferred = acceptLanguageHeader.split(",").map((part) => {
     const [lang, qValue] = part.split(";");
-    const q = qValue ? parseFloat(qValue.split("=")[1]) : 1;
-    if (isNaN(q)) {
+    const q = qValue ? Number.parseFloat(qValue.split("=")[1]) : 1;
+    if (Number.isNaN(q)) {
       return { lang: lang.trim(), q: 0 };
     }
     return { lang: lang.trim(), q };
-  }).sort((a, b) => b.q - a.q).find(({ lang }) => supportedLocalesSet.has(lang))?.lang;
+  }).toSorted((a, b) => b.q - a.q).find(({ lang }) => supportedLocalesSet.has(lang))?.lang;
   return preferred;
 };
 
@@ -298,8 +226,8 @@ var normalizePathname = (rawPathname, options = {}) => {
   const length = rawPathname.length;
   let start = 0;
   let end = length - 1;
-  while (start <= end && rawPathname.charCodeAt(start) <= 32) start++;
-  while (end >= start && rawPathname.charCodeAt(end) <= 32) end--;
+  while (start <= end && (rawPathname.codePointAt(start) ?? 0) <= 32) start++;
+  while (end >= start && (rawPathname.codePointAt(end) ?? 0) <= 32) end--;
   if (start > end) return "/";
   let result = "";
   let hasSlash = false;
@@ -310,11 +238,7 @@ var normalizePathname = (rawPathname, options = {}) => {
         hasSlash = true;
       }
     } else {
-      if (hasSlash || result === "") {
-        result += "/" + char;
-      } else {
-        result += char;
-      }
+      result += hasSlash || result === "" ? "/" + char : char;
       hasSlash = false;
     }
   }
@@ -338,8 +262,8 @@ var extractPathname = ({
   } else if (basePath && normalizedPathname === basePath) {
     prefixedPathname = "/";
   }
-  const pathParts = prefixedPathname.split("/").filter(Boolean);
-  const maybeLocale = pathParts[0] || "";
+  const pathPart = prefixedPathname.split("/").find(Boolean);
+  const maybeLocale = pathPart || "";
   const isLocalePrefixed = config.supportedLocales?.includes(maybeLocale);
   let unprefixedPathname = prefixedPathname;
   if (prefix === "all") {
@@ -372,7 +296,7 @@ var standardizePathname = ({
     PREFIX_PLACEHOLDER,
     normalizePathname(pathname)
   ];
-  const standardizedPathname = parts.join("/").replace(/\/{2,}/g, "/");
+  const standardizedPathname = parts.join("/").replaceAll(/\/{2,}/g, "/");
   return normalizePathname(standardizedPathname);
 };
 
@@ -484,8 +408,8 @@ var loadApiMessages = async ({
     loggerOptions.id,
     basePath,
     locale,
-    [...fallbackLocales ?? []].sort().join(","),
-    [...namespaces ?? []].sort().join(",")
+    (fallbackLocales ?? []).toSorted().join(","),
+    (namespaces ?? []).toSorted().join(",")
   ]);
   if (cache.enabled && key) {
     const cached = await pool?.get(key);
@@ -606,6 +530,8 @@ function useMessages() {
     throw new Error("useMessages must be used within a MessagesProvider");
   return context;
 }
+
+// src/adapters/next/contexts/locale/utils/use-init-lazy-load.ts
 var useInitLazyLoad = ({
   loaderOptions,
   currentLocale
@@ -620,6 +546,41 @@ var useInitLazyLoad = ({
     }
   }, [lazyLoad, currentLocale, refetchMessages, isFirstLoadedRef]);
 };
+
+// src/adapters/next/shared/utils/build-cookie-string.ts
+var buildCookieString = (cookie, locale) => {
+  const parts = [`${cookie.name}=${encodeURIComponent(locale)}`];
+  if (cookie.maxAge) {
+    const expires = new Date(Date.now() + cookie.maxAge * 1e3).toUTCString();
+    parts.push(`expires=${expires}`, `max-age=${cookie.maxAge}`);
+  }
+  parts.push(`path=${cookie.path ?? "/"}`);
+  if (cookie.domain) {
+    parts.push(`domain=${cookie.domain}`);
+  }
+  if (cookie.sameSite) {
+    parts.push(
+      `SameSite=${cookie.sameSite[0].toUpperCase()}${cookie.sameSite.slice(1).toLowerCase()}`
+    );
+  }
+  if (cookie.secure !== false) {
+    parts.push(`Secure`);
+  }
+  return parts.join("; ");
+};
+
+// src/adapters/next/shared/utils/set-locale-cookie-browser.ts
+var setLocaleCookieBrowser = ({
+  cookie,
+  locale
+}) => {
+  if (globalThis.window === void 0) return;
+  if (cookie.disabled || !cookie.autoSetCookie) return;
+  const cookieString = buildCookieString(cookie, locale);
+  document.cookie = cookieString;
+};
+
+// src/adapters/next/contexts/locale/utils/use-init-locale-cookie.ts
 var useInitLocaleCookie = ({
   config,
   locale
@@ -637,6 +598,31 @@ var useInitLocaleCookie = ({
   }, []);
 };
 
+// src/adapters/next/contexts/locale/utils/change-locale.ts
+var changeLocale = ({
+  currentLocale,
+  newLocale,
+  loaderOptions,
+  cookie,
+  setLocale,
+  refetchMessages
+}) => {
+  if (typeof document === "undefined") return;
+  const loaderType = loaderOptions?.type;
+  if (newLocale === currentLocale) return;
+  if (loaderType === "import") {
+    console.warn(
+      `[Intor] You are using dynamic import to switch languages. Please make sure to use the wrapped <Link> component to trigger a page reload, ensuring that the translation data is dynamically updated.`
+    );
+  }
+  setLocale(newLocale);
+  setLocaleCookieBrowser({ cookie, locale: newLocale });
+  document.documentElement.lang = newLocale;
+  if (loaderType === "api" && refetchMessages) {
+    void refetchMessages(newLocale);
+  }
+};
+
 // src/adapters/next/contexts/locale/provider.tsx
 function LocaleProvider({
   value: { initialLocale },
@@ -735,7 +721,7 @@ function useTranslator() {
   const context = React7__namespace.useContext(TranslatorContext);
   if (!context)
     throw new Error(
-      "useIntorTranslator must be used within IntorTranslatorProvider"
+      "useTranslator must be used within IntorTranslatorProvider"
     );
   return context;
 }
@@ -758,13 +744,12 @@ function useTranslator2(preKey) {
     isLoading: translator.isLoading,
     setLocale
   };
-  if (preKey) {
-    const { hasKey, t } = translator.scoped(preKey);
-    return { ...props, hasKey, t };
-  } else {
-    const { hasKey, t } = translator;
-    return { ...props, hasKey, t };
-  }
+  const scoped = translator.scoped(preKey);
+  return {
+    ...props,
+    hasKey: preKey ? scoped.hasKey : translator.hasKey,
+    t: preKey ? scoped.t : translator.t
+  };
 }
 
 // src/adapters/next/shared/utils/locale-prefix-pathname.ts
@@ -784,15 +769,11 @@ var localePrefixPathname = ({
     );
   }
   if (prefix === "except-default") {
-    if (locale === config.defaultLocale) {
-      return normalizePathname(
-        standardizedPathname.replaceAll(`/${PREFIX_PLACEHOLDER}`, "")
-      );
-    } else {
-      return normalizePathname(
-        standardizedPathname.replaceAll(PREFIX_PLACEHOLDER, locale)
-      );
-    }
+    return locale === config.defaultLocale ? normalizePathname(
+      standardizedPathname.replaceAll(`/${PREFIX_PLACEHOLDER}`, "")
+    ) : normalizePathname(
+      standardizedPathname.replaceAll(PREFIX_PLACEHOLDER, locale)
+    );
   }
   return normalizePathname(
     standardizedPathname.replaceAll(`/${PREFIX_PLACEHOLDER}`, "")
@@ -884,7 +865,7 @@ var useLocaleSwitch = () => {
     if (isExternal) return;
     if (shouldFullReload({ config, targetPathname, locale, currentLocale })) {
       setLocaleCookieBrowser({ cookie: config.cookie, locale: targetLocale });
-      window.location.href = resolvedHref;
+      globalThis.location.href = resolvedHref;
       return;
     } else {
       setLocale(targetLocale);

package/dist/next/index.d.cts

@@ -1,8 +1,8 @@
-import * as React from 'react';
 import { Level, NormalizerConfig, FormatterConfig, LoggerPreset } from 'logry/edge';
-import { Locale, LocaleNamespaceMessages, FallbackLocalesMap, TranslateHandlers, InferTranslatorKey, LocaleKey, Replacement, RichReplacement, NodeKeys, UnionLocaleMessages, ScopedLeafKeys } from 'intor-translator';
-import { LinkProps as LinkProps$1 } from 'next/link';
+import { Locale, LocaleMessages, FallbackLocalesMap, TranslateHandlers, ScopedLeafKeys, LocalizedLeafKeys, Replacement, LocalizedNodeKeys } from 'intor-translator';
+import * as React from 'react';
 import { Url } from 'next/dist/shared/lib/router/router';
+import { LinkProps as LinkProps$1 } from 'next/link';
 import * as next_dist_shared_lib_app_router_context_shared_runtime from 'next/dist/shared/lib/app-router-context.shared-runtime';
 import { NavigateOptions } from 'next/dist/shared/lib/app-router-context.shared-runtime';
 import { RedirectType } from 'next/navigation';
@@ -115,7 +115,7 @@ type WithLoader = {
 };
 type IntorResolvedConfig = (WithLoader | WithoutLoader) & {
     readonly id: string;
-    readonly messages?: LocaleNamespaceMessages;
+    readonly messages?: LocaleMessages;
     readonly defaultLocale: Locale;
     readonly fallbackLocales: FallbackLocalesMap;
     readonly translator?: TranslatorOptions;
@@ -130,7 +130,7 @@ interface IntorProviderProps {
         config: IntorResolvedConfig;
         initialLocale: Locale;
         pathname: string;
-        messages: Readonly<LocaleNamespaceMessages>;
+        messages: Readonly<LocaleMessages>;
     };
     children: React.ReactNode;
 }
@@ -146,37 +146,64 @@ declare const TranslateHandlersProvider: ({ children, handlers, }: TranslateHand
 
 declare const PREFIX_PLACEHOLDER = "{locale}";
 
+/**
+ * Conditional type for generated types.
+ * - Returns `Then` if `IntorGeneratedTypes` exists, otherwise `Else`.
+ */
 type IfGen<Then, Else = never> = IntorGeneratedTypes extends void ? Else : Then;
+/**
+ * Union of all configuration keys.
+ * - Defaults to `string` if `IntorGeneratedTypes` does not exist.
+ */
 type GenConfigKeys = IfGen<keyof IntorGeneratedTypes, string>;
-type GenConfig<C extends GenConfigKeys = "__default__"> = IntorGeneratedTypes extends void ? {
+/**
+ * Configuration shape for a given config key.
+ * - If `IntorGeneratedTypes` is not defined, falls back to default shape.
+ * Otherwise, picks `Locales` and `Messages` according to the key.
+ */
+type GenConfig<CK extends GenConfigKeys = "__default__"> = IntorGeneratedTypes extends void ? {
     Locales: string;
-    Messages: LocaleNamespaceMessages;
-} : C extends keyof IntorGeneratedTypes ? {
-    Locales: IntorGeneratedTypes[C]["Locales"];
+    Messages: LocaleMessages;
+} : CK extends keyof IntorGeneratedTypes ? {
+    Locales: IntorGeneratedTypes[CK]["Locales"];
     Messages: {
-        [K in IntorGeneratedTypes[C]["Locales"]]: IntorGeneratedTypes[C]["Messages"][typeof PREFIX_PLACEHOLDER];
+        [K in IntorGeneratedTypes[CK]["Locales"]]: IntorGeneratedTypes[CK]["Messages"][typeof PREFIX_PLACEHOLDER];
     };
 } : never;
-type GenMessages<C extends GenConfigKeys = "__default__"> = GenConfig<C>["Messages"];
-type GenLocaleFallback = Locale;
-type GenLocale<Config extends string = "__default__"> = Config extends keyof IntorGeneratedTypes ? IntorGeneratedTypes[Config]["Locales"] : GenLocaleFallback;
+/** Extracts messages for a given config key */
+type GenMessages<CK extends GenConfigKeys = "__default__"> = GenConfig<CK>["Messages"];
+/** Extracts locales for a given config key */
+type GenLocale<CK extends GenConfigKeys = "__default__"> = GenConfig<CK>["Locales"];
 
-type PreKey<C extends GenConfigKeys = "__default__"> = NodeKeys<UnionLocaleMessages<GenMessages<C>>>;
-interface TranslatorBaseProps<M> {
+/** Base properties shared by all translator instances. */
+interface TranslatorBaseProps<M = unknown> {
+    /** `messages`: The message object containing all translations. */
     messages: M;
-    locale: LocaleKey<M>;
+    /** Current locale in use. */
+    locale: Locale<M>;
 }
-interface TranslatorClientProps<M> {
+/** Properties specific to client-side translator behavior. */
+interface TranslatorClientProps<M = unknown> {
+    /** `isLoading`: Indicates whether translations are currently loading. */
     isLoading: boolean;
-    setLocale: (locale: LocaleKey<M>) => void;
+    /** `setLocale`: Function to update the current locale. */
+    setLocale: (locale: Locale<M>) => void;
 }
-type TranslatorInstance<M> = {
-    hasKey: (key?: IfGen<InferTranslatorKey<M>, string>, targetLocale?: LocaleKey<M> | undefined) => boolean;
-    t: <Result = string>(key?: IfGen<InferTranslatorKey<M>, string>, replacements?: Replacement | RichReplacement) => Result;
-} & TranslatorBaseProps<M> & TranslatorClientProps<M>;
-type ScopedTranslatorInstance<M, K extends string> = {
-    hasKey: (key?: IfGen<ScopedLeafKeys<M, K> & string, string>, targetLocale?: LocaleKey<M>) => boolean;
-    t: (key?: IfGen<ScopedLeafKeys<M, K> & string, string>, replacements?: Replacement | RichReplacement) => string;
+/**
+ * Conditional key type for TranslatorInstance.
+ * - Resolves to `ScopedLeafKeys` if a pre-key `PK` is provided,
+ * otherwise resolves to `LocalizedLeafKeys`.
+ */
+type Key<M, PK> = IfGen<PK extends string ? ScopedLeafKeys<M, PK> : LocalizedLeafKeys<M>, string>;
+/**
+ * Translator instance type.
+ * Combines base props, client props, and core translation methods.
+ */
+type TranslatorInstance<M, PK extends string | undefined = undefined> = {
+    /** Check if a given key exists in the messages. */
+    hasKey: (key?: Key<M, PK>, targetLocale?: Locale<M>) => boolean;
+    /** Translate a given key into its string representation. */
+    t: <Result = string>(key?: Key<M, PK>, replacements?: Replacement) => Result;
 } & TranslatorBaseProps<M> & TranslatorClientProps<M>;
 
 /**
@@ -186,8 +213,8 @@ type ScopedTranslatorInstance<M, K extends string> = {
  * - Supports optional `preKey` to create a scoped translator for nested keys.
  * - Can accept a generic type parameter `M` to strongly type your messages.
  */
-declare function useTranslator<C extends GenConfigKeys = "__default__">(): TranslatorInstance<GenMessages<C>>;
-declare function useTranslator<C extends GenConfigKeys = "__default__", K extends PreKey<C> = PreKey<C>>(preKey: IfGen<K, string>): ScopedTranslatorInstance<GenMessages<C>, K>;
+declare function useTranslator<CK extends GenConfigKeys = "__default__">(): TranslatorInstance<GenMessages<CK>>;
+declare function useTranslator<CK extends GenConfigKeys = "__default__", PK extends string = LocalizedNodeKeys<GenMessages<CK>>>(preKey: IfGen<PK, string>): TranslatorInstance<GenMessages<CK>, PK>;
 
 interface LinkProps extends Omit<LinkProps$1, "href">, Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
     href?: Url;

package/dist/next/index.d.ts

@@ -1,8 +1,8 @@
-import * as React from 'react';
 import { Level, NormalizerConfig, FormatterConfig, LoggerPreset } from 'logry/edge';
-import { Locale, LocaleNamespaceMessages, FallbackLocalesMap, TranslateHandlers, InferTranslatorKey, LocaleKey, Replacement, RichReplacement, NodeKeys, UnionLocaleMessages, ScopedLeafKeys } from 'intor-translator';
-import { LinkProps as LinkProps$1 } from 'next/link';
+import { Locale, LocaleMessages, FallbackLocalesMap, TranslateHandlers, ScopedLeafKeys, LocalizedLeafKeys, Replacement, LocalizedNodeKeys } from 'intor-translator';
+import * as React from 'react';
 import { Url } from 'next/dist/shared/lib/router/router';
+import { LinkProps as LinkProps$1 } from 'next/link';
 import * as next_dist_shared_lib_app_router_context_shared_runtime from 'next/dist/shared/lib/app-router-context.shared-runtime';
 import { NavigateOptions } from 'next/dist/shared/lib/app-router-context.shared-runtime';
 import { RedirectType } from 'next/navigation';
@@ -115,7 +115,7 @@ type WithLoader = {
 };
 type IntorResolvedConfig = (WithLoader | WithoutLoader) & {
     readonly id: string;
-    readonly messages?: LocaleNamespaceMessages;
+    readonly messages?: LocaleMessages;
     readonly defaultLocale: Locale;
     readonly fallbackLocales: FallbackLocalesMap;
     readonly translator?: TranslatorOptions;
@@ -130,7 +130,7 @@ interface IntorProviderProps {
         config: IntorResolvedConfig;
         initialLocale: Locale;
         pathname: string;
-        messages: Readonly<LocaleNamespaceMessages>;
+        messages: Readonly<LocaleMessages>;
     };
     children: React.ReactNode;
 }
@@ -146,37 +146,64 @@ declare const TranslateHandlersProvider: ({ children, handlers, }: TranslateHand
 
 declare const PREFIX_PLACEHOLDER = "{locale}";
 
+/**
+ * Conditional type for generated types.
+ * - Returns `Then` if `IntorGeneratedTypes` exists, otherwise `Else`.
+ */
 type IfGen<Then, Else = never> = IntorGeneratedTypes extends void ? Else : Then;
+/**
+ * Union of all configuration keys.
+ * - Defaults to `string` if `IntorGeneratedTypes` does not exist.
+ */
 type GenConfigKeys = IfGen<keyof IntorGeneratedTypes, string>;
-type GenConfig<C extends GenConfigKeys = "__default__"> = IntorGeneratedTypes extends void ? {
+/**
+ * Configuration shape for a given config key.
+ * - If `IntorGeneratedTypes` is not defined, falls back to default shape.
+ * Otherwise, picks `Locales` and `Messages` according to the key.
+ */
+type GenConfig<CK extends GenConfigKeys = "__default__"> = IntorGeneratedTypes extends void ? {
     Locales: string;
-    Messages: LocaleNamespaceMessages;
-} : C extends keyof IntorGeneratedTypes ? {
-    Locales: IntorGeneratedTypes[C]["Locales"];
+    Messages: LocaleMessages;
+} : CK extends keyof IntorGeneratedTypes ? {
+    Locales: IntorGeneratedTypes[CK]["Locales"];
     Messages: {
-        [K in IntorGeneratedTypes[C]["Locales"]]: IntorGeneratedTypes[C]["Messages"][typeof PREFIX_PLACEHOLDER];
+        [K in IntorGeneratedTypes[CK]["Locales"]]: IntorGeneratedTypes[CK]["Messages"][typeof PREFIX_PLACEHOLDER];
     };
 } : never;
-type GenMessages<C extends GenConfigKeys = "__default__"> = GenConfig<C>["Messages"];
-type GenLocaleFallback = Locale;
-type GenLocale<Config extends string = "__default__"> = Config extends keyof IntorGeneratedTypes ? IntorGeneratedTypes[Config]["Locales"] : GenLocaleFallback;
+/** Extracts messages for a given config key */
+type GenMessages<CK extends GenConfigKeys = "__default__"> = GenConfig<CK>["Messages"];
+/** Extracts locales for a given config key */
+type GenLocale<CK extends GenConfigKeys = "__default__"> = GenConfig<CK>["Locales"];
 
-type PreKey<C extends GenConfigKeys = "__default__"> = NodeKeys<UnionLocaleMessages<GenMessages<C>>>;
-interface TranslatorBaseProps<M> {
+/** Base properties shared by all translator instances. */
+interface TranslatorBaseProps<M = unknown> {
+    /** `messages`: The message object containing all translations. */
     messages: M;
-    locale: LocaleKey<M>;
+    /** Current locale in use. */
+    locale: Locale<M>;
 }
-interface TranslatorClientProps<M> {
+/** Properties specific to client-side translator behavior. */
+interface TranslatorClientProps<M = unknown> {
+    /** `isLoading`: Indicates whether translations are currently loading. */
     isLoading: boolean;
-    setLocale: (locale: LocaleKey<M>) => void;
+    /** `setLocale`: Function to update the current locale. */
+    setLocale: (locale: Locale<M>) => void;
 }
-type TranslatorInstance<M> = {
-    hasKey: (key?: IfGen<InferTranslatorKey<M>, string>, targetLocale?: LocaleKey<M> | undefined) => boolean;
-    t: <Result = string>(key?: IfGen<InferTranslatorKey<M>, string>, replacements?: Replacement | RichReplacement) => Result;
-} & TranslatorBaseProps<M> & TranslatorClientProps<M>;
-type ScopedTranslatorInstance<M, K extends string> = {
-    hasKey: (key?: IfGen<ScopedLeafKeys<M, K> & string, string>, targetLocale?: LocaleKey<M>) => boolean;
-    t: (key?: IfGen<ScopedLeafKeys<M, K> & string, string>, replacements?: Replacement | RichReplacement) => string;
+/**
+ * Conditional key type for TranslatorInstance.
+ * - Resolves to `ScopedLeafKeys` if a pre-key `PK` is provided,
+ * otherwise resolves to `LocalizedLeafKeys`.
+ */
+type Key<M, PK> = IfGen<PK extends string ? ScopedLeafKeys<M, PK> : LocalizedLeafKeys<M>, string>;
+/**
+ * Translator instance type.
+ * Combines base props, client props, and core translation methods.
+ */
+type TranslatorInstance<M, PK extends string | undefined = undefined> = {
+    /** Check if a given key exists in the messages. */
+    hasKey: (key?: Key<M, PK>, targetLocale?: Locale<M>) => boolean;
+    /** Translate a given key into its string representation. */
+    t: <Result = string>(key?: Key<M, PK>, replacements?: Replacement) => Result;
 } & TranslatorBaseProps<M> & TranslatorClientProps<M>;
 
 /**
@@ -186,8 +213,8 @@ type ScopedTranslatorInstance<M, K extends string> = {
  * - Supports optional `preKey` to create a scoped translator for nested keys.
  * - Can accept a generic type parameter `M` to strongly type your messages.
  */
-declare function useTranslator<C extends GenConfigKeys = "__default__">(): TranslatorInstance<GenMessages<C>>;
-declare function useTranslator<C extends GenConfigKeys = "__default__", K extends PreKey<C> = PreKey<C>>(preKey: IfGen<K, string>): ScopedTranslatorInstance<GenMessages<C>, K>;
+declare function useTranslator<CK extends GenConfigKeys = "__default__">(): TranslatorInstance<GenMessages<CK>>;
+declare function useTranslator<CK extends GenConfigKeys = "__default__", PK extends string = LocalizedNodeKeys<GenMessages<CK>>>(preKey: IfGen<PK, string>): TranslatorInstance<GenMessages<CK>, PK>;
 
 interface LinkProps extends Omit<LinkProps$1, "href">, Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
     href?: Url;