intor 2.1.0 → 2.2.0

package/dist/next/server/index.cjs

@@ -50,7 +50,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);
     }
   }
@@ -61,7 +61,7 @@ function getLogger({
 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) => {
@@ -85,56 +85,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();
@@ -165,12 +153,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;
 };
 
@@ -179,8 +167,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;
@@ -191,11 +179,7 @@ var normalizePathname = (rawPathname, options = {}) => {
         hasSlash = true;
       }
     } else {
-      if (hasSlash || result === "") {
-        result += "/" + char;
-      } else {
-        result += char;
-      }
+      result += hasSlash || result === "" ? "/" + char : char;
       hasSlash = false;
     }
   }
@@ -205,42 +189,6 @@ var normalizePathname = (rawPathname, options = {}) => {
   return result || "/";
 };
 
-// src/shared/utils/pathname/extract-pathname.ts
-var extractPathname = ({
-  config,
-  pathname: rawPathname
-}) => {
-  const { routing, defaultLocale } = config;
-  const { basePath, prefix } = routing;
-  const normalizedPathname = normalizePathname(rawPathname);
-  let prefixedPathname = normalizedPathname;
-  if (basePath && normalizedPathname.startsWith(basePath + "/")) {
-    prefixedPathname = normalizedPathname.slice(basePath.length) || "/";
-  } else if (basePath && normalizedPathname === basePath) {
-    prefixedPathname = "/";
-  }
-  const pathParts = prefixedPathname.split("/").filter(Boolean);
-  const maybeLocale = pathParts[0] || "";
-  const isLocalePrefixed = config.supportedLocales?.includes(maybeLocale);
-  let unprefixedPathname = prefixedPathname;
-  if (prefix === "all") {
-    if (isLocalePrefixed) {
-      unprefixedPathname = prefixedPathname.slice(maybeLocale.length + 1) || "/";
-    }
-  } else if (prefix === "except-default") {
-    if (maybeLocale && maybeLocale !== defaultLocale && isLocalePrefixed) {
-      unprefixedPathname = prefixedPathname.slice(maybeLocale.length + 1) || "/";
-    }
-  }
-  return {
-    basePath,
-    prefixedPathname,
-    unprefixedPathname,
-    maybeLocale,
-    isLocalePrefixed: Boolean(isLocalePrefixed)
-  };
-};
-
 // src/shared/utils/pathname/standardize-pathname.ts
 var standardizePathname = ({
   config,
@@ -253,7 +201,7 @@ var standardizePathname = ({
     PREFIX_PLACEHOLDER,
     normalizePathname(pathname)
   ];
-  const standardizedPathname = parts.join("/").replace(/\/{2,}/g, "/");
+  const standardizedPathname = parts.join("/").replaceAll(/\/{2,}/g, "/");
   return normalizePathname(standardizedPathname);
 };
 
@@ -307,21 +255,6 @@ var IntorError = class extends Error {
   }
 };
 
-// src/modules/messages/load-local-messages/utils/read-message-record-file.ts
-var readMessageRecordFile = async (filePath, loggerOptions) => {
-  const fileName = path__default.default.basename(filePath, ".json");
-  const content = await fs__default.default.readFile(filePath, "utf-8");
-  const parsed = JSON.parse(content);
-  if (typeof parsed !== "object" || parsed === null) {
-    throw new IntorError({
-      id: loggerOptions.id,
-      code: "INTOR_INVALID_MESSAGE_FORMAT" /* INVALID_MESSAGE_FORMAT */,
-      message: "Invalid message format"
-    });
-  }
-  return { fileName, content: parsed };
-};
-
 // src/modules/messages/load-local-messages/load-namespace-group/parse-message-file.ts
 var MAX_PATH_LENGTH = 260;
 var parseMessageFile = async (filePath, loggerOptions) => {
@@ -342,9 +275,17 @@ var parseMessageFile = async (filePath, loggerOptions) => {
     return null;
   }
   try {
-    const { content } = await readMessageRecordFile(trimmedPath, loggerOptions);
-    logger.trace(`Message file loaded.`, { filePath: trimmedPath });
-    return content;
+    const content = await fs__default.default.readFile(trimmedPath, "utf8");
+    const parsed = JSON.parse(content);
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new IntorError({
+        id: loggerOptions.id,
+        code: "INTOR_INVALID_MESSAGE_FORMAT" /* INVALID_MESSAGE_FORMAT */,
+        message: "Invalid message format"
+      });
+    }
+    logger.trace("Message file loaded.", { filePath: trimmedPath });
+    return parsed;
   } catch (error) {
     logger.warn("Failed to parse message file.", {
       filePath: trimmedPath,
@@ -438,7 +379,7 @@ var addToNamespaceGroup = ({
   const filePathsSet = new Set(group.filePaths);
   if (!filePathsSet.has(filePath)) {
     filePathsSet.add(filePath);
-    group.filePaths = Array.from(filePathsSet);
+    group.filePaths = [...filePathsSet];
     namespaceGroups.set(nsKey, group);
   }
 };
@@ -448,14 +389,15 @@ var traverseDirectory = async ({
   options,
   currentDirPath,
   namespaceGroups,
-  namespacePathSegments
+  namespacePathSegments,
+  readdir = fs__default.default.readdir
 }) => {
   const { limit } = options;
   const loggerOptions = options.logger || { id: "default" };
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "traverse-directory" });
   try {
-    const dirents = await fs__default.default.readdir(currentDirPath, { withFileTypes: true });
+    const dirents = await readdir(currentDirPath, { withFileTypes: true });
     const dirPromises = dirents.map(
       (dirent) => limit(async () => {
         const filePath = path__default.default.join(currentDirPath, dirent.name);
@@ -471,7 +413,8 @@ var traverseDirectory = async ({
             namespaceGroups,
             currentDirPath: filePath,
             namespacePathSegments: [...namespacePathSegments, dirent.name],
-            options
+            options,
+            readdir
           });
         }
       }).catch((error) => {
@@ -546,7 +489,7 @@ var loadSingleLocale = async ({
     namespaceGroups: [...namespaceGroups.entries()].map(([ns, val]) => ({
       namespace: ns,
       isAtRoot: val.isAtRoot,
-      fileCounts: val.filePaths.length
+      fileCount: val.filePaths.length
     }))
   });
   const namespaceGroupTasks = [...namespaceGroups.entries()].filter(
@@ -577,8 +520,8 @@ var loadLocaleWithFallback = async ({
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-locale-with-fallback" });
-  const localesToTry = [targetLocale, ...fallbackLocales];
-  for (const locale of localesToTry) {
+  const candidateLocales = [targetLocale, ...fallbackLocales];
+  for (const locale of candidateLocales) {
     try {
       const validNamespaces = await loadSingleLocale({
         basePath,
@@ -597,7 +540,7 @@ var loadLocaleWithFallback = async ({
     }
   }
   logger.warn("All fallback locales failed.", {
-    attemptedLocales: localesToTry
+    attemptedLocales: candidateLocales
   });
   return;
 };
@@ -643,8 +586,8 @@ var loadLocalMessages = async ({
     loggerOptions.id,
     resolvedBasePath,
     locale,
-    [...fallbackLocales ?? []].sort().join(","),
-    [...namespaces ?? []].sort().join(",")
+    (fallbackLocales ?? []).toSorted().join(","),
+    (namespaces ?? []).toSorted().join(",")
   ]);
   if (cache.enabled && key) {
     const cached = await pool?.get(key);
@@ -789,8 +732,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);
@@ -852,7 +795,7 @@ var loadMessages = async ({
     );
     return;
   }
-  const { loader } = config;
+  const { id, loader, cache } = config;
   const fallbackLocales = config.fallbackLocales[locale] || [];
   const namespaces = resolveNamespaces({ config, pathname });
   logger.debug("Namespaces ready for loading.", {
@@ -867,8 +810,8 @@ var loadMessages = async ({
       locale,
       fallbackLocales,
       namespaces,
-      cache: config.cache,
-      logger: { id: config.id }
+      cache,
+      logger: { id }
     });
   } else if (loader.type === "api") {
     loadedMessages = await loadApiMessages({
@@ -876,7 +819,7 @@ var loadMessages = async ({
       locale,
       fallbackLocales,
       namespaces,
-      logger: { id: config.id }
+      logger: { id }
     });
   }
   if (!loadedMessages || Object.keys(loadedMessages).length === 0) {
@@ -887,29 +830,23 @@ var loadMessages = async ({
 
 // src/modules/tools/get-translator.ts
 async function getTranslator(opts) {
-  const { config, locale, pathname = "", preKey } = opts;
+  const { config, locale, pathname = "", preKey, handlers } = opts;
   const messages = await loadMessages({ config, locale, pathname });
   const translator = new intorTranslator.Translator({
     locale,
     messages,
     fallbackLocales: config.fallbackLocales,
     loadingMessage: config.translator?.loadingMessage,
-    placeholder: config.translator?.placeholder
+    placeholder: config.translator?.placeholder,
+    handlers
   });
-  const props = {
-    messages,
-    locale
+  const props = { messages, locale };
+  const scoped = translator.scoped(preKey);
+  return {
+    ...props,
+    hasKey: preKey ? scoped.hasKey : translator.hasKey,
+    t: preKey ? scoped.t : translator.t
   };
-  if (preKey) {
-    const scoped = translator.scoped(preKey);
-    return { ...props, ...scoped };
-  } else {
-    return {
-      ...props,
-      t: translator.t,
-      hasKey: translator.hasKey
-    };
-  }
 }
 
 // src/adapters/next/server/get-translator.ts

package/dist/next/server/index.d.cts

@@ -1,5 +1,5 @@
 import { Level, NormalizerConfig, FormatterConfig, LoggerPreset } from 'logry/edge';
-import { Locale, LocaleNamespaceMessages, FallbackLocalesMap, InferTranslatorKey, LocaleKey, Replacement, RichReplacement, NodeKeys, UnionLocaleMessages, ScopedLeafKeys } from 'intor-translator';
+import { Locale, LocaleMessages, FallbackLocalesMap, ScopedLeafKeys, LocalizedLeafKeys, Replacement, LocalizedNodeKeys } from 'intor-translator';
 
 type CookieRawOptions = {
     /** Completely disable cookie usage (no read, no write, no lookup by name) - default: false */
@@ -109,7 +109,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;
@@ -121,20 +121,34 @@ type IntorResolvedConfig = (WithLoader | WithoutLoader) & {
 
 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"];
 
 interface I18nContext {
     locale: GenLocale;
@@ -146,24 +160,37 @@ interface I18nContext {
  *
  * Next.js adapter implementation: uses `next/headers` and `next/cookies`.
  */
-declare const getI18nContext: (config: IntorResolvedConfig) => Promise<I18nContext>;
+declare const getI18nContext: <CK extends string = "__default__">(config: IntorResolvedConfig) => Promise<I18nContext>;
 
-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>;
 
 /**
@@ -175,7 +202,7 @@ type ScopedTranslatorInstance<M, K extends string> = {
  * - Supports optional `preKey` to create a scoped translator for nested translation keys.
  * - Allows passing additional `TranslateConfig` options to the underlying translator.
  */
-declare function getTranslator<C extends GenConfigKeys = "__default__">(config: IntorResolvedConfig): Promise<TranslatorInstance<GenMessages<C>>>;
-declare function getTranslator<C extends GenConfigKeys = "__default__", K extends PreKey<C> = PreKey<C>>(config: IntorResolvedConfig, preKey?: K): Promise<ScopedTranslatorInstance<GenMessages<C>, K>>;
+declare function getTranslator<CK extends GenConfigKeys = "__default__">(config: IntorResolvedConfig): Promise<TranslatorInstance<GenMessages<CK>>>;
+declare function getTranslator<CK extends GenConfigKeys = "__default__", PK extends string = LocalizedNodeKeys<GenMessages<CK>>>(config: IntorResolvedConfig, preKey: IfGen<PK, string>): Promise<TranslatorInstance<GenMessages<CK>, PK>>;
 
 export { getI18nContext, getTranslator };

package/dist/next/server/index.d.ts

@@ -1,5 +1,5 @@
 import { Level, NormalizerConfig, FormatterConfig, LoggerPreset } from 'logry/edge';
-import { Locale, LocaleNamespaceMessages, FallbackLocalesMap, InferTranslatorKey, LocaleKey, Replacement, RichReplacement, NodeKeys, UnionLocaleMessages, ScopedLeafKeys } from 'intor-translator';
+import { Locale, LocaleMessages, FallbackLocalesMap, ScopedLeafKeys, LocalizedLeafKeys, Replacement, LocalizedNodeKeys } from 'intor-translator';
 
 type CookieRawOptions = {
     /** Completely disable cookie usage (no read, no write, no lookup by name) - default: false */
@@ -109,7 +109,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;
@@ -121,20 +121,34 @@ type IntorResolvedConfig = (WithLoader | WithoutLoader) & {
 
 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"];
 
 interface I18nContext {
     locale: GenLocale;
@@ -146,24 +160,37 @@ interface I18nContext {
  *
  * Next.js adapter implementation: uses `next/headers` and `next/cookies`.
  */
-declare const getI18nContext: (config: IntorResolvedConfig) => Promise<I18nContext>;
+declare const getI18nContext: <CK extends string = "__default__">(config: IntorResolvedConfig) => Promise<I18nContext>;
 
-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>;
 
 /**
@@ -175,7 +202,7 @@ type ScopedTranslatorInstance<M, K extends string> = {
  * - Supports optional `preKey` to create a scoped translator for nested translation keys.
  * - Allows passing additional `TranslateConfig` options to the underlying translator.
  */
-declare function getTranslator<C extends GenConfigKeys = "__default__">(config: IntorResolvedConfig): Promise<TranslatorInstance<GenMessages<C>>>;
-declare function getTranslator<C extends GenConfigKeys = "__default__", K extends PreKey<C> = PreKey<C>>(config: IntorResolvedConfig, preKey?: K): Promise<ScopedTranslatorInstance<GenMessages<C>, K>>;
+declare function getTranslator<CK extends GenConfigKeys = "__default__">(config: IntorResolvedConfig): Promise<TranslatorInstance<GenMessages<CK>>>;
+declare function getTranslator<CK extends GenConfigKeys = "__default__", PK extends string = LocalizedNodeKeys<GenMessages<CK>>>(config: IntorResolvedConfig, preKey: IfGen<PK, string>): Promise<TranslatorInstance<GenMessages<CK>, PK>>;
 
 export { getI18nContext, getTranslator };