intor 2.2.2 → 2.2.4

package/dist/index.cjs

@@ -137,11 +137,11 @@ async function collectFileEntries({
   return results;
 }
 
-// src/modules/messages/shared/utils/is-namespace-messages.ts
+// src/modules/messages/shared/utils/is-valid-messages.ts
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isNamespaceMessages(value) {
+function isValidMessages(value) {
   if (!isPlainObject(value)) return false;
   const stack = [value];
   while (stack.length > 0) {
@@ -157,22 +157,17 @@ function isNamespaceMessages(value) {
   }
   return true;
 }
-
-// src/modules/messages/load-local-messages/read-locale-messages/parse-file-entries/utils/json-reader.ts
 async function jsonReader(filePath, readFile = fs__default.default.readFile) {
   const raw = await readFile(filePath, "utf8");
   const parsed = JSON.parse(raw);
-  if (!isNamespaceMessages(parsed)) {
-    throw new Error("JSON file does not match NamespaceMessages structure");
-  }
   return parsed;
 }
 
 // src/modules/messages/load-local-messages/read-locale-messages/parse-file-entries/utils/nest-object-from-path.ts
-function nestObjectFromPath(path4, value) {
+function nestObjectFromPath(path5, value) {
   let obj = value;
-  for (let i = path4.length - 1; i >= 0; i--) {
-    obj = { [path4[i]]: obj };
+  for (let i = path5.length - 1; i >= 0; i--) {
+    obj = { [path5[i]]: obj };
   }
   return obj;
 }
@@ -181,7 +176,7 @@ function nestObjectFromPath(path4, value) {
 async function parseFileEntries({
   fileEntries,
   limit,
-  extraOptions: { messageFileReader, loggerOptions } = {}
+  extraOptions: { messagesReader, loggerOptions } = {}
 }) {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "parse-file-entries" });
@@ -190,11 +185,17 @@ async function parseFileEntries({
     ({ namespace, segments, basename, fullPath }) => limit(async () => {
       try {
         const segsWithoutNs = segments.slice(1);
-        const json = await (messageFileReader ? messageFileReader(fullPath) : jsonReader(fullPath));
+        const ext = path__default.default.extname(fullPath);
+        const json = ext !== ".json" && messagesReader ? await messagesReader(fullPath) : await jsonReader(fullPath);
+        if (!isValidMessages(json)) {
+          throw new Error(
+            "JSON file does not match NamespaceMessages structure"
+          );
+        }
         const isIndex = basename === "index";
         const keyPath = isIndex ? segsWithoutNs.slice(0, -1) : segsWithoutNs;
-        const namespaceMessages = nestObjectFromPath(keyPath, json);
-        parsedFileEntries.push({ namespace, namespaceMessages });
+        const nested = nestObjectFromPath(keyPath, json);
+        parsedFileEntries.push({ namespace, messages: nested });
         logger.trace("Parsed file.", { path: fullPath });
       } catch (error) {
         logger.error("Failed to read or parse file.", {
@@ -206,13 +207,13 @@ async function parseFileEntries({
   );
   await Promise.all(tasks);
   const result = {};
-  for (const { namespace, namespaceMessages } of parsedFileEntries) {
+  for (const { namespace, messages } of parsedFileEntries) {
     if (namespace === "index") {
-      merge__default.default(result, namespaceMessages);
+      merge__default.default(result, messages);
     } else {
       result[namespace] = merge__default.default(
         result[namespace] ?? {},
-        namespaceMessages
+        messages
       );
     }
   }
@@ -225,7 +226,7 @@ var readLocaleMessages = async ({
   rootDir = "messages",
   locale,
   namespaces,
-  extraOptions: { exts, messageFileReader, loggerOptions } = {}
+  extraOptions: { exts, messagesReader, loggerOptions } = {}
 }) => {
   const fileEntries = await collectFileEntries({
     rootDir: path__default.default.resolve(process.cwd(), rootDir, locale),
@@ -236,7 +237,7 @@ var readLocaleMessages = async ({
   const namespaceMessages = await parseFileEntries({
     fileEntries,
     limit,
-    extraOptions: { messageFileReader, loggerOptions }
+    extraOptions: { messagesReader, loggerOptions }
   });
   const localeMessages = { [locale]: namespaceMessages };
   return localeMessages;
@@ -454,8 +455,9 @@ var loadLocalMessages = async ({
     cacheOptions = DEFAULT_CACHE_OPTIONS,
     loggerOptions = { id: "default" },
     exts,
-    messageFileReader
-  } = {}
+    messagesReader
+  } = {},
+  allowCacheWrite = false
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-local-messages" });
@@ -489,7 +491,7 @@ var loadLocalMessages = async ({
         rootDir,
         locale: candidateLocale,
         namespaces,
-        extraOptions: { loggerOptions, exts, messageFileReader }
+        extraOptions: { loggerOptions, exts, messagesReader }
       });
       if (result && Object.values(result[candidateLocale] || {}).length > 0) {
         messages = result;
@@ -502,7 +504,7 @@ var loadLocalMessages = async ({
       });
     }
   }
-  if (cacheOptions.enabled && key && messages) {
+  if (allowCacheWrite && cacheOptions.enabled && key && messages) {
     await pool?.set(key, messages, cacheOptions.ttl);
   }
   const end = perf_hooks.performance.now();
@@ -541,7 +543,7 @@ var fetchLocaleMessages = async ({
       throw new Error(`HTTP error ${response.status} ${response.statusText}`);
     }
     const data = await response.json();
-    if (!isNamespaceMessages(data[locale])) {
+    if (!isValidMessages(data[locale])) {
       throw new Error("JSON file does not match NamespaceMessages structure");
     }
     return data;
@@ -586,7 +588,8 @@ var loadRemoteMessages = async ({
   extraOptions: {
     cacheOptions = DEFAULT_CACHE_OPTIONS,
     loggerOptions = { id: "default" }
-  } = {}
+  } = {},
+  allowCacheWrite
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-remote-messages" });
@@ -630,7 +633,7 @@ var loadRemoteMessages = async ({
       });
     }
   }
-  if (cacheOptions.enabled && key && messages) {
+  if (allowCacheWrite && cacheOptions.enabled && key && messages) {
     await pool?.set(key, messages, cacheOptions.ttl);
   }
   const end = performance.now();
@@ -647,7 +650,8 @@ var loadMessages = async ({
   config,
   locale,
   pathname = "",
-  extraOptions: { exts, messageFileReader } = {}
+  extraOptions: { exts, messagesReader } = {},
+  allowCacheWrite = false
 }) => {
   const baseLogger = getLogger({ id: config.id, ...config.logger });
   const logger = baseLogger.child({ scope: "load-messages" });
@@ -683,8 +687,9 @@ var loadMessages = async ({
         cacheOptions: config.cache,
         loggerOptions: { id: config.id, ...config.logger },
         exts,
-        messageFileReader
-      }
+        messagesReader
+      },
+      allowCacheWrite
     });
   } else if (type === "remote") {
     loadedMessages = await loadRemoteMessages({
@@ -728,8 +733,9 @@ var intor = async (config, i18nContext, loadMessagesOptions = {}) => {
       pathname,
       extraOptions: {
         exts: loadMessagesOptions.exts,
-        messageFileReader: loadMessagesOptions.messageFileReader
-      }
+        messagesReader: loadMessagesOptions.messagesReader
+      },
+      allowCacheWrite: true
     });
   }
   const mergedMessages = mergeMessages(messages, loadedMessages);

package/dist/index.d.cts

@@ -165,8 +165,44 @@ interface IntorResult {
     messages: LocaleMessages;
 }
 
-type NamespaceMessages = Record<string, NestedMessage>;
-type MessageFileReader = (filePath: string) => Promise<NamespaceMessages>;
+/**
+ * Represents a collection of localized messages.
+ *
+ * - Each key is a namespace or message identifier, and the value is a
+ * `NestedMessage` object that can contain nested message structures.
+ *
+ * @example
+ * ```ts
+ * const messages: Messages = {
+ *   ui: {
+ *     greeting: "Hello",
+ *     farewell: "Goodbye"
+ *   },
+ *   errors: {
+ *     network: "Network error occurred"
+ *   }
+ * };
+ * ```
+ */
+type Messages = Record<string, NestedMessage>;
+/**
+ * A function that reads messages from a given file path.
+ *
+ * - This function is expected to return a `Promise` that resolves to a `Messages` object.
+ * - It can be implemented to support different file formats such as JSON, YAML, or others.
+ *
+ * @param filePath - The path to the message file to read.
+ * @returns A Promise that resolves to a `Messages` object.
+ *
+ * @example
+ * ```ts
+ * const reader: MessagesReader = async (filePath) => {
+ *   const content = await fs.promises.readFile(filePath, "utf-8");
+ *   return JSON.parse(content) as Messages;
+ * };
+ * ```
+ */
+type MessagesReader = (filePath: string) => Promise<Messages>;
 
 type LoadMessagesOptions = {
     config: IntorResolvedConfig;
@@ -174,8 +210,9 @@ type LoadMessagesOptions = {
     pathname?: string;
     extraOptions?: {
         exts?: string[];
-        messageFileReader?: MessageFileReader;
+        messagesReader?: MessagesReader;
     };
+    allowCacheWrite?: boolean;
 };
 type LoadMessagesResult<C extends GenConfigKeys = "__default__"> = Promise<GenMessages<C> | undefined>;
 
@@ -187,7 +224,7 @@ type LoadMessagesResult<C extends GenConfigKeys = "__default__"> = Promise<GenMe
  * - Apply fallback locales if needed.
  * - Cache messages if enabled (handled by underlying loader, not this function directly).
  */
-declare const loadMessages: <C extends GenConfigKeys = "__default__">({ config, locale, pathname, extraOptions: { exts, messageFileReader }, }: LoadMessagesOptions) => LoadMessagesResult<C>;
+declare const loadMessages: <C extends GenConfigKeys = "__default__">({ config, locale, pathname, extraOptions: { exts, messagesReader }, allowCacheWrite, }: LoadMessagesOptions) => LoadMessagesResult<C>;
 
 /**
  * Global messages pool (cross-module + hot-reload safe)
@@ -215,8 +252,9 @@ interface LoadLocalMessagesOptions {
             id?: string;
         };
         exts?: string[];
-        messageFileReader?: MessageFileReader;
+        messagesReader?: MessagesReader;
     };
+    allowCacheWrite?: boolean;
 }
 
 /**
@@ -227,7 +265,7 @@ interface LoadLocalMessagesOptions {
  * - Cache messages if enabled.
  * - Limit concurrent file reads for performance.
  */
-declare const loadLocalMessages: ({ pool, rootDir, locale, fallbackLocales, namespaces, extraOptions: { concurrency, cacheOptions, loggerOptions, exts, messageFileReader, }, }: LoadLocalMessagesOptions) => Promise<LocaleMessages | undefined>;
+declare const loadLocalMessages: ({ pool, rootDir, locale, fallbackLocales, namespaces, extraOptions: { concurrency, cacheOptions, loggerOptions, exts, messagesReader, }, allowCacheWrite, }: LoadLocalMessagesOptions) => Promise<LocaleMessages | undefined>;
 
 interface LoadRemoteMessagesOptions {
     pool?: MessagesPool;
@@ -243,6 +281,7 @@ interface LoadRemoteMessagesOptions {
             id?: string;
         };
     };
+    allowCacheWrite?: boolean;
 }
 
 /**
@@ -251,7 +290,7 @@ interface LoadRemoteMessagesOptions {
  * - Fetch messages for a target locale with optional fallback locales.
  * - Cache messages if enabled.
  */
-declare const loadRemoteMessages: ({ pool, rootDir, remoteUrl, remoteHeaders, locale, fallbackLocales, namespaces, extraOptions: { cacheOptions, loggerOptions, }, }: LoadRemoteMessagesOptions) => Promise<LocaleMessages | undefined>;
+declare const loadRemoteMessages: ({ pool, rootDir, remoteUrl, remoteHeaders, locale, fallbackLocales, namespaces, extraOptions: { cacheOptions, loggerOptions, }, allowCacheWrite, }: LoadRemoteMessagesOptions) => Promise<LocaleMessages | undefined>;
 
 /**
  * Entry point for initializing Intor.
@@ -262,7 +301,7 @@ declare const loadRemoteMessages: ({ pool, rootDir, remoteUrl, remoteHeaders, lo
  */
 declare const intor: (config: IntorResolvedConfig, i18nContext: GetI18nContext | Partial<I18nContext>, loadMessagesOptions?: {
     exts?: string[];
-    messageFileReader?: MessageFileReader;
+    messagesReader?: MessagesReader;
 }) => Promise<IntorResult>;
 
 /** Base properties shared by all translator instances. */
@@ -416,4 +455,4 @@ declare global {
  */
 declare function clearLoggerPool(): void;
 
-export { type I18nContext, type IntorResult, type LoadLocalMessagesOptions, type LoadRemoteMessagesOptions, type MessageFileReader, type NamespaceMessages, PREFIX_PLACEHOLDER, clearLoggerPool, clearMessagesPool, extractPathname, getTranslator, intor, loadLocalMessages, loadMessages, loadRemoteMessages, mergeMessages, normalizeCacheKey, normalizeLocale, normalizePathname, resolveNamespaces, resolvePreferredLocale, standardizePathname };
+export { type I18nContext, type IntorResult, type LoadLocalMessagesOptions, type LoadRemoteMessagesOptions, type Messages, type MessagesReader, PREFIX_PLACEHOLDER, clearLoggerPool, clearMessagesPool, extractPathname, getTranslator, intor, loadLocalMessages, loadMessages, loadRemoteMessages, mergeMessages, normalizeCacheKey, normalizeLocale, normalizePathname, resolveNamespaces, resolvePreferredLocale, standardizePathname };

package/dist/index.d.ts

@@ -165,8 +165,44 @@ interface IntorResult {
     messages: LocaleMessages;
 }
 
-type NamespaceMessages = Record<string, NestedMessage>;
-type MessageFileReader = (filePath: string) => Promise<NamespaceMessages>;
+/**
+ * Represents a collection of localized messages.
+ *
+ * - Each key is a namespace or message identifier, and the value is a
+ * `NestedMessage` object that can contain nested message structures.
+ *
+ * @example
+ * ```ts
+ * const messages: Messages = {
+ *   ui: {
+ *     greeting: "Hello",
+ *     farewell: "Goodbye"
+ *   },
+ *   errors: {
+ *     network: "Network error occurred"
+ *   }
+ * };
+ * ```
+ */
+type Messages = Record<string, NestedMessage>;
+/**
+ * A function that reads messages from a given file path.
+ *
+ * - This function is expected to return a `Promise` that resolves to a `Messages` object.
+ * - It can be implemented to support different file formats such as JSON, YAML, or others.
+ *
+ * @param filePath - The path to the message file to read.
+ * @returns A Promise that resolves to a `Messages` object.
+ *
+ * @example
+ * ```ts
+ * const reader: MessagesReader = async (filePath) => {
+ *   const content = await fs.promises.readFile(filePath, "utf-8");
+ *   return JSON.parse(content) as Messages;
+ * };
+ * ```
+ */
+type MessagesReader = (filePath: string) => Promise<Messages>;
 
 type LoadMessagesOptions = {
     config: IntorResolvedConfig;
@@ -174,8 +210,9 @@ type LoadMessagesOptions = {
     pathname?: string;
     extraOptions?: {
         exts?: string[];
-        messageFileReader?: MessageFileReader;
+        messagesReader?: MessagesReader;
     };
+    allowCacheWrite?: boolean;
 };
 type LoadMessagesResult<C extends GenConfigKeys = "__default__"> = Promise<GenMessages<C> | undefined>;
 
@@ -187,7 +224,7 @@ type LoadMessagesResult<C extends GenConfigKeys = "__default__"> = Promise<GenMe
  * - Apply fallback locales if needed.
  * - Cache messages if enabled (handled by underlying loader, not this function directly).
  */
-declare const loadMessages: <C extends GenConfigKeys = "__default__">({ config, locale, pathname, extraOptions: { exts, messageFileReader }, }: LoadMessagesOptions) => LoadMessagesResult<C>;
+declare const loadMessages: <C extends GenConfigKeys = "__default__">({ config, locale, pathname, extraOptions: { exts, messagesReader }, allowCacheWrite, }: LoadMessagesOptions) => LoadMessagesResult<C>;
 
 /**
  * Global messages pool (cross-module + hot-reload safe)
@@ -215,8 +252,9 @@ interface LoadLocalMessagesOptions {
             id?: string;
         };
         exts?: string[];
-        messageFileReader?: MessageFileReader;
+        messagesReader?: MessagesReader;
     };
+    allowCacheWrite?: boolean;
 }
 
 /**
@@ -227,7 +265,7 @@ interface LoadLocalMessagesOptions {
  * - Cache messages if enabled.
  * - Limit concurrent file reads for performance.
  */
-declare const loadLocalMessages: ({ pool, rootDir, locale, fallbackLocales, namespaces, extraOptions: { concurrency, cacheOptions, loggerOptions, exts, messageFileReader, }, }: LoadLocalMessagesOptions) => Promise<LocaleMessages | undefined>;
+declare const loadLocalMessages: ({ pool, rootDir, locale, fallbackLocales, namespaces, extraOptions: { concurrency, cacheOptions, loggerOptions, exts, messagesReader, }, allowCacheWrite, }: LoadLocalMessagesOptions) => Promise<LocaleMessages | undefined>;
 
 interface LoadRemoteMessagesOptions {
     pool?: MessagesPool;
@@ -243,6 +281,7 @@ interface LoadRemoteMessagesOptions {
             id?: string;
         };
     };
+    allowCacheWrite?: boolean;
 }
 
 /**
@@ -251,7 +290,7 @@ interface LoadRemoteMessagesOptions {
  * - Fetch messages for a target locale with optional fallback locales.
  * - Cache messages if enabled.
  */
-declare const loadRemoteMessages: ({ pool, rootDir, remoteUrl, remoteHeaders, locale, fallbackLocales, namespaces, extraOptions: { cacheOptions, loggerOptions, }, }: LoadRemoteMessagesOptions) => Promise<LocaleMessages | undefined>;
+declare const loadRemoteMessages: ({ pool, rootDir, remoteUrl, remoteHeaders, locale, fallbackLocales, namespaces, extraOptions: { cacheOptions, loggerOptions, }, allowCacheWrite, }: LoadRemoteMessagesOptions) => Promise<LocaleMessages | undefined>;
 
 /**
  * Entry point for initializing Intor.
@@ -262,7 +301,7 @@ declare const loadRemoteMessages: ({ pool, rootDir, remoteUrl, remoteHeaders, lo
  */
 declare const intor: (config: IntorResolvedConfig, i18nContext: GetI18nContext | Partial<I18nContext>, loadMessagesOptions?: {
     exts?: string[];
-    messageFileReader?: MessageFileReader;
+    messagesReader?: MessagesReader;
 }) => Promise<IntorResult>;
 
 /** Base properties shared by all translator instances. */
@@ -416,4 +455,4 @@ declare global {
  */
 declare function clearLoggerPool(): void;
 
-export { type I18nContext, type IntorResult, type LoadLocalMessagesOptions, type LoadRemoteMessagesOptions, type MessageFileReader, type NamespaceMessages, PREFIX_PLACEHOLDER, clearLoggerPool, clearMessagesPool, extractPathname, getTranslator, intor, loadLocalMessages, loadMessages, loadRemoteMessages, mergeMessages, normalizeCacheKey, normalizeLocale, normalizePathname, resolveNamespaces, resolvePreferredLocale, standardizePathname };
+export { type I18nContext, type IntorResult, type LoadLocalMessagesOptions, type LoadRemoteMessagesOptions, type Messages, type MessagesReader, PREFIX_PLACEHOLDER, clearLoggerPool, clearMessagesPool, extractPathname, getTranslator, intor, loadLocalMessages, loadMessages, loadRemoteMessages, mergeMessages, normalizeCacheKey, normalizeLocale, normalizePathname, resolveNamespaces, resolvePreferredLocale, standardizePathname };

package/dist/index.js

@@ -128,11 +128,11 @@ async function collectFileEntries({
   return results;
 }
 
-// src/modules/messages/shared/utils/is-namespace-messages.ts
+// src/modules/messages/shared/utils/is-valid-messages.ts
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isNamespaceMessages(value) {
+function isValidMessages(value) {
   if (!isPlainObject(value)) return false;
   const stack = [value];
   while (stack.length > 0) {
@@ -148,22 +148,17 @@ function isNamespaceMessages(value) {
   }
   return true;
 }
-
-// src/modules/messages/load-local-messages/read-locale-messages/parse-file-entries/utils/json-reader.ts
 async function jsonReader(filePath, readFile = fs.readFile) {
   const raw = await readFile(filePath, "utf8");
   const parsed = JSON.parse(raw);
-  if (!isNamespaceMessages(parsed)) {
-    throw new Error("JSON file does not match NamespaceMessages structure");
-  }
   return parsed;
 }
 
 // src/modules/messages/load-local-messages/read-locale-messages/parse-file-entries/utils/nest-object-from-path.ts
-function nestObjectFromPath(path4, value) {
+function nestObjectFromPath(path5, value) {
   let obj = value;
-  for (let i = path4.length - 1; i >= 0; i--) {
-    obj = { [path4[i]]: obj };
+  for (let i = path5.length - 1; i >= 0; i--) {
+    obj = { [path5[i]]: obj };
   }
   return obj;
 }
@@ -172,7 +167,7 @@ function nestObjectFromPath(path4, value) {
 async function parseFileEntries({
   fileEntries,
   limit,
-  extraOptions: { messageFileReader, loggerOptions } = {}
+  extraOptions: { messagesReader, loggerOptions } = {}
 }) {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "parse-file-entries" });
@@ -181,11 +176,17 @@ async function parseFileEntries({
     ({ namespace, segments, basename, fullPath }) => limit(async () => {
       try {
         const segsWithoutNs = segments.slice(1);
-        const json = await (messageFileReader ? messageFileReader(fullPath) : jsonReader(fullPath));
+        const ext = path.extname(fullPath);
+        const json = ext !== ".json" && messagesReader ? await messagesReader(fullPath) : await jsonReader(fullPath);
+        if (!isValidMessages(json)) {
+          throw new Error(
+            "JSON file does not match NamespaceMessages structure"
+          );
+        }
         const isIndex = basename === "index";
         const keyPath = isIndex ? segsWithoutNs.slice(0, -1) : segsWithoutNs;
-        const namespaceMessages = nestObjectFromPath(keyPath, json);
-        parsedFileEntries.push({ namespace, namespaceMessages });
+        const nested = nestObjectFromPath(keyPath, json);
+        parsedFileEntries.push({ namespace, messages: nested });
         logger.trace("Parsed file.", { path: fullPath });
       } catch (error) {
         logger.error("Failed to read or parse file.", {
@@ -197,13 +198,13 @@ async function parseFileEntries({
   );
   await Promise.all(tasks);
   const result = {};
-  for (const { namespace, namespaceMessages } of parsedFileEntries) {
+  for (const { namespace, messages } of parsedFileEntries) {
     if (namespace === "index") {
-      merge(result, namespaceMessages);
+      merge(result, messages);
     } else {
       result[namespace] = merge(
         result[namespace] ?? {},
-        namespaceMessages
+        messages
       );
     }
   }
@@ -216,7 +217,7 @@ var readLocaleMessages = async ({
   rootDir = "messages",
   locale,
   namespaces,
-  extraOptions: { exts, messageFileReader, loggerOptions } = {}
+  extraOptions: { exts, messagesReader, loggerOptions } = {}
 }) => {
   const fileEntries = await collectFileEntries({
     rootDir: path.resolve(process.cwd(), rootDir, locale),
@@ -227,7 +228,7 @@ var readLocaleMessages = async ({
   const namespaceMessages = await parseFileEntries({
     fileEntries,
     limit,
-    extraOptions: { messageFileReader, loggerOptions }
+    extraOptions: { messagesReader, loggerOptions }
   });
   const localeMessages = { [locale]: namespaceMessages };
   return localeMessages;
@@ -445,8 +446,9 @@ var loadLocalMessages = async ({
     cacheOptions = DEFAULT_CACHE_OPTIONS,
     loggerOptions = { id: "default" },
     exts,
-    messageFileReader
-  } = {}
+    messagesReader
+  } = {},
+  allowCacheWrite = false
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-local-messages" });
@@ -480,7 +482,7 @@ var loadLocalMessages = async ({
         rootDir,
         locale: candidateLocale,
         namespaces,
-        extraOptions: { loggerOptions, exts, messageFileReader }
+        extraOptions: { loggerOptions, exts, messagesReader }
       });
       if (result && Object.values(result[candidateLocale] || {}).length > 0) {
         messages = result;
@@ -493,7 +495,7 @@ var loadLocalMessages = async ({
       });
     }
   }
-  if (cacheOptions.enabled && key && messages) {
+  if (allowCacheWrite && cacheOptions.enabled && key && messages) {
     await pool?.set(key, messages, cacheOptions.ttl);
   }
   const end = performance$1.now();
@@ -532,7 +534,7 @@ var fetchLocaleMessages = async ({
       throw new Error(`HTTP error ${response.status} ${response.statusText}`);
     }
     const data = await response.json();
-    if (!isNamespaceMessages(data[locale])) {
+    if (!isValidMessages(data[locale])) {
       throw new Error("JSON file does not match NamespaceMessages structure");
     }
     return data;
@@ -577,7 +579,8 @@ var loadRemoteMessages = async ({
   extraOptions: {
     cacheOptions = DEFAULT_CACHE_OPTIONS,
     loggerOptions = { id: "default" }
-  } = {}
+  } = {},
+  allowCacheWrite
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-remote-messages" });
@@ -621,7 +624,7 @@ var loadRemoteMessages = async ({
       });
     }
   }
-  if (cacheOptions.enabled && key && messages) {
+  if (allowCacheWrite && cacheOptions.enabled && key && messages) {
     await pool?.set(key, messages, cacheOptions.ttl);
   }
   const end = performance.now();
@@ -638,7 +641,8 @@ var loadMessages = async ({
   config,
   locale,
   pathname = "",
-  extraOptions: { exts, messageFileReader } = {}
+  extraOptions: { exts, messagesReader } = {},
+  allowCacheWrite = false
 }) => {
   const baseLogger = getLogger({ id: config.id, ...config.logger });
   const logger = baseLogger.child({ scope: "load-messages" });
@@ -674,8 +678,9 @@ var loadMessages = async ({
         cacheOptions: config.cache,
         loggerOptions: { id: config.id, ...config.logger },
         exts,
-        messageFileReader
-      }
+        messagesReader
+      },
+      allowCacheWrite
     });
   } else if (type === "remote") {
     loadedMessages = await loadRemoteMessages({
@@ -719,8 +724,9 @@ var intor = async (config, i18nContext, loadMessagesOptions = {}) => {
       pathname,
       extraOptions: {
         exts: loadMessagesOptions.exts,
-        messageFileReader: loadMessagesOptions.messageFileReader
-      }
+        messagesReader: loadMessagesOptions.messagesReader
+      },
+      allowCacheWrite: true
     });
   }
   const mergedMessages = mergeMessages(messages, loadedMessages);

package/dist/next/index.cjs

@@ -96,11 +96,11 @@ function getLogger({
   return logger;
 }
 
-// src/modules/messages/shared/utils/is-namespace-messages.ts
+// src/modules/messages/shared/utils/is-valid-messages.ts
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isNamespaceMessages(value) {
+function isValidMessages(value) {
   if (!isPlainObject(value)) return false;
   const stack = [value];
   while (stack.length > 0) {
@@ -340,7 +340,7 @@ var fetchLocaleMessages = async ({
       throw new Error(`HTTP error ${response.status} ${response.statusText}`);
     }
     const data = await response.json();
-    if (!isNamespaceMessages(data[locale])) {
+    if (!isValidMessages(data[locale])) {
       throw new Error("JSON file does not match NamespaceMessages structure");
     }
     return data;
@@ -385,7 +385,8 @@ var loadRemoteMessages = async ({
   extraOptions: {
     cacheOptions = DEFAULT_CACHE_OPTIONS,
     loggerOptions = { id: "default" }
-  } = {}
+  } = {},
+  allowCacheWrite
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-remote-messages" });
@@ -429,7 +430,7 @@ var loadRemoteMessages = async ({
       });
     }
   }
-  if (cacheOptions.enabled && key && messages) {
+  if (allowCacheWrite && cacheOptions.enabled && key && messages) {
     await pool?.set(key, messages, cacheOptions.ttl);
   }
   const end = performance.now();

package/dist/next/index.js

@@ -69,11 +69,11 @@ function getLogger({
   return logger;
 }
 
-// src/modules/messages/shared/utils/is-namespace-messages.ts
+// src/modules/messages/shared/utils/is-valid-messages.ts
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isNamespaceMessages(value) {
+function isValidMessages(value) {
   if (!isPlainObject(value)) return false;
   const stack = [value];
   while (stack.length > 0) {
@@ -313,7 +313,7 @@ var fetchLocaleMessages = async ({
       throw new Error(`HTTP error ${response.status} ${response.statusText}`);
     }
     const data = await response.json();
-    if (!isNamespaceMessages(data[locale])) {
+    if (!isValidMessages(data[locale])) {
       throw new Error("JSON file does not match NamespaceMessages structure");
     }
     return data;
@@ -358,7 +358,8 @@ var loadRemoteMessages = async ({
   extraOptions: {
     cacheOptions = DEFAULT_CACHE_OPTIONS,
     loggerOptions = { id: "default" }
-  } = {}
+  } = {},
+  allowCacheWrite
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-remote-messages" });
@@ -402,7 +403,7 @@ var loadRemoteMessages = async ({
       });
     }
   }
-  if (cacheOptions.enabled && key && messages) {
+  if (allowCacheWrite && cacheOptions.enabled && key && messages) {
     await pool?.set(key, messages, cacheOptions.ttl);
   }
   const end = performance.now();

package/dist/next/server/index.cjs

@@ -309,11 +309,11 @@ async function collectFileEntries({
   return results;
 }
 
-// src/modules/messages/shared/utils/is-namespace-messages.ts
+// src/modules/messages/shared/utils/is-valid-messages.ts
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isNamespaceMessages(value) {
+function isValidMessages(value) {
   if (!isPlainObject(value)) return false;
   const stack = [value];
   while (stack.length > 0) {
@@ -329,22 +329,17 @@ function isNamespaceMessages(value) {
   }
   return true;
 }
-
-// src/modules/messages/load-local-messages/read-locale-messages/parse-file-entries/utils/json-reader.ts
 async function jsonReader(filePath, readFile = fs__default.default.readFile) {
   const raw = await readFile(filePath, "utf8");
   const parsed = JSON.parse(raw);
-  if (!isNamespaceMessages(parsed)) {
-    throw new Error("JSON file does not match NamespaceMessages structure");
-  }
   return parsed;
 }
 
 // src/modules/messages/load-local-messages/read-locale-messages/parse-file-entries/utils/nest-object-from-path.ts
-function nestObjectFromPath(path4, value) {
+function nestObjectFromPath(path5, value) {
   let obj = value;
-  for (let i = path4.length - 1; i >= 0; i--) {
-    obj = { [path4[i]]: obj };
+  for (let i = path5.length - 1; i >= 0; i--) {
+    obj = { [path5[i]]: obj };
   }
   return obj;
 }
@@ -353,7 +348,7 @@ function nestObjectFromPath(path4, value) {
 async function parseFileEntries({
   fileEntries,
   limit,
-  extraOptions: { messageFileReader, loggerOptions } = {}
+  extraOptions: { messagesReader, loggerOptions } = {}
 }) {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "parse-file-entries" });
@@ -362,11 +357,17 @@ async function parseFileEntries({
     ({ namespace, segments, basename, fullPath }) => limit(async () => {
       try {
         const segsWithoutNs = segments.slice(1);
-        const json = await (messageFileReader ? messageFileReader(fullPath) : jsonReader(fullPath));
+        const ext = path__default.default.extname(fullPath);
+        const json = ext !== ".json" && messagesReader ? await messagesReader(fullPath) : await jsonReader(fullPath);
+        if (!isValidMessages(json)) {
+          throw new Error(
+            "JSON file does not match NamespaceMessages structure"
+          );
+        }
         const isIndex = basename === "index";
         const keyPath = isIndex ? segsWithoutNs.slice(0, -1) : segsWithoutNs;
-        const namespaceMessages = nestObjectFromPath(keyPath, json);
-        parsedFileEntries.push({ namespace, namespaceMessages });
+        const nested = nestObjectFromPath(keyPath, json);
+        parsedFileEntries.push({ namespace, messages: nested });
         logger.trace("Parsed file.", { path: fullPath });
       } catch (error) {
         logger.error("Failed to read or parse file.", {
@@ -378,13 +379,13 @@ async function parseFileEntries({
   );
   await Promise.all(tasks);
   const result = {};
-  for (const { namespace, namespaceMessages } of parsedFileEntries) {
+  for (const { namespace, messages } of parsedFileEntries) {
     if (namespace === "index") {
-      merge__default.default(result, namespaceMessages);
+      merge__default.default(result, messages);
     } else {
       result[namespace] = merge__default.default(
         result[namespace] ?? {},
-        namespaceMessages
+        messages
       );
     }
   }
@@ -397,7 +398,7 @@ var readLocaleMessages = async ({
   rootDir = "messages",
   locale,
   namespaces,
-  extraOptions: { exts, messageFileReader, loggerOptions } = {}
+  extraOptions: { exts, messagesReader, loggerOptions } = {}
 }) => {
   const fileEntries = await collectFileEntries({
     rootDir: path__default.default.resolve(process.cwd(), rootDir, locale),
@@ -408,7 +409,7 @@ var readLocaleMessages = async ({
   const namespaceMessages = await parseFileEntries({
     fileEntries,
     limit,
-    extraOptions: { messageFileReader, loggerOptions }
+    extraOptions: { messagesReader, loggerOptions }
   });
   const localeMessages = { [locale]: namespaceMessages };
   return localeMessages;
@@ -432,8 +433,9 @@ var loadLocalMessages = async ({
     cacheOptions = DEFAULT_CACHE_OPTIONS,
     loggerOptions = { id: "default" },
     exts,
-    messageFileReader
-  } = {}
+    messagesReader
+  } = {},
+  allowCacheWrite = false
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-local-messages" });
@@ -467,7 +469,7 @@ var loadLocalMessages = async ({
         rootDir,
         locale: candidateLocale,
         namespaces,
-        extraOptions: { loggerOptions, exts, messageFileReader }
+        extraOptions: { loggerOptions, exts, messagesReader }
       });
       if (result && Object.values(result[candidateLocale] || {}).length > 0) {
         messages = result;
@@ -480,7 +482,7 @@ var loadLocalMessages = async ({
       });
     }
   }
-  if (cacheOptions.enabled && key && messages) {
+  if (allowCacheWrite && cacheOptions.enabled && key && messages) {
     await pool?.set(key, messages, cacheOptions.ttl);
   }
   const end = perf_hooks.performance.now();
@@ -519,7 +521,7 @@ var fetchLocaleMessages = async ({
       throw new Error(`HTTP error ${response.status} ${response.statusText}`);
     }
     const data = await response.json();
-    if (!isNamespaceMessages(data[locale])) {
+    if (!isValidMessages(data[locale])) {
       throw new Error("JSON file does not match NamespaceMessages structure");
     }
     return data;
@@ -564,7 +566,8 @@ var loadRemoteMessages = async ({
   extraOptions: {
     cacheOptions = DEFAULT_CACHE_OPTIONS,
     loggerOptions = { id: "default" }
-  } = {}
+  } = {},
+  allowCacheWrite
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-remote-messages" });
@@ -608,7 +611,7 @@ var loadRemoteMessages = async ({
       });
     }
   }
-  if (cacheOptions.enabled && key && messages) {
+  if (allowCacheWrite && cacheOptions.enabled && key && messages) {
     await pool?.set(key, messages, cacheOptions.ttl);
   }
   const end = performance.now();
@@ -625,7 +628,8 @@ var loadMessages = async ({
   config,
   locale,
   pathname = "",
-  extraOptions: { exts, messageFileReader } = {}
+  extraOptions: { exts, messagesReader } = {},
+  allowCacheWrite = false
 }) => {
   const baseLogger = getLogger({ id: config.id, ...config.logger });
   const logger = baseLogger.child({ scope: "load-messages" });
@@ -661,8 +665,9 @@ var loadMessages = async ({
         cacheOptions: config.cache,
         loggerOptions: { id: config.id, ...config.logger },
         exts,
-        messageFileReader
-      }
+        messagesReader
+      },
+      allowCacheWrite
     });
   } else if (type === "remote") {
     loadedMessages = await loadRemoteMessages({

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

@@ -160,7 +160,7 @@ interface I18nContext {
  *
  * Next.js adapter implementation: uses `next/headers` and `next/cookies`.
  */
-declare const getI18nContext: <CK extends string = "__default__">(config: IntorResolvedConfig) => Promise<I18nContext>;
+declare const getI18nContext: <CK extends GenConfigKeys = "__default__">(config: IntorResolvedConfig) => Promise<I18nContext>;
 
 /** Base properties shared by all translator instances. */
 interface TranslatorBaseProps<M = unknown> {

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

@@ -160,7 +160,7 @@ interface I18nContext {
  *
  * Next.js adapter implementation: uses `next/headers` and `next/cookies`.
  */
-declare const getI18nContext: <CK extends string = "__default__">(config: IntorResolvedConfig) => Promise<I18nContext>;
+declare const getI18nContext: <CK extends GenConfigKeys = "__default__">(config: IntorResolvedConfig) => Promise<I18nContext>;
 
 /** Base properties shared by all translator instances. */
 interface TranslatorBaseProps<M = unknown> {

package/dist/next/server/index.js

@@ -299,11 +299,11 @@ async function collectFileEntries({
   return results;
 }
 
-// src/modules/messages/shared/utils/is-namespace-messages.ts
+// src/modules/messages/shared/utils/is-valid-messages.ts
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isNamespaceMessages(value) {
+function isValidMessages(value) {
   if (!isPlainObject(value)) return false;
   const stack = [value];
   while (stack.length > 0) {
@@ -319,22 +319,17 @@ function isNamespaceMessages(value) {
   }
   return true;
 }
-
-// src/modules/messages/load-local-messages/read-locale-messages/parse-file-entries/utils/json-reader.ts
 async function jsonReader(filePath, readFile = fs.readFile) {
   const raw = await readFile(filePath, "utf8");
   const parsed = JSON.parse(raw);
-  if (!isNamespaceMessages(parsed)) {
-    throw new Error("JSON file does not match NamespaceMessages structure");
-  }
   return parsed;
 }
 
 // src/modules/messages/load-local-messages/read-locale-messages/parse-file-entries/utils/nest-object-from-path.ts
-function nestObjectFromPath(path4, value) {
+function nestObjectFromPath(path5, value) {
   let obj = value;
-  for (let i = path4.length - 1; i >= 0; i--) {
-    obj = { [path4[i]]: obj };
+  for (let i = path5.length - 1; i >= 0; i--) {
+    obj = { [path5[i]]: obj };
   }
   return obj;
 }
@@ -343,7 +338,7 @@ function nestObjectFromPath(path4, value) {
 async function parseFileEntries({
   fileEntries,
   limit,
-  extraOptions: { messageFileReader, loggerOptions } = {}
+  extraOptions: { messagesReader, loggerOptions } = {}
 }) {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "parse-file-entries" });
@@ -352,11 +347,17 @@ async function parseFileEntries({
     ({ namespace, segments, basename, fullPath }) => limit(async () => {
       try {
         const segsWithoutNs = segments.slice(1);
-        const json = await (messageFileReader ? messageFileReader(fullPath) : jsonReader(fullPath));
+        const ext = path.extname(fullPath);
+        const json = ext !== ".json" && messagesReader ? await messagesReader(fullPath) : await jsonReader(fullPath);
+        if (!isValidMessages(json)) {
+          throw new Error(
+            "JSON file does not match NamespaceMessages structure"
+          );
+        }
         const isIndex = basename === "index";
         const keyPath = isIndex ? segsWithoutNs.slice(0, -1) : segsWithoutNs;
-        const namespaceMessages = nestObjectFromPath(keyPath, json);
-        parsedFileEntries.push({ namespace, namespaceMessages });
+        const nested = nestObjectFromPath(keyPath, json);
+        parsedFileEntries.push({ namespace, messages: nested });
         logger.trace("Parsed file.", { path: fullPath });
       } catch (error) {
         logger.error("Failed to read or parse file.", {
@@ -368,13 +369,13 @@ async function parseFileEntries({
   );
   await Promise.all(tasks);
   const result = {};
-  for (const { namespace, namespaceMessages } of parsedFileEntries) {
+  for (const { namespace, messages } of parsedFileEntries) {
     if (namespace === "index") {
-      merge(result, namespaceMessages);
+      merge(result, messages);
     } else {
       result[namespace] = merge(
         result[namespace] ?? {},
-        namespaceMessages
+        messages
       );
     }
   }
@@ -387,7 +388,7 @@ var readLocaleMessages = async ({
   rootDir = "messages",
   locale,
   namespaces,
-  extraOptions: { exts, messageFileReader, loggerOptions } = {}
+  extraOptions: { exts, messagesReader, loggerOptions } = {}
 }) => {
   const fileEntries = await collectFileEntries({
     rootDir: path.resolve(process.cwd(), rootDir, locale),
@@ -398,7 +399,7 @@ var readLocaleMessages = async ({
   const namespaceMessages = await parseFileEntries({
     fileEntries,
     limit,
-    extraOptions: { messageFileReader, loggerOptions }
+    extraOptions: { messagesReader, loggerOptions }
   });
   const localeMessages = { [locale]: namespaceMessages };
   return localeMessages;
@@ -422,8 +423,9 @@ var loadLocalMessages = async ({
     cacheOptions = DEFAULT_CACHE_OPTIONS,
     loggerOptions = { id: "default" },
     exts,
-    messageFileReader
-  } = {}
+    messagesReader
+  } = {},
+  allowCacheWrite = false
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-local-messages" });
@@ -457,7 +459,7 @@ var loadLocalMessages = async ({
         rootDir,
         locale: candidateLocale,
         namespaces,
-        extraOptions: { loggerOptions, exts, messageFileReader }
+        extraOptions: { loggerOptions, exts, messagesReader }
       });
       if (result && Object.values(result[candidateLocale] || {}).length > 0) {
         messages = result;
@@ -470,7 +472,7 @@ var loadLocalMessages = async ({
       });
     }
   }
-  if (cacheOptions.enabled && key && messages) {
+  if (allowCacheWrite && cacheOptions.enabled && key && messages) {
     await pool?.set(key, messages, cacheOptions.ttl);
   }
   const end = performance$1.now();
@@ -509,7 +511,7 @@ var fetchLocaleMessages = async ({
       throw new Error(`HTTP error ${response.status} ${response.statusText}`);
     }
     const data = await response.json();
-    if (!isNamespaceMessages(data[locale])) {
+    if (!isValidMessages(data[locale])) {
       throw new Error("JSON file does not match NamespaceMessages structure");
     }
     return data;
@@ -554,7 +556,8 @@ var loadRemoteMessages = async ({
   extraOptions: {
     cacheOptions = DEFAULT_CACHE_OPTIONS,
     loggerOptions = { id: "default" }
-  } = {}
+  } = {},
+  allowCacheWrite
 }) => {
   const baseLogger = getLogger({ ...loggerOptions });
   const logger = baseLogger.child({ scope: "load-remote-messages" });
@@ -598,7 +601,7 @@ var loadRemoteMessages = async ({
       });
     }
   }
-  if (cacheOptions.enabled && key && messages) {
+  if (allowCacheWrite && cacheOptions.enabled && key && messages) {
     await pool?.set(key, messages, cacheOptions.ttl);
   }
   const end = performance.now();
@@ -615,7 +618,8 @@ var loadMessages = async ({
   config,
   locale,
   pathname = "",
-  extraOptions: { exts, messageFileReader } = {}
+  extraOptions: { exts, messagesReader } = {},
+  allowCacheWrite = false
 }) => {
   const baseLogger = getLogger({ id: config.id, ...config.logger });
   const logger = baseLogger.child({ scope: "load-messages" });
@@ -651,8 +655,9 @@ var loadMessages = async ({
         cacheOptions: config.cache,
         loggerOptions: { id: config.id, ...config.logger },
         exts,
-        messageFileReader
-      }
+        messagesReader
+      },
+      allowCacheWrite
     });
   } else if (type === "remote") {
     loadedMessages = await loadRemoteMessages({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intor",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "A modular and extensible i18n core designed for TypeScript and JavaScript projects. Intor enables custom translation logic with support for both frontend and backend environments, featuring runtime configuration, caching, adapters, and message loaders.",
   "author": "Yiming Liao",
   "license": "MIT",
@@ -77,6 +77,7 @@
     "p-limit": "^6.2.0"
   },
   "devDependencies": {
+    "@intor/cli": "../@intor:cli",
     "@types/lodash.merge": "^4.6.9",
     "@types/node": "^24.10.1",
     "@types/react": "^19.1.4",
@@ -94,6 +95,8 @@
     "prettier": "^3.5.3",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "remark": "^15.0.1",
+    "remark-gfm": "^4.0.1",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.32.1",