intor 2.3.3 → 2.3.5

package/README.md

@@ -21,3 +21,82 @@ Fast to start, easy to extend, and free from the usual i18n heaviness.
 #### 🍳 Cooking the Intor v2 docs, crafting them to perfection...
 
 </div>
+
+---
+
+Intor separates language translation from semantic rendering.  
+ICU operates at the text-translation layer, while semantic tags  
+are parsed and rendered in a dedicated AST-based rendering phase.
+
+```
+┌──────────────────────────────────────────────┐
+│                Application                   │
+│                                              │
+│  t() / tRich() / <T />                       │
+└───────────────────────────┬──────────────────┘
+                            │
+                            ▼
+┌──────────────────────────────────────────────┐
+│        Translator (Language / Semantic)      │
+│              intor-translator                │
+│                                              │
+│  Responsibilities:                           │
+│  - Resolve message key                       │
+│  - Locale resolution & fallback              │
+│  - Message loading                           │
+│  - Text-level interpolation                  │
+│    • {name}, {count}                         │
+│    • plural / select                         │
+│    • ICU MessageFormat (optional)            │
+│      (ignoreTag: true)                       │
+│                                              │
+│  Output:                                     │
+│  - Translated string                         │
+│  - May still contain <semantic tags>         │
+└───────────────────────────┬──────────────────┘
+                            │
+                            ▼
+┌──────────────────────────────────────────────┐
+│      Semantic Parsing & AST Construction     │
+│                                              │
+│  Responsibilities:                           │
+│  - Tokenize semantic tags                    │
+│    • <b>, <link>, <Component>                │
+│  - Build semantic AST                        │
+│    • TextNode                                │
+│    • TagNode                                 │
+│                                              │
+│  Note:                                       │
+│  - Independent from ICU / formatter          │
+│  - Pure semantic structure                   │
+└───────────────────────────┬──────────────────┘
+                            │
+                            ▼
+┌──────────────────────────────────────────────┐
+│        Semantic Rendering (Renderer)         │
+│                                              │
+│  Responsibilities:                           │
+│  - Traverse semantic AST                     │
+│  - Render TextNode                           │
+│  - Render TagNode                            │
+│                                              │
+│  Renderer decides output type:               │
+│  - string                                    │
+│  - ReactNode                                 │
+│  - Vue / Svelte nodes                        │
+│  - Markdown / CLI output                     │
+│                                              │
+│  Optional extensions:                        │
+│  - Custom tag renderers                      │
+│  - Rich components                           │
+└───────────────────────────┬──────────────────┘
+                            │
+                            ▼
+┌──────────────────────────────────────────────┐
+│                 Final Output                 │
+│                                              │
+│  - Rendered rich content                     │
+│  - Framework-specific result                 │
+│                                              │
+└──────────────────────────────────────────────┘
+```

package/dist/core/export/config/index.js

@@ -0,0 +1 @@
+export { defineIntorConfig } from '../../src/config/define-intor-config.js';

package/dist/core/export/index.js

@@ -0,0 +1,4 @@
+export { PREFIX_PLACEHOLDER } from '../src/shared/constants/prefix-placeholder.js';
+export { localizePathname } from '../src/shared/utils/pathname/localize-pathname.js';
+export { IntorError, IntorErrorCode } from '../src/shared/error/intor-error.js';
+import 'intor-translator';

package/dist/core/export/server/index.js

@@ -0,0 +1,7 @@
+export { intor } from '../../src/server/intor/intor.js';
+export { loadMessages } from '../../src/server/messages/load-messages.js';
+export { isValidMessages } from '../../src/server/messages/shared/utils/is-valid-messages.js';
+export { getTranslator } from '../../src/server/translator/get-translator.js';
+export { clearLoggerPool } from '../../src/server/shared/logger/global-logger-pool.js';
+export { clearMessagesPool, setGlobalMessagesPool } from '../../src/server/shared/messages/global-messages-pool.js';
+export { loadLocalMessagesFromUrl } from '../../src/server/helpers/local-messages-from-url.js';

