@fluojs/i18n 1.0.0-beta.1

package/dist/http.js

@@ -0,0 +1,179 @@
+import { createContextKey, getContextValue, setContextValue } from '@fluojs/http';
+import { isSupportedLocale, isValidLocale, normalizeLocaleResolverResult, parseLocalePreferences, selectLocaleFromAcceptLanguagePolicy } from './locale-resolution.js';
+
+/**
+ * Locale metadata stored on a fluo HTTP request context.
+ */
+
+/**
+ * Parsed `Accept-Language` preference ordered by caller priority.
+ */
+
+/**
+ * Input shared by explicit HTTP locale resolvers.
+ */
+
+/**
+ * Result returned by one HTTP locale resolver.
+ */
+
+/**
+ * Explicit locale resolver used by `resolveHttpLocale(...)` in application-defined order.
+ */
+
+/**
+ * Options for resolving a request locale from an ordered resolver chain.
+ */
+
+/**
+ * Options for creating an `Accept-Language` resolver.
+ */
+
+/**
+ * Options for the opt-in `Accept-Language` policy resolver.
+ */
+
+/**
+ * Request-context key used by `setHttpLocale(...)` and `getHttpLocale(...)`.
+ */
+export const HTTP_LOCALE_CONTEXT_KEY = createContextKey('fluo.i18n.http.locale');
+const DEFAULT_ACCEPT_LANGUAGE_SOURCE = 'accept-language';
+function readHeader(request, headerName) {
+  const normalizedName = headerName.toLowerCase();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (name.toLowerCase() === normalizedName) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Stores locale metadata on a fluo HTTP request context.
+ *
+ * @param context Request context to update.
+ * @param locale Locale selected for the request.
+ * @param metadata Additional locale metadata such as a resolver source.
+ */
+export function setHttpLocale(context, locale, metadata = {}) {
+  setContextValue(context, HTTP_LOCALE_CONTEXT_KEY, Object.freeze({
+    ...metadata,
+    locale
+  }));
+}
+
+/**
+ * Reads locale metadata from a fluo HTTP request context.
+ *
+ * @param context Request context to inspect.
+ * @returns Stored locale metadata, or `undefined` when the request has no locale.
+ */
+export function getHttpLocale(context) {
+  return getContextValue(context, HTTP_LOCALE_CONTEXT_KEY);
+}
+
+/**
+ * Parses an `Accept-Language` header into quality-sorted locale preferences.
+ *
+ * @param header Raw header value or adapter-provided repeated header values.
+ * @returns Valid language ranges ordered by descending q-value and original header order for ties.
+ */
+export function parseAcceptLanguage(header) {
+  return parseLocalePreferences(header);
+}
+
+/**
+ * Creates a resolver that selects the first supported `Accept-Language` locale.
+ *
+ * @param options Header name and source label options.
+ * @returns Locale resolver that inspects the current request headers.
+ */
+export function createAcceptLanguageLocaleResolver(options = {}) {
+  const headerName = options.headerName ?? 'accept-language';
+  const source = options.source ?? DEFAULT_ACCEPT_LANGUAGE_SOURCE;
+  return ({
+    context,
+    supportedLocales
+  }) => {
+    const header = readHeader(context.request, headerName);
+    const preferences = parseAcceptLanguage(header);
+    for (const preference of preferences) {
+      if (preference.locale === '*') {
+        continue;
+      }
+      if (isSupportedLocale(preference.locale, supportedLocales)) {
+        return {
+          locale: preference.locale,
+          source
+        };
+      }
+    }
+    return undefined;
+  };
+}
+
+/**
+ * Creates an opt-in resolver that normalizes supported `Accept-Language` ranges and can select a wildcard fallback.
+ *
+ * @param options Header, source, normalization, and wildcard policy options.
+ * @returns Locale resolver that treats `*` as fallback-only and preserves explicit locale preferences first.
+ */
+export function createAcceptLanguageLocalePolicyResolver(options = {}) {
+  const headerName = options.headerName ?? 'accept-language';
+  const source = options.source ?? DEFAULT_ACCEPT_LANGUAGE_SOURCE;
+  return ({
+    context,
+    defaultLocale,
+    supportedLocales
+  }) => {
+    const locale = selectLocaleFromAcceptLanguagePolicy(parseAcceptLanguage(readHeader(context.request, headerName)), defaultLocale, supportedLocales, options);
+    if (locale === undefined) {
+      return undefined;
+    }
+    return {
+      locale,
+      source
+    };
+  };
+}
+
+/**
+ * Runs an explicit resolver chain and stores the selected request locale.
+ *
+ * @param context Request context to resolve and update.
+ * @param options Default locale, supported locales, and ordered resolvers.
+ * @returns Stored locale metadata selected by the first valid resolver or the configured default locale.
+ * @throws {TypeError} When the configured default locale is invalid or unsupported.
+ */
+export function resolveHttpLocale(context, options) {
+  if (!isValidLocale(options.defaultLocale)) {
+    throw new TypeError('defaultLocale must be a syntactically valid locale string.');
+  }
+  if (!isSupportedLocale(options.defaultLocale, options.supportedLocales)) {
+    throw new TypeError('defaultLocale must be listed in supportedLocales when supportedLocales is provided.');
+  }
+  for (const resolver of options.resolvers ?? []) {
+    const result = normalizeLocaleResolverResult(resolver({
+      context,
+      defaultLocale: options.defaultLocale,
+      supportedLocales: options.supportedLocales
+    }));
+    if (result === undefined || !isValidLocale(result.locale) || !isSupportedLocale(result.locale, options.supportedLocales)) {
+      continue;
+    }
+    setHttpLocale(context, result.locale, {
+      source: result.source
+    });
+    return getHttpLocale(context) ?? {
+      locale: result.locale,
+      source: result.source
+    };
+  }
+  setHttpLocale(context, options.defaultLocale, {
+    source: 'default'
+  });
+  return getHttpLocale(context) ?? {
+    locale: options.defaultLocale,
+    source: 'default'
+  };
+}

package/dist/icu.d.ts

@@ -0,0 +1,59 @@
+import type { Formats } from 'intl-messageformat';
+import { I18nService } from './service.js';
+import type { I18nModuleOptions, I18nTranslateOptions } from './types.js';
+/**
+ * Primitive values accepted by the ICU MessageFormat subpath.
+ */
+export type I18nIcuValue = string | number | bigint | boolean | null | undefined | Date;
+/**
+ * Named values available to ICU MessageFormat placeholders.
+ */
+export type I18nIcuValues = Readonly<Record<string, I18nIcuValue>>;
+/**
+ * Per-call options for ICU MessageFormat translation.
+ */
+export interface I18nIcuTranslateOptions extends Omit<I18nTranslateOptions, 'values'> {
+    /** Values passed to ICU MessageFormat placeholders after core catalog and fallback resolution. */
+    readonly values?: I18nIcuValues;
+    /** Optional per-call Intl MessageFormat named format overrides. */
+    readonly formats?: Partial<Formats>;
+}
+/**
+ * ICU MessageFormat translation service layered on top of the framework-agnostic core `I18nService`.
+ *
+ * @remarks
+ * The root service keeps its simple `{{ name }}` interpolation and fallback behavior. This subpath resolves the
+ * message through that service first, then formats the resolved message with ICU MessageFormat plural/select rules.
+ */
+export declare class IcuI18nService {
+    private readonly service;
+    /**
+     * Creates an ICU MessageFormat service from root options or an existing core service.
+     *
+     * @param options Root i18n options or an existing `I18nService` instance.
+     */
+    constructor(options?: I18nModuleOptions | I18nService);
+    /**
+     * Returns the underlying core i18n service used for catalog lookup and fallback resolution.
+     *
+     * @returns The core `I18nService` instance backing this ICU formatter.
+     */
+    getCoreService(): I18nService;
+    /**
+     * Resolves a message with the core service and formats it with ICU MessageFormat.
+     *
+     * @param key Dot-path catalog key, optionally prefixed by `options.namespace`.
+     * @param options Per-call locale, ICU values, default value, and optional named format overrides.
+     * @returns The resolved and ICU-formatted message.
+     * @throws {I18nError} When the core lookup fails or the ICU pattern/values are invalid.
+     */
+    translate(key: string, options: I18nIcuTranslateOptions): string;
+}
+/**
+ * Creates a standalone ICU MessageFormat i18n service.
+ *
+ * @param options Root i18n options or an existing `I18nService` instance.
+ * @returns An `IcuI18nService` that preserves core lookup semantics before ICU formatting.
+ */
+export declare function createIcuI18n(options?: I18nModuleOptions | I18nService): IcuI18nService;
+//# sourceMappingURL=icu.d.ts.map

package/dist/icu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icu.d.ts","sourceRoot":"","sources":["../src/icu.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,OAAO,EAAE,WAAW,EAAc,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAwD,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEhI;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;AAExF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC;IACnF,kGAAkG;IAClG,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC;AAgFD;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IAEtC;;;;OAIG;gBACS,OAAO,GAAE,iBAAiB,GAAG,WAAgB;IAIzD;;;;OAIG;IACH,cAAc,IAAI,WAAW;IAI7B;;;;;;;OAOG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,MAAM;CAsBjE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,iBAAiB,GAAG,WAAgB,GAAG,cAAc,CAE3F"}

package/dist/icu.js

@@ -0,0 +1,142 @@
+import { FormatError, IntlMessageFormat } from 'intl-messageformat';
+import { I18nError } from './errors.js';
+import { I18nService, createI18n } from './service.js';
+
+/**
+ * Primitive values accepted by the ICU MessageFormat subpath.
+ */
+
+/**
+ * Named values available to ICU MessageFormat placeholders.
+ */
+
+/**
+ * Per-call options for ICU MessageFormat translation.
+ */
+
+function isCoreInterpolationValue(value) {
+  return value === null || value === undefined || ['string', 'number', 'boolean'].includes(typeof value);
+}
+function toCoreInterpolationValues(values) {
+  if (values === undefined) {
+    return undefined;
+  }
+  const interpolationValues = {};
+  let hasInterpolationValue = false;
+  for (const [key, value] of Object.entries(values)) {
+    if (isCoreInterpolationValue(value)) {
+      interpolationValues[key] = value;
+      hasInterpolationValue = true;
+    }
+  }
+  return hasInterpolationValue ? interpolationValues : undefined;
+}
+function toMessageFormatValues(values) {
+  if (values === undefined) {
+    return undefined;
+  }
+  return Object.fromEntries(Object.entries(values));
+}
+function hasOwn(value, key) {
+  return typeof value === 'object' && value !== null && Object.hasOwn(value, key);
+}
+function resolveMessage(tree, key) {
+  if (tree === undefined) {
+    return undefined;
+  }
+  if (hasOwn(tree, key)) {
+    const direct = tree[key];
+    return typeof direct === 'string' ? direct : undefined;
+  }
+  let current = tree;
+  for (const part of key.split('.')) {
+    if (!hasOwn(current, part)) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return typeof current === 'string' ? current : undefined;
+}
+function resolveMessageLocale(service, key, options) {
+  const resolvedKey = options.namespace === undefined ? key : `${options.namespace}.${key}`;
+  const snapshot = service.snapshotOptions();
+  for (const locale of service.resolveLocales(options.locale)) {
+    if (resolveMessage(snapshot.catalogs?.[locale], resolvedKey) !== undefined) {
+      return locale;
+    }
+  }
+  return options.locale;
+}
+function normalizeMessageFormatError(error, key) {
+  if (error instanceof FormatError || error instanceof SyntaxError || error instanceof Error) {
+    return new I18nError(`Invalid ICU MessageFormat for i18n key: ${key}`, 'I18N_INVALID_MESSAGE_FORMAT');
+  }
+  return new I18nError(`Invalid ICU MessageFormat for i18n key: ${key}`, 'I18N_INVALID_MESSAGE_FORMAT');
+}
+
+/**
+ * ICU MessageFormat translation service layered on top of the framework-agnostic core `I18nService`.
+ *
+ * @remarks
+ * The root service keeps its simple `{{ name }}` interpolation and fallback behavior. This subpath resolves the
+ * message through that service first, then formats the resolved message with ICU MessageFormat plural/select rules.
+ */
+export class IcuI18nService {
+  service;
+
+  /**
+   * Creates an ICU MessageFormat service from root options or an existing core service.
+   *
+   * @param options Root i18n options or an existing `I18nService` instance.
+   */
+  constructor(options = {}) {
+    this.service = options instanceof I18nService ? options : createI18n(options);
+  }
+
+  /**
+   * Returns the underlying core i18n service used for catalog lookup and fallback resolution.
+   *
+   * @returns The core `I18nService` instance backing this ICU formatter.
+   */
+  getCoreService() {
+    return this.service;
+  }
+
+  /**
+   * Resolves a message with the core service and formats it with ICU MessageFormat.
+   *
+   * @param key Dot-path catalog key, optionally prefixed by `options.namespace`.
+   * @param options Per-call locale, ICU values, default value, and optional named format overrides.
+   * @returns The resolved and ICU-formatted message.
+   * @throws {I18nError} When the core lookup fails or the ICU pattern/values are invalid.
+   */
+  translate(key, options) {
+    const message = this.service.translate(key, {
+      defaultValue: options.defaultValue,
+      locale: options.locale,
+      namespace: options.namespace,
+      values: toCoreInterpolationValues(options.values)
+    });
+    const messageLocale = resolveMessageLocale(this.service, key, options);
+    try {
+      const formatter = new IntlMessageFormat(message, messageLocale, options.formats);
+      const formatted = formatter.format(toMessageFormatValues(options.values));
+      if (typeof formatted === 'string') {
+        return formatted;
+      }
+    } catch (error) {
+      throw normalizeMessageFormatError(error, key);
+    }
+    throw new I18nError(`Invalid ICU MessageFormat result for i18n key: ${key}`, 'I18N_INVALID_MESSAGE_FORMAT');
+  }
+}
+
+/**
+ * Creates a standalone ICU MessageFormat i18n service.
+ *
+ * @param options Root i18n options or an existing `I18nService` instance.
+ * @returns An `IcuI18nService` that preserves core lookup semantics before ICU formatting.
+ */
+export function createIcuI18n(options = {}) {
+  return new IcuI18nService(options);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { I18nError } from './errors.js';
+export { I18nModule } from './module.js';
+export { createI18n, I18nService } from './service.js';
+export type { I18nErrorCode, I18nFallbackLocales, I18nCurrencyFormatOptions, I18nDateTimeFormatOptions, I18nFormatOptions, I18nFormatterOptions, I18nInterpolationValues, I18nListFormatOptions, I18nLocale, I18nMessageCatalogs, I18nMessageTree, I18nMissingMessageContext, I18nMissingMessageHandler, I18nModuleOptions, I18nNamedDateTimeFormats, I18nNamedListFormats, I18nNamedNumberFormats, I18nNamedRelativeTimeFormats, I18nNumberFormatOptions, I18nRelativeTimeFormatOptions, I18nTranslateOptions, I18nTranslationKey, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB,EACrB,UAAU,EACV,mBAAmB,EACnB,eAAe,EACf,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EACjB,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,4BAA4B,EAC5B,uBAAuB,EACvB,6BAA6B,EAC7B,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { I18nError } from './errors.js';
+export { I18nModule } from './module.js';
+export { createI18n, I18nService } from './service.js';

package/dist/loaders/fs.d.ts

@@ -0,0 +1,43 @@
+import type { I18nLocale, I18nMessageTree, I18nTranslationKey } from '../types.js';
+import type { I18nLoader } from './shared.js';
+export type { I18nLoader, I18nLoaderLoadOptions } from './shared.js';
+/**
+ * Options for the Node-only filesystem i18n catalog loader.
+ */
+export interface FileSystemI18nLoaderOptions {
+    /** Root catalog directory containing locale subdirectories. */
+    readonly rootDir: string;
+}
+/**
+ * Node-only JSON catalog loader for `@fluojs/i18n/loaders/fs`.
+ *
+ * @remarks
+ * Catalogs are read from `${rootDir}/${locale}/${namespace}.json`. Locale and namespace inputs are
+ * validated before disk reads, and the resolved path must remain inside `rootDir`.
+ */
+export declare class FileSystemI18nLoader implements I18nLoader {
+    private readonly rootDir;
+    /**
+     * Creates a filesystem-backed JSON catalog loader.
+     *
+     * @param options Loader options with an absolute or relative root catalog directory.
+     */
+    constructor(options: FileSystemI18nLoaderOptions);
+    /**
+     * Loads and validates one JSON message catalog from disk.
+     *
+     * @param locale Locale directory to load from.
+     * @param namespace Namespace JSON file path without extension.
+     * @returns A detached immutable i18n message tree.
+     * @throws {I18nError} When inputs are unsafe, the file is missing, JSON is malformed, or catalog shape is invalid.
+     */
+    load(locale: I18nLocale, namespace: I18nTranslationKey): Promise<I18nMessageTree>;
+}
+/**
+ * Creates a Node-only filesystem JSON catalog loader.
+ *
+ * @param options Loader options with the root catalog directory.
+ * @returns A filesystem-backed i18n loader instance.
+ */
+export declare function createFileSystemI18nLoader(options: FileSystemI18nLoaderOptions): FileSystemI18nLoader;
+//# sourceMappingURL=fs.d.ts.map

package/dist/loaders/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/loaders/fs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAO9C,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,UAAU;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;OAIG;gBACS,OAAO,EAAE,2BAA2B;IAQhD;;;;;;;OAOG;IACG,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;CA+BxF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,oBAAoB,CAErG"}

package/dist/loaders/fs.js

@@ -0,0 +1,79 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { I18nError } from '../errors.js';
+import { isPlainObject, snapshotLoaderMessageTree, validateLoaderLocale, validateLoaderNamespace } from './shared.js';
+function isWithinDirectory(rootDir, targetPath) {
+  const relativePath = relative(rootDir, targetPath);
+  return relativePath === '' || !relativePath.startsWith('..') && !isAbsolute(relativePath);
+}
+
+/**
+ * Options for the Node-only filesystem i18n catalog loader.
+ */
+
+/**
+ * Node-only JSON catalog loader for `@fluojs/i18n/loaders/fs`.
+ *
+ * @remarks
+ * Catalogs are read from `${rootDir}/${locale}/${namespace}.json`. Locale and namespace inputs are
+ * validated before disk reads, and the resolved path must remain inside `rootDir`.
+ */
+export class FileSystemI18nLoader {
+  rootDir;
+
+  /**
+   * Creates a filesystem-backed JSON catalog loader.
+   *
+   * @param options Loader options with an absolute or relative root catalog directory.
+   */
+  constructor(options) {
+    if (!isPlainObject(options) || typeof options.rootDir !== 'string' || options.rootDir.trim() === '') {
+      throw new I18nError('Filesystem i18n loader rootDir must be a non-empty string.', 'I18N_INVALID_LOADER_OPTIONS');
+    }
+    this.rootDir = resolve(options.rootDir);
+  }
+
+  /**
+   * Loads and validates one JSON message catalog from disk.
+   *
+   * @param locale Locale directory to load from.
+   * @param namespace Namespace JSON file path without extension.
+   * @returns A detached immutable i18n message tree.
+   * @throws {I18nError} When inputs are unsafe, the file is missing, JSON is malformed, or catalog shape is invalid.
+   */
+  async load(locale, namespace) {
+    validateLoaderLocale(locale, 'Filesystem i18n');
+    validateLoaderNamespace(namespace, 'Filesystem i18n');
+    const namespacePath = namespace.replaceAll('/', sep);
+    const catalogPath = resolve(this.rootDir, locale, `${namespacePath}.json`);
+    if (!isWithinDirectory(this.rootDir, catalogPath)) {
+      throw new I18nError('Filesystem i18n catalog path escapes rootDir.', 'I18N_INVALID_LOADER_OPTIONS');
+    }
+    let raw;
+    try {
+      raw = await readFile(catalogPath, 'utf8');
+    } catch (error) {
+      if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+        throw new I18nError(`Missing i18n catalog file: ${locale}/${namespace}.json`, 'I18N_MISSING_CATALOG');
+      }
+      throw error;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (error) {
+      throw new I18nError(`Malformed i18n catalog JSON: ${locale}/${namespace}.json`, 'I18N_INVALID_CATALOG');
+    }
+    return snapshotLoaderMessageTree(parsed, `catalogs.${locale}.${namespace}`);
+  }
+}
+
+/**
+ * Creates a Node-only filesystem JSON catalog loader.
+ *
+ * @param options Loader options with the root catalog directory.
+ * @returns A filesystem-backed i18n loader instance.
+ */
+export function createFileSystemI18nLoader(options) {
+  return new FileSystemI18nLoader(options);
+}

package/dist/loaders/remote.d.ts

@@ -0,0 +1,146 @@
+import type { I18nLocale, I18nMessageTree, I18nTranslationKey } from '../types.js';
+import type { I18nLoader, I18nLoaderLoadOptions } from './shared.js';
+export type { I18nLoader, I18nLoaderLoadOptions } from './shared.js';
+/**
+ * Request metadata passed to a remote catalog provider.
+ */
+export interface RemoteI18nCatalogRequest {
+    /** Locale identifier requested by the loader caller. */
+    readonly locale: I18nLocale;
+    /** Namespace identifier requested by the loader caller. */
+    readonly namespace: I18nTranslationKey;
+    /** Cancellation signal owned by the loader for timeout and caller abort propagation. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Provider abstraction for remote JSON catalog backends such as HTTP APIs, object stores, or databases.
+ */
+export type RemoteI18nCatalogProvider = (request: RemoteI18nCatalogRequest) => Promise<unknown> | unknown;
+/**
+ * Options for provider-backed remote catalog loading.
+ */
+export interface RemoteI18nLoaderOptions {
+    /** Backend provider that returns one raw catalog object or JSON string for the requested locale and namespace. */
+    readonly provider: RemoteI18nCatalogProvider;
+    /** Maximum load duration in milliseconds before the loader aborts and throws `I18N_LOADER_TIMEOUT`. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Cache key input for opt-in remote catalog caching helpers.
+ */
+export interface CachedI18nLoaderKeyInput {
+    /** Locale identifier requested by the loader caller. */
+    readonly locale: I18nLocale;
+    /** Namespace identifier requested by the loader caller. */
+    readonly namespace: I18nTranslationKey;
+    /** Optional caller-owned catalog version included in the default cache key. */
+    readonly version?: string;
+}
+/**
+ * Options for wrapping a remote catalog loader with explicit in-memory caching.
+ */
+export interface CachedI18nLoaderOptions {
+    /** Loader to wrap with opt-in cache behavior. */
+    readonly loader: I18nLoader;
+    /** Cache entry lifetime in milliseconds. */
+    readonly ttlMs: number;
+    /** Optional catalog version included in the default `(locale, namespace, version)` cache key. */
+    readonly version?: string;
+    /** Optional caller-owned cache key function for application-specific invalidation boundaries. */
+    readonly getCacheKey?: (input: CachedI18nLoaderKeyInput) => string;
+    /** Optional clock used by tests or deterministic runtime wrappers. */
+    readonly now?: () => number;
+}
+/**
+ * Invalidation controls exposed by opt-in cached i18n loaders.
+ */
+export interface CachedI18nLoader extends I18nLoader {
+    /** Invalidates one catalog cache entry by locale and namespace. */
+    invalidate(locale: I18nLocale, namespace: I18nTranslationKey): void;
+    /** Clears every cached catalog entry owned by this wrapper. */
+    clear(): void;
+}
+/**
+ * Provider-backed remote JSON catalog loader for `@fluojs/i18n/loaders/remote`.
+ *
+ * @remarks
+ * The loader validates locale and namespace before calling the provider, propagates cancellation through an
+ * `AbortSignal`, enforces a per-load timeout, parses JSON strings, validates message tree shape, and always
+ * returns a detached immutable catalog snapshot.
+ */
+export declare class RemoteI18nLoader implements I18nLoader {
+    private readonly provider;
+    private readonly timeoutMs;
+    /**
+     * Creates a provider-backed remote catalog loader.
+     *
+     * @param options Remote loader options with a provider and optional timeout.
+     */
+    constructor(options: RemoteI18nLoaderOptions);
+    /**
+     * Loads and validates one remote message catalog through the configured provider.
+     *
+     * @param locale Locale identifier passed to the provider.
+     * @param namespace Namespace identifier passed to the provider.
+     * @param options Optional per-load cancellation controls.
+     * @returns A detached immutable i18n message tree.
+     * @throws {I18nError} When inputs are unsafe, the provider misses/fails, loading times out, JSON is malformed, or catalog shape is invalid.
+     */
+    load(locale: I18nLocale, namespace: I18nTranslationKey, options?: I18nLoaderLoadOptions): Promise<I18nMessageTree>;
+}
+/**
+ * Opt-in in-memory caching wrapper for remote i18n catalog loaders.
+ *
+ * @remarks
+ * This wrapper never changes `RemoteI18nLoader` defaults. Applications choose it explicitly when they want catalog
+ * caching at the loading boundary and can invalidate entries through `invalidate(...)` or `clear()`.
+ */
+export declare class CachedRemoteI18nLoader implements CachedI18nLoader {
+    private readonly cache;
+    private readonly getCacheKey;
+    private readonly loader;
+    private readonly now;
+    private readonly ttlMs;
+    private readonly version;
+    /**
+     * Creates an explicit cache wrapper around a remote catalog loader.
+     *
+     * @param options Loader, TTL, version, key, and clock options for the cache wrapper.
+     */
+    constructor(options: CachedI18nLoaderOptions);
+    /**
+     * Loads a catalog through the wrapped loader and caches successful results until the configured TTL expires.
+     *
+     * @param locale Locale identifier passed to the wrapped loader.
+     * @param namespace Namespace identifier passed to the wrapped loader.
+     * @param options Optional per-load cancellation controls for cache misses.
+     * @returns A cached or freshly loaded immutable i18n message tree.
+     */
+    load(locale: I18nLocale, namespace: I18nTranslationKey, options?: I18nLoaderLoadOptions): Promise<I18nMessageTree>;
+    /**
+     * Invalidates one cached catalog entry using the same key policy as `load(...)`.
+     *
+     * @param locale Locale identifier for the cache entry.
+     * @param namespace Namespace identifier for the cache entry.
+     */
+    invalidate(locale: I18nLocale, namespace: I18nTranslationKey): void;
+    /**
+     * Clears every cache entry owned by this wrapper.
+     */
+    clear(): void;
+}
+/**
+ * Creates a provider-backed remote JSON catalog loader.
+ *
+ * @param options Remote loader options with a provider and optional timeout.
+ * @returns A remote i18n loader instance.
+ */
+export declare function createRemoteI18nLoader(options: RemoteI18nLoaderOptions): RemoteI18nLoader;
+/**
+ * Creates an opt-in cached remote catalog loader wrapper.
+ *
+ * @param options Loader, TTL, version, key, and clock options for the cache wrapper.
+ * @returns A cached loader wrapper with explicit invalidation controls.
+ */
+export declare function createCachedRemoteI18nLoader(options: CachedI18nLoaderOptions): CachedRemoteI18nLoader;
+//# sourceMappingURL=remote.d.ts.map

package/dist/loaders/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/loaders/remote.ts"],"names":[],"mappings":"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"}