intor 2.3.35 → 2.4.0

package/README.md

@@ -2,16 +2,20 @@
 
 <div align="center">
   
-A lightweight, framework-agnostic i18n engine that works instantly with a clean, type-safe API.  
-Fast to start, easy to extend, and free from the usual i18n heaviness.
+The i18n library for modern JavaScript
 
 </div>
 
 <div align="center">
 
 [![NPM version](https://img.shields.io/npm/v/intor?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/intor)
-[![Bundle size](https://img.shields.io/bundlephobia/minzip/intor?style=flat&colorA=000000&colorB=000000)](https://bundlephobia.com/package/intor)
 [![TypeScript](https://img.shields.io/badge/TypeScript-%E2%9C%94-blue?style=flat&colorA=000000&colorB=000000)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/npm/l/intor?style=flat&colorA=000000&colorB=000000)](LICENSE)
 
 </div>
+
+<div align="center">
+
+#### [![Documentation ↗](https://img.shields.io/badge/%20Documentation%20%F0%9F%93%9A%20-3e668c?style=for-the-badge)](https://intor-doc.pages.dev/en-US/frameworks)
+
+</div>

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

@@ -0,0 +1,6 @@
+export { getTranslator } from '../../src/edge/helpers/get-translator.js';
+import '../../src/core/error/intor-error.js';
+import 'logry';
+import 'p-limit';
+import 'intor-translator';
+export { resolveInboundFromRequest } from '../../src/routing/inbound/helpers/resolve-inbound-from-request.js';

package/dist/core/src/{server → core}/translator/create-translator.js

@@ -1,5 +1,5 @@
 import { Translator } from 'intor-translator';
-import { mergeMessages } from '../../core/messages/merge-messages.js';
+import { mergeMessages } from '../messages/merge-messages.js';
 
 /**
  * Create a server-side Translator instance for a fixed locale.

package/dist/core/src/core/utils/normalizers/normalize-locale.js

@@ -0,0 +1,59 @@
+const toCanonical = (input) => {
+    try {
+        return Intl.getCanonicalLocales(input)[0];
+    }
+    catch {
+        return;
+    }
+};
+/**
+ * Normalizes a locale string and resolves the best match
+ * from a list of supported locales.
+ *
+ * Resolution strategy:
+ *
+ * 1. Exact canonical match (BCP 47)
+ * 2. Base language fallback
+ *    - Falls back by base language when no exact match is found
+ *      (e.g. `"en"` → `"en-US"`).
+ *    - Script and region subtags are ignored during this step
+ *      (e.g. `"zh-Hans"` → `"zh-Hant-TW"`)
+ *    - Preference is determined by the order of `supportedLocales`.
+ *
+ * Returns `undefined` if no suitable match is found.
+ *
+ * Notes:
+ * - Invalid locale inputs are ignored gracefully.
+ * - Always returns an original entry from `supportedLocales`.
+ * - Requires `Intl` locale support in the runtime.
+ */
+const normalizeLocale = (locale, supportedLocales = []) => {
+    if (!locale || supportedLocales.length === 0)
+        return;
+    const canonicalLocale = toCanonical(locale);
+    if (!canonicalLocale)
+        return;
+    const supportedCanonicalMap = new Map();
+    for (const l of supportedLocales) {
+        const normalized = toCanonical(l);
+        if (normalized) {
+            supportedCanonicalMap.set(normalized, l);
+        }
+    }
+    // 1. Exact match
+    if (supportedCanonicalMap.has(canonicalLocale)) {
+        return supportedCanonicalMap.get(canonicalLocale);
+    }
+    const baseLang = canonicalLocale.split("-")[0];
+    // 2. Match by same base language (e.g., "en" matches "en-US" or "en-GB")
+    for (const [key, original] of supportedCanonicalMap) {
+        const supportedBase = key.split("-")[0];
+        if (supportedBase === baseLang) {
+            return original;
+        }
+    }
+    // 3. No match
+    return;
+};
+
+export { normalizeLocale };

package/dist/core/src/core/utils/normalizers/normalize-query.js

@@ -0,0 +1,25 @@
+/**
+ * Normalize a raw query object into a string-only map.
+ *
+ * This utility is used to sanitize framework-specific query inputs
+ * into a stable shape that the routing core
+ * can safely consume.
+ *
+ * Behavior:
+ * - Keeps only entries whose values are strings
+ * - Ignores arrays, objects, and other non-string values
+ * - Does not throw or attempt to coerce values
+ *
+ * This function is intentionally conservative by design.
+ */
+function normalizeQuery(query) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(query)) {
+        if (typeof value === "string") {
+            normalized[key] = value;
+        }
+    }
+    return normalized;
+}
+
+export { normalizeQuery };

package/dist/core/src/edge/helpers/get-translator.js

@@ -0,0 +1,29 @@
+import '../../core/error/intor-error.js';
+import 'logry';
+import 'p-limit';
+import 'intor-translator';
+import { createTRich } from '../../core/translator/create-t-rich.js';
+import { initTranslator } from '../translator/init-translator.js';
+
+/**
+ * Get a edge-runtime translator for the current execution context.
+ */
+async function getTranslator(config, params) {
+    const { locale, fetch, preKey, handlers, plugins } = params;
+    // Initialize a locale-bound translator snapshot with messages loaded
+    const translator = await initTranslator(config, locale, {
+        fetch: fetch || globalThis.fetch,
+        plugins,
+        handlers,
+    });
+    const scoped = translator.scoped(preKey);
+    return {
+        messages: translator.messages,
+        locale: translator.locale,
+        hasKey: scoped.hasKey,
+        t: scoped.t,
+        tRich: createTRich(scoped.t),
+    };
+}
+
+export { getTranslator };

package/dist/core/src/edge/translator/init-translator.js

@@ -0,0 +1,35 @@
+import '../../core/error/intor-error.js';
+import 'logry';
+import { loadRemoteMessages } from '../../core/messages/load-remote-messages/load-remote-messages.js';
+import { createTranslator } from '../../core/translator/create-translator.js';
+import 'intor-translator';
+
+/**
+ * Initialize a locale-bound Translator snapshot.
+ *
+ * - Loads translation messages using the configured remote loader, if present.
+ * - Creates an immutable Translator instance for edge runtimes
+ */
+async function initTranslator(config, locale, options) {
+    const { loader } = config;
+    const { fetch, handlers, plugins } = options;
+    // Load messages
+    let messages = {};
+    if (loader && loader.mode === "remote") {
+        const loaded = await loadRemoteMessages({
+            locale,
+            fallbackLocales: config.fallbackLocales[locale] || [],
+            namespaces: loader.namespaces,
+            concurrency: loader.concurrency,
+            fetch,
+            url: loader.url,
+            headers: loader.headers,
+            loggerOptions: config.logger,
+        });
+        messages = loaded || {};
+    }
+    // Create immutable translator snapshot
+    return createTranslator({ config, locale, messages, handlers, plugins });
+}
+
+export { initTranslator };

package/dist/core/src/routing/inbound/helpers/resolve-inbound-from-request.js

@@ -0,0 +1,29 @@
+import '../../../core/error/intor-error.js';
+import { parseCookieHeader } from '../../../core/utils/parse-cookie-header.js';
+import { normalizeQuery } from '../../../core/utils/normalizers/normalize-query.js';
+import 'logry';
+import 'p-limit';
+import 'intor-translator';
+import { getLocaleFromAcceptLanguage } from '../../locale/get-locale-from-accept-language.js';
+import { resolveInbound } from '../resolve-inbound.js';
+
+async function resolveInboundFromRequest(config, request) {
+    const url = new URL(request.url);
+    const headers = request.headers;
+    // Cookie
+    const cookies = parseCookieHeader(headers.get("cookie") ?? undefined);
+    const cookieLocale = cookies[config.cookie.name];
+    // Query
+    const normalizedQuery = normalizeQuery(Object.fromEntries(url.searchParams));
+    // Accept-Language
+    const acceptLanguage = headers.get("accept-language") ?? undefined;
+    const localeFromAcceptLanguage = getLocaleFromAcceptLanguage(acceptLanguage, config.supportedLocales);
+    return resolveInbound(config, url.pathname, {
+        host: url.hostname,
+        query: normalizedQuery,
+        cookie: cookieLocale,
+        detected: localeFromAcceptLanguage || config.defaultLocale,
+    });
+}
+
+export { resolveInboundFromRequest };

package/dist/core/src/routing/inbound/resolve-inbound.js

@@ -0,0 +1,45 @@
+import { getLocaleFromPathname } from '../locale/get-locale-from-pathname.js';
+import { getLocaleFromHost } from '../locale/get-locale-from-host.js';
+import { getLocaleFromQuery } from '../locale/get-locale-from-query.js';
+import { resolveLocale } from './resolve-locale/resolve-locale.js';
+import { resolvePath } from './resolve-path/resolve-path.js';
+
+/**
+ * Resolves inbound routing state.
+ *
+ * - Resolves the effective locale from inbound inputs
+ * - Localizes the pathname based on the resolved locale
+ * - Indicates whether a redirect is required
+ *
+ * No side effects. No navigation.
+ */
+async function resolveInbound(config, rawPathname, localeInputs, options) {
+    const { queryKey } = config.routing.inbound;
+    const { host, query, cookie, detected } = localeInputs;
+    // ------------------------------------------------------
+    // Resolve locale from inbound inputs
+    // ------------------------------------------------------
+    const pathLocale = getLocaleFromPathname(rawPathname, config);
+    const { locale, localeSource } = resolveLocale(config, {
+        path: { locale: pathLocale },
+        host: { locale: getLocaleFromHost(host) },
+        query: { locale: getLocaleFromQuery(query, queryKey) },
+        cookie: { locale: cookie },
+        detected: { locale: detected },
+    });
+    // ------------------------------------------------------
+    // Resolve localized pathname and redirect requirement
+    // ------------------------------------------------------
+    const { pathname, shouldRedirect } = resolvePath(config, rawPathname, {
+        locale,
+        hasPathLocale: !!pathLocale,
+        hasPersisted: !!cookie});
+    return {
+        locale,
+        localeSource,
+        pathname,
+        shouldRedirect,
+    };
+}
+
+export { resolveInbound };

package/dist/core/src/routing/inbound/resolve-locale/resolve-locale.js

@@ -0,0 +1,35 @@
+import '../../../core/error/intor-error.js';
+import { normalizeLocale } from '../../../core/utils/normalizers/normalize-locale.js';
+import 'logry';
+import 'p-limit';
+import 'intor-translator';
+
+/**
+ * Resolve the active locale from inbound routing configuration.
+ *
+ * Iterates through configured locale sources and returns the first normalized, supported locale.
+ *
+ * Falls back to the detected locale or the default locale if none match.
+ */
+function resolveLocale(config, context) {
+    const { localeSources } = config.routing.inbound;
+    for (const source of localeSources) {
+        const locale = context[source]?.locale;
+        const normalized = normalizeLocale(locale, config.supportedLocales);
+        if (!normalized)
+            continue;
+        return {
+            locale: normalized,
+            localeSource: source,
+        };
+    }
+    // Fallback: detected is always available
+    const fallback = normalizeLocale(context.detected.locale, config.supportedLocales) ||
+        config.defaultLocale;
+    return {
+        locale: fallback,
+        localeSource: "detected",
+    };
+}
+
+export { resolveLocale };

package/dist/{next/src/routing/inbound/resolve-pathname/resolve-pathname.js → core/src/routing/inbound/resolve-path/resolve-path.js}

@@ -12,7 +12,7 @@ const assertNever = (x) => {
  * The resolved pathname represents the final, normalized form
  * used for routing and navigation.
  */
-const resolvePathname = (config, rawPathname, context) => {
+const resolvePath = (config, rawPathname, context) => {
     const { localePrefix } = config.routing;
     let directive;
     switch (localePrefix) {
@@ -39,4 +39,4 @@ const resolvePathname = (config, rawPathname, context) => {
     };
 };
 
-export { resolvePathname };
+export { resolvePath };

package/dist/core/src/routing/locale/get-locale-from-accept-language.js

@@ -0,0 +1,38 @@
+/**
+ * Get locale candidate from the `Accept-Language` header.
+ *
+ * Parses language priorities and returns the highest-priority
+ * language present in `supportedLocales`, without normalization.
+ *
+ * @example
+ * ```ts
+ * getLocaleFromAcceptLanguage("en-US,en;q=0.8,zh-TW;q=0.9", ["en-US", "zh-TW"])
+ * // => "en-US"
+ *
+ * getLocaleFromAcceptLanguage("fr,ja;q=0.9", ["en", "zh-TW"])
+ * // => undefined
+ * ```
+ */
+const getLocaleFromAcceptLanguage = (acceptLanguageHeader, supportedLocales) => {
+    if (!acceptLanguageHeader || supportedLocales.length === 0) {
+        return;
+    }
+    const supportedLocalesSet = new Set(supportedLocales);
+    // 1. Parse Accept-Language header into language + priority pairs
+    const parsedLanguages = acceptLanguageHeader.split(",").map((part) => {
+        const [rawLang, rawQ] = part.split(";");
+        const lang = rawLang.trim();
+        const q = rawQ ? Number.parseFloat(rawQ.split("=")[1]) : 1;
+        return {
+            lang,
+            q: Number.isNaN(q) ? 0 : q, // Invalid q values have lowest priority
+        };
+    });
+    // 2. Sort by priority (highest first)
+    const sortedByPriority = parsedLanguages.toSorted((a, b) => b.q - a.q);
+    // 3. Pick the first language explicitly supported
+    const preferred = sortedByPriority.find(({ lang }) => supportedLocalesSet.has(lang))?.lang;
+    return preferred;
+};
+
+export { getLocaleFromAcceptLanguage };

package/dist/core/src/routing/locale/get-locale-from-host.js

@@ -0,0 +1,32 @@
+/**
+ * Get locale candidate from hostname.
+ *
+ * Returns the left-most hostname label, without validation or normalization.
+ *
+ * @example
+ * ```ts
+ * getLocaleFromHost("en.example.com")
+ * // => "en"
+ *
+ * getLocaleFromHost("example.com")
+ * // => "example"
+ *
+ * getLocaleFromHost("api.jp.example.com")
+ * // => "api"
+ *
+ * getLocaleFromHost("localhost")
+ * // => undefined
+ * ```
+ */
+function getLocaleFromHost(host) {
+    if (!host)
+        return;
+    // Remove port (e.g. localhost:3000)
+    const hostname = host.split(":")[0];
+    const parts = hostname.split(".");
+    if (parts.length < 2)
+        return;
+    return parts[0];
+}
+
+export { getLocaleFromHost };

package/dist/core/src/routing/locale/get-locale-from-pathname.js

@@ -0,0 +1,47 @@
+import '../../core/error/intor-error.js';
+import { normalizePathname } from '../../core/utils/normalizers/normalize-pathname.js';
+import 'logry';
+import 'p-limit';
+import 'intor-translator';
+
+/**
+ * Get locale from pathname.
+ *
+ * Extracts the first pathname segment (after basePath) as a locale
+ * if it exactly matches one of the supported locales.
+ *
+ * @example
+ * ```ts
+ * getLocaleFromPathname(config, "/en/about")
+ * // => "en"
+ * getLocaleFromPathname(config, "/zh-TW")
+ * // => "zh-TW"
+ * getLocaleFromPathname(config, "/about")
+ * // => undefined
+ *
+ * // config.routing.basePath: "/app"
+ * getLocaleFromPathname(config, "/app/en/dashboard")
+ * // => "en"
+ * ```
+ */
+function getLocaleFromPathname(pathname, config) {
+    const { routing, supportedLocales } = config;
+    const { basePath } = routing;
+    // 1. Normalize pathname
+    const normalizedPathname = normalizePathname(pathname);
+    // 2. Strip basePath
+    let prefixedPathname = normalizedPathname;
+    if (basePath && normalizedPathname === basePath) {
+        prefixedPathname = "/";
+    }
+    else if (basePath && normalizedPathname.startsWith(basePath + "/")) {
+        prefixedPathname = normalizedPathname.slice(basePath.length);
+    }
+    // 3. Detect locale segment
+    const firstSegment = prefixedPathname.split("/").find(Boolean);
+    return firstSegment && supportedLocales.includes(firstSegment)
+        ? firstSegment
+        : undefined;
+}
+
+export { getLocaleFromPathname };

package/dist/core/src/routing/locale/get-locale-from-query.js

@@ -0,0 +1,21 @@
+/**
+ * Get locale candidate from URL query parameters.
+ *
+ * Extracts the value of the configured query key, without
+ * validation or normalization.
+ *
+ * @example
+ * ```ts
+ * getLocaleFromQuery({ locale: "en" }, "locale")
+ * // => "en"
+ *
+ * getLocaleFromQuery({}, "locale")
+ * // => undefined
+ */
+function getLocaleFromQuery(query, queryKey) {
+    if (!query)
+        return;
+    return query[queryKey];
+}
+
+export { getLocaleFromQuery };

package/dist/core/src/server/helpers/get-translator.js

@@ -1,10 +1,13 @@
 import '../../core/error/intor-error.js';
 import 'logry';
 import 'p-limit';
+import 'intor-translator';
 import { createTRich } from '../../core/translator/create-t-rich.js';
 import { initTranslator } from '../translator/init-translator.js';
 
-// Implementation
+/**
+ * Get a server-side translator for the current execution context.
+ */
 async function getTranslator(config, params) {
     const { locale, readers, allowCacheWrite, fetch, preKey, handlers, plugins } = params;
     // Initialize a locale-bound translator snapshot with messages loaded
@@ -22,10 +25,6 @@ async function getTranslator(config, params) {
         hasKey: scoped.hasKey,
         t: scoped.t,
         tRich: createTRich(scoped.t),
-        // NOTE:
-        // The runtime implementation is intentionally erased.
-        // Type safety is guaranteed by public type contracts.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
     };
 }
 

package/dist/core/src/server/translator/init-translator.js

@@ -2,11 +2,11 @@ import '../../core/error/intor-error.js';
 import { resolveLoaderOptions } from '../../core/utils/resolve-loader-options.js';
 import 'logry';
 import 'p-limit';
+import { createTranslator } from '../../core/translator/create-translator.js';
 import 'intor-translator';
 import { loadMessages } from '../messages/load-messages.js';
 import 'node:path';
 import 'node:fs/promises';
-import { createTranslator } from './create-translator.js';
 
 /**
  * Initialize a locale-bound Translator snapshot.

package/dist/express/src/adapters/express/create-intor-handler.js

@@ -1,4 +1,5 @@
 import '../../core/error/intor-error.js';
+import { parseCookieHeader } from '../../core/utils/parse-cookie-header.js';
 import { normalizeQuery } from '../../core/utils/normalizers/normalize-query.js';
 import 'logry';
 import 'p-limit';
@@ -8,14 +9,11 @@ import { getLocaleFromAcceptLanguage } from '../../routing/locale/get-locale-fro
 import 'node:path';
 import 'node:fs/promises';
 import { getTranslator } from '../../server/helpers/get-translator.js';
-import { parseCookieHeader } from '../../server/shared/utils/parse-cookie-header.js';
 
 /**
  * Resolves locale-aware routing for the current execution context.
  *
- * The resolved routing state is exposed via response headers.
- *
- * - Permits cache writes during server execution.
+ * - Binds resolved routing state to the request.
  * - Convenience routing shortcuts are also bound to the request for downstream consumption.
  *
  * @platform Express

package/dist/express/src/adapters/express/get-translator.js

@@ -6,7 +6,13 @@ import 'node:path';
 import 'node:fs/promises';
 import { getTranslator as getTranslator$1 } from '../../server/helpers/get-translator.js';
 
-// Implementation
+/**
+ * Get a server-side translator for the current execution context.
+ *
+ * - Automatically resolves the locale from the framework context.
+ *
+ * @platform Express
+ */
 async function getTranslator(config, req, params) {
     const { preKey, handlers, plugins, readers, allowCacheWrite } = params || {};
     return getTranslator$1(config, {

package/dist/express/src/{server → core}/translator/create-translator.js

@@ -1,5 +1,5 @@
 import { Translator } from 'intor-translator';
-import { mergeMessages } from '../../core/messages/merge-messages.js';
+import { mergeMessages } from '../messages/merge-messages.js';
 
 /**
  * Create a server-side Translator instance for a fixed locale.

package/dist/express/src/core/utils/parse-cookie-header.js

@@ -0,0 +1,22 @@
+/**
+ * Parse a raw HTTP Cookie header into a key-value record.
+ */
+function parseCookieHeader(cookieHeader) {
+    if (!cookieHeader)
+        return {};
+    const record = {};
+    // Split the Cookie header into individual key-value pairs
+    const pairs = cookieHeader.split(";");
+    for (const pair of pairs) {
+        // Locate the first "=" to separate key and value
+        const index = pair.indexOf("=");
+        if (index === -1)
+            continue;
+        const key = pair.slice(0, index).trim();
+        const value = pair.slice(index + 1).trim();
+        record[key] = decodeURIComponent(value);
+    }
+    return record;
+}
+
+export { parseCookieHeader };

package/dist/express/src/routing/inbound/resolve-inbound.js

@@ -2,7 +2,7 @@ import { getLocaleFromPathname } from '../locale/get-locale-from-pathname.js';
 import { getLocaleFromHost } from '../locale/get-locale-from-host.js';
 import { getLocaleFromQuery } from '../locale/get-locale-from-query.js';
 import { resolveLocale } from './resolve-locale/resolve-locale.js';
-import { resolvePathname } from './resolve-pathname/resolve-pathname.js';
+import { resolvePath } from './resolve-path/resolve-path.js';
 
 /**
  * Resolves inbound routing state.
@@ -30,7 +30,7 @@ async function resolveInbound(config, rawPathname, localeInputs, options) {
     // ------------------------------------------------------
     // Resolve localized pathname and redirect requirement
     // ------------------------------------------------------
-    const { pathname, shouldRedirect } = resolvePathname(config, rawPathname, {
+    const { pathname, shouldRedirect } = resolvePath(config, rawPathname, {
         locale,
         hasPathLocale: !!pathLocale,
         hasPersisted: !!cookie});

package/dist/express/src/routing/inbound/{resolve-pathname/resolve-pathname.js → resolve-path/resolve-path.js}

@@ -12,7 +12,7 @@ const assertNever = (x) => {
  * The resolved pathname represents the final, normalized form
  * used for routing and navigation.
  */
-const resolvePathname = (config, rawPathname, context) => {
+const resolvePath = (config, rawPathname, context) => {
     const { localePrefix } = config.routing;
     let directive;
     switch (localePrefix) {
@@ -39,4 +39,4 @@ const resolvePathname = (config, rawPathname, context) => {
     };
 };
 
-export { resolvePathname };
+export { resolvePath };

package/dist/express/src/server/helpers/get-translator.js

@@ -1,10 +1,13 @@
 import '../../core/error/intor-error.js';
 import 'logry';
 import 'p-limit';
+import 'intor-translator';
 import { createTRich } from '../../core/translator/create-t-rich.js';
 import { initTranslator } from '../translator/init-translator.js';
 
-// Implementation
+/**
+ * Get a server-side translator for the current execution context.
+ */
 async function getTranslator(config, params) {
     const { locale, readers, allowCacheWrite, fetch, preKey, handlers, plugins } = params;
     // Initialize a locale-bound translator snapshot with messages loaded
@@ -22,10 +25,6 @@ async function getTranslator(config, params) {
         hasKey: scoped.hasKey,
         t: scoped.t,
         tRich: createTRich(scoped.t),
-        // NOTE:
-        // The runtime implementation is intentionally erased.
-        // Type safety is guaranteed by public type contracts.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
     };
 }
 

package/dist/express/src/server/translator/init-translator.js

@@ -2,11 +2,11 @@ import '../../core/error/intor-error.js';
 import { resolveLoaderOptions } from '../../core/utils/resolve-loader-options.js';
 import 'logry';
 import 'p-limit';
+import { createTranslator } from '../../core/translator/create-translator.js';
 import 'intor-translator';
 import { loadMessages } from '../messages/load-messages.js';
 import 'node:path';
 import 'node:fs/promises';
-import { createTranslator } from './create-translator.js';
 
 /**
  * Initialize a locale-bound Translator snapshot.

package/dist/fastify/export/fastify/index.js

@@ -0,0 +1,3 @@
+export { intorFastifyPlugin } from '../../src/adapters/fastify/intor-fastify-plugin.js';
+export { getTranslator } from '../../src/adapters/fastify/get-translator.js';
+import 'fastify';