package/dist/{src → core/src}/config/constants/cookie.constants.js

@@ -1,8 +1,8 @@
 // Default cookie options
 const DEFAULT_COOKIE_OPTIONS = {
     enabled: true,
-    autoSetCookie: true,
-    name: "intor.i18n.locale",
+    persist: true,
+    name: "intor.locale",
     domain: null,
     path: "/",
     maxAge: 60 * 60 * 24 * 365, // 365 days

package/dist/{src → core/src}/config/constants/routing.constants.js

@@ -1,11 +1,17 @@
 // Default routing options
 const DEFAULT_ROUTING_OPTIONS = {
+    locale: {
+        sources: ["path", "query", "cookie", "detected"],
+        queryKey: "locale",
+    },
     prefix: "none",
     firstVisit: {
         localeSource: "browser",
         redirect: true,
+        persist: true,
     },
     basePath: "/",
+    forceFullReload: false,
 };
 
 export { DEFAULT_ROUTING_OPTIONS };

package/dist/{src → core/src}/config/define-intor-config.js

@@ -5,10 +5,24 @@ import { resolveRoutingOptions } from './resolvers/resolve-routing-options.js';
 import { validateDefaultLocale } from './validators/validate-default-locale.js';
 import { validateSupportedLocales } from './validators/validate-supported-locales.js';
 
+/**
+ * Defines and resolves an Intor configuration.
+ *
+ * This is the canonical entry point for transforming a raw configuration
+ * into a fully validated and resolved Intor config.
+ *
+ * Responsibilities:
+ * - Validate required invariants
+ * - Resolve and normalize derived options
+ * - Apply stable defaults
+ *
+ * This function is purely declarative and side-effect free.
+ * It does not create runtime instances or attach dynamic behavior.
+ *
+ * Intended to run once during application initialization.
+ */
 const defineIntorConfig = (config) => {
-    // Generate a random id if config.id is not defined
-    const id = config.id || `ID${Math.random().toString(36).slice(2, 6)}`;
-    // Validaters
+    // Validators
     const supportedLocales = validateSupportedLocales(config);
     const defaultLocale = validateDefaultLocale(config, supportedLocales);
     // Resolvers
@@ -17,7 +31,7 @@ const defineIntorConfig = (config) => {
     const routing = resolveRoutingOptions(config.routing);
     const cache = resolveCacheOptions(config.cache);
     return {
-        id,
+        id: config.id ?? "default",
         messages: config.messages,
         loader: config.loader,
         defaultLocale,

package/dist/core/src/config/resolvers/resolve-cookie-options.js

@@ -0,0 +1,10 @@
+import { DEFAULT_COOKIE_OPTIONS } from '../constants/cookie.constants.js';
+
+const resolveCookieOptions = (cookie = {}) => {
+    return {
+        ...DEFAULT_COOKIE_OPTIONS,
+        ...cookie,
+    };
+};
+
+export { resolveCookieOptions };

package/dist/{src → core/src}/config/resolvers/resolve-fallback-locales.js

@@ -1,3 +1,20 @@
+/**
+ * Resolves and normalizes fallback locale mappings.
+ *
+ * This utility validates the user-defined `fallbackLocales` configuration
+ * against the provided `supportedLocales` list and the configured `defaultLocale`.
+ *
+ * Resolution rules:
+ * - Only locales listed in `supportedLocales` are considered valid fallbacks.
+ * - The literal value `"default"` is always allowed and represents the configured default locale.
+ * - Fallback entries matching `defaultLocale` are treated as valid.
+ * - Invalid fallback locales are ignored and reported via warnings.
+ *
+ * Notes:
+ * - This function is purely defensive and does not throw on invalid input.
+ * - Only validated fallback mappings are included in the returned result.
+ * - Logging is used for diagnostics only and does not affect the output.
+ */
 const resolveFallbackLocales = (config, supportedLocales) => {
     const { defaultLocale, fallbackLocales } = config;
     if (!fallbackLocales || typeof fallbackLocales !== "object") {

package/dist/core/src/config/resolvers/resolve-routing-options.js

@@ -0,0 +1,20 @@
+import { DEFAULT_ROUTING_OPTIONS } from '../constants/routing.constants.js';
+import { normalizePathname } from '../../shared/utils/normalizers/normalize-pathname.js';
+
+const resolveRoutingOptions = (routing = {}) => {
+    return {
+        ...DEFAULT_ROUTING_OPTIONS,
+        ...routing,
+        locale: {
+            ...DEFAULT_ROUTING_OPTIONS.locale,
+            ...routing.locale,
+        },
+        firstVisit: {
+            ...DEFAULT_ROUTING_OPTIONS.firstVisit,
+            ...routing.firstVisit,
+        },
+        basePath: normalizePathname(routing?.basePath || ""),
+    };
+};
+
+export { resolveRoutingOptions };

package/dist/{src → core/src}/config/validators/validate-default-locale.js

@@ -1,5 +1,14 @@
 import { IntorError, IntorErrorCode } from '../../shared/error/intor-error.js';
 
+/**
+ * Validates the configured default locale.
+ *
+ * - Ensures that `defaultLocale` is explicitly defined.
+ * - Ensures that `defaultLocale` is included in `supportedLocales`.
+ *
+ * This validation is part of the configuration initialization phase
+ * and is expected to fail fast when misconfigured.
+ */
 const validateDefaultLocale = (config, supportedLocales) => {
     const { id, defaultLocale } = config;
     // Throw error if defaultLocale is undefined

package/dist/{src → core/src}/config/validators/validate-supported-locales.js

@@ -1,9 +1,14 @@
 import { IntorError, IntorErrorCode } from '../../shared/error/intor-error.js';
 
 /**
- * Validate and resolve supported locales.
- * Throws error if loader is used without supportedLocales.
- * Falls back to message keys if supportedLocales is undefined.
+ * Validates and resolves the list of supported locales.
+ *
+ * - Ensures `supportedLocales` is explicitly provided when a loader is used.
+ * - Falls back to inferring locales from static message keys when no loader
+ *   is configured.
+ *
+ * This validation runs during configuration initialization and is expected
+ * to fail fast when required inputs are missing.
  */
 const validateSupportedLocales = (config) => {
     const { id, loader, supportedLocales } = config;

package/dist/core/src/server/helpers/local-messages-from-url.js

@@ -0,0 +1,48 @@
+import { loadLocalMessages } from '../messages/load-local-messages/load-local-messages.js';
+
+/** Parse a multi-value query parameter into a normalized string array. */
+function parseMultiValueParam(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    const result = values.flatMap((value) => value
+        .split(",")
+        .map((v) => v.trim())
+        .filter(Boolean));
+    return result.length > 0 ? result : undefined;
+}
+/**
+ * Load local locale messages from a URL-based query protocol.
+ *
+ * - A convenience helper for exposing local messages through a URL-accessible interface.
+ *
+ * @example
+ * ```ts
+ * const url = new URL(
+ *   "https://example.com/messages" +
+ *   "?locale=en-US" +
+ *   "&rootDir=./messages" +
+ *   "&namespaces=common" +
+ *   "&namespaces=homepage" +
+ *   "&fallbackLocales=zh-TW"
+ * );
+ *
+ * const messages = await loadLocalMessagesFromUrl(url);
+ * ```
+ */
+async function loadLocalMessagesFromUrl(url, extraOptions) {
+    // Parse query parameters
+    const rootDir = url.searchParams.get("rootDir") ?? "";
+    const locale = url.searchParams.get("locale") ?? "en-US";
+    const namespaces = parseMultiValueParam(url.searchParams.getAll("namespaces"));
+    const fallbackLocales = parseMultiValueParam(url.searchParams.getAll("fallbackLocales"));
+    // Load local messages
+    return loadLocalMessages({
+        rootDir,
+        locale,
+        namespaces,
+        fallbackLocales,
+        extraOptions,
+    });
+}
+
+export { loadLocalMessagesFromUrl };

package/dist/core/src/server/intor/intor.js

@@ -0,0 +1,49 @@
+import { loadMessages } from '../messages/load-messages.js';
+import { getLogger } from '../shared/logger/get-logger.js';
+import { deepMerge } from '../../shared/utils/deep-merge.js';
+
+/**
+ * Entry point for initializing Intor.
+ *
+ * This function orchestrates the initialization flow:
+ *
+ * - Resolves the initial locale using a provided locale resolver
+ * - Loads locale messages if the message loader is enabled
+ * - Returns a fully-initialized Intor result
+ *
+ * This function does not perform routing decisions itself.
+ * Locale resolution is delegated to the provided `getLocale` implementation.
+ */
+const intor = async (config, getLocale, loadMessagesOptions = {}) => {
+    const baseLogger = getLogger({ id: config.id, ...config.logger });
+    const logger = baseLogger.child({ scope: "intor" });
+    logger.info("Start Intor initialization.");
+    // Resolve initial locale
+    const isLocaleFunction = typeof getLocale === "function";
+    const locale = isLocaleFunction
+        ? await getLocale(config)
+        : getLocale || config.defaultLocale;
+    const source = typeof getLocale === "function" ? "resolver" : "static";
+    logger.debug(`Initial locale resolved as "${locale}" via "${source}".`);
+    // Load messages (if enabled)
+    let loadedMessages;
+    if (config.loader) {
+        loadedMessages = await loadMessages({
+            config,
+            locale,
+            extraOptions: {
+                exts: loadMessagesOptions.exts,
+                messagesReader: loadMessagesOptions.messagesReader,
+            },
+            allowCacheWrite: true,
+        });
+    }
+    logger.info("Intor initialized.");
+    return {
+        config,
+        initialLocale: locale,
+        messages: deepMerge(config.messages, loadedMessages) || {},
+    };
+};
+
+export { intor };

package/dist/core/src/server/messages/load-local-messages/load-local-messages.js

@@ -0,0 +1,93 @@
+import path from 'node:path';
+import pLimit from 'p-limit';
+import { DEFAULT_CACHE_OPTIONS } from '../../../config/constants/cache.constants.js';
+import { readLocaleMessages } from './read-locale-messages/read-locale-messages.js';
+import { getLogger } from '../../shared/logger/get-logger.js';
+import { getGlobalMessagesPool } from '../../shared/messages/global-messages-pool.js';
+import { normalizeCacheKey } from '../../../shared/utils/normalizers/normalize-cache-key.js';
+
+/**
+ * Load locale messages from the local file system.
+ *
+ * This function acts as the orchestration layer for local message loading.
+ * It is responsible for:
+ *
+ * - Resolving fallback locales in order
+ * - Coordinating cache read / write behavior
+ * - Limiting concurrent file reads for performance
+ *
+ * File system traversal, parsing, and message validation are delegated to lower-level utilities.
+ */
+const loadLocalMessages = async ({ pool = getGlobalMessagesPool(), rootDir = "messages", locale, fallbackLocales, namespaces, extraOptions: { concurrency = 10, cacheOptions = DEFAULT_CACHE_OPTIONS, loggerOptions = { id: "default" }, exts, messagesReader, } = {}, allowCacheWrite = false, }) => {
+    const baseLogger = getLogger({ ...loggerOptions });
+    const logger = baseLogger.child({ scope: "load-local-messages" });
+    const start = performance.now();
+    logger.debug("Loading local messages.", {
+        rootDir,
+        resolvedRootDir: path.resolve(process.cwd(), rootDir),
+    });
+    // --- Cache key
+    const cacheKey = normalizeCacheKey([
+        loggerOptions.id,
+        "loaderType:local",
+        rootDir,
+        locale,
+        (fallbackLocales || []).toSorted().join(","),
+        (namespaces || []).toSorted().join(","),
+    ]);
+    // --- Cache read --------------------------------------------------
+    if (cacheOptions.enabled && cacheKey) {
+        const cached = await pool?.get(cacheKey);
+        if (cached) {
+            logger.debug("Messages cache hit.", { key: cacheKey });
+            return cached;
+        }
+    }
+    const limit = pLimit(concurrency);
+    const candidateLocales = [locale, ...(fallbackLocales || [])];
+    let messages;
+    // Try each candidate locale in order and stop at the first successful result
+    for (let i = 0; i < candidateLocales.length; i++) {
+        const candidateLocale = candidateLocales[i];
+        const isLast = i === candidateLocales.length - 1;
+        try {
+            const readed = await readLocaleMessages({
+                limit,
+                rootDir,
+                locale: candidateLocale,
+                namespaces,
+                extraOptions: { loggerOptions, exts, messagesReader },
+            });
+            // Stop at the first locale that yields non-empty messages
+            if (Object.values(readed[candidateLocale] || {}).length > 0) {
+                messages = readed;
+                break;
+            }
+        }
+        catch {
+            if (isLast) {
+                logger.warn("Failed to load messages for all candidate locales.", {
+                    locale,
+                    fallbackLocales,
+                });
+            }
+            else {
+                logger.warn(`Failed to load locale messages for "${candidateLocale}", trying next fallback.`);
+            }
+        }
+    }
+    // --- Cache write --------------------------------------------------
+    if (allowCacheWrite && cacheOptions.enabled && cacheKey && messages) {
+        await pool?.set(cacheKey, messages, cacheOptions.ttl);
+    }
+    // Final success log with resolved locale and timing
+    if (messages) {
+        logger.trace("Finished loading local messages.", {
+            loadedLocale: Object.keys(messages)[0],
+            duration: `${Math.round(performance.now() - start)} ms`,
+        });
+    }
+    return messages;
+};
+
+export { loadLocalMessages };

package/dist/{src → core/src}/server/messages/load-local-messages/read-locale-messages/collect-file-entries/collect-file-entries.js

@@ -10,36 +10,29 @@ import { getLogger } from '../../../../shared/logger/get-logger.js';
  *
  * @example
  * ```ts
- * [
- *   {
- *     namespace: "index", // "index" = messages under locale root (no namespace)
- *     fullPath: "/Users/john/my-app/messages/en-US/index.json",
- *     relativePath: "index.json",
- *     segments: ["index"],
- *     basename: "index",
- *   },
- *   {
- *     namespace: "auth",
+ * [{
+ *     namespace: "auth", // If messages under locale root (no namespace) -> "index"
  *     fullPath: "/Users/john/my-app/messages/en-US/auth/login.json",
  *     relativePath: "auth/login.json",
  *     segments: ["auth", "login"],
  *     basename: "login",
- *   },
- * ];
+ * }, ... ];
  * ```
  */
 async function collectFileEntries({ readdir = fs.readdir, limit, rootDir, namespaces, extraOptions: { exts = [".json"], loggerOptions } = {}, }) {
     const baseLogger = getLogger({ ...loggerOptions });
     const logger = baseLogger.child({ scope: "collect-file-entries" });
-    const results = [];
+    const fileEntries = [];
     const walk = async (currentDir) => {
         // Read current directory entries
         let entries = [];
         try {
             entries = await readdir(currentDir, { withFileTypes: true });
         }
-        catch (error) {
-            logger.error(`Error reading directory: ${currentDir}`, { error });
+        catch {
+            logger.debug("Locale directory not found, skipping locale.", {
+                localeDir: currentDir,
+            });
             return;
         }
         // Process each directory entry and collect valid files
@@ -65,7 +58,7 @@ async function collectFileEntries({ readdir = fs.readdir, limit, rootDir, namesp
                 if (!namespaces.includes(namespace))
                     return;
             }
-            results.push({
+            fileEntries.push({
                 namespace,
                 fullPath,
                 relativePath,
@@ -76,20 +69,10 @@ async function collectFileEntries({ readdir = fs.readdir, limit, rootDir, namesp
         await Promise.all(tasks);
     };
     await walk(rootDir);
-    // Logs
-    if (logger.core.level === "debug") {
-        logger.debug("Local message files collected.", {
-            count: results.length,
-        });
+    if (fileEntries.length > 0) {
+        logger.trace(`Collected ${fileEntries.length} local message files for locale "${path.basename(rootDir)}".`);
     }
-    logger.trace("Local message files collected.", {
-        count: results.length,
-        fileEntries: results.map(({ namespace, relativePath }) => ({
-            namespace: namespace === "index" ? null : namespace,
-            relativePath,
-        })),
-    });
-    return results;
+    return fileEntries;
 }
 
 export { collectFileEntries };

package/dist/{src → core/src}/server/messages/load-local-messages/read-locale-messages/parse-file-entries/parse-file-entries.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
-import merge from 'lodash.merge';
 import { isValidMessages } from '../../../shared/utils/is-valid-messages.js';
 import { getLogger } from '../../../../shared/logger/get-logger.js';
+import { deepMerge } from '../../../../../shared/utils/deep-merge.js';
 import { jsonReader } from './utils/json-reader.js';
 import { nestObjectFromPath } from './utils/nest-object-from-path.js';
 
@@ -41,7 +41,7 @@ async function parseFileEntries({ fileEntries, limit, extraOptions: { messagesRe
     const logger = baseLogger.child({ scope: "parse-file-entries" });
     // Read and parse all file entries
     const parsedFileEntries = [];
-    const tasks = fileEntries.map(({ namespace, segments, basename, fullPath }) => limit(async () => {
+    const tasks = fileEntries.map(({ namespace, segments, basename, fullPath, relativePath }) => limit(async () => {
         try {
             const segsWithoutNs = segments.slice(1);
             const ext = path.extname(fullPath);
@@ -58,7 +58,7 @@ async function parseFileEntries({ fileEntries, limit, extraOptions: { messagesRe
             // Nest the parsed content based on the path segments
             const nested = nestObjectFromPath(keyPath, json);
             parsedFileEntries.push({ namespace, messages: nested });
-            logger.trace("Parsed file.", { path: fullPath });
+            logger.trace(`Parsed message file: ${relativePath}`);
         }
         catch (error) {
             logger.error("Failed to read or parse file.", {
@@ -73,10 +73,13 @@ async function parseFileEntries({ fileEntries, limit, extraOptions: { messagesRe
     for (const { namespace, messages } of parsedFileEntries) {
         // Handle root-level namespace (i.e., [rootDir]/index.json)
         if (namespace === "index") {
-            merge(result, messages);
+            const merged = deepMerge(result, messages);
+            if (merged)
+                Object.assign(result, merged);
         }
         else {
-            result[namespace] = merge(result[namespace] ?? {}, messages);
+            result[namespace] =
+                deepMerge(result[namespace] ?? {}, messages) || {};
         }
     }
     return result;

package/dist/{src → core/src}/server/messages/load-local-messages/read-locale-messages/read-locale-messages.js

@@ -18,13 +18,13 @@ const readLocaleMessages = async ({ limit, rootDir = "messages", locale, namespa
         extraOptions: { exts, loggerOptions },
     });
     // 2. Parse file entries
-    const namespaceMessages = await parseFileEntries({
+    const messages = await parseFileEntries({
         fileEntries,
         limit,
         extraOptions: { messagesReader, loggerOptions },
     });
-    // 3. Wrap the parsed namespace messages under the locale key
-    const localeMessages = { [locale]: namespaceMessages };
+    // 3. Wrap the parsed messages under the locale key
+    const localeMessages = { [locale]: messages };
     return localeMessages;
 };