@fluojs/i18n 1.0.0-beta.1

package/dist/adapters.d.ts

@@ -0,0 +1,180 @@
+import { type AcceptLanguageLocalePolicyOptions } from './locale-resolution.js';
+import type { I18nLocale } from './types.js';
+/**
+ * Locale metadata resolved for a non-HTTP transport context.
+ */
+export interface LocaleAdapterContext {
+    /** Locale selected for the active context. */
+    readonly locale: I18nLocale;
+    /** Optional resolver name or application-defined source that selected the locale. */
+    readonly source?: string;
+}
+/**
+ * Input shared by opt-in non-HTTP locale resolvers.
+ */
+export interface LocaleAdapterResolverInput<TContext> {
+    /** Transport-specific context supplied by the application boundary. */
+    readonly context: TContext;
+    /** Supported locale allow-list. Empty or omitted lists allow any syntactically valid locale. */
+    readonly supportedLocales?: readonly I18nLocale[];
+    /** Default locale used when no resolver selects a supported locale. */
+    readonly defaultLocale: I18nLocale;
+}
+/**
+ * Result returned by one non-HTTP locale resolver.
+ */
+export interface LocaleAdapterResolverResult {
+    /** Locale selected by the resolver. */
+    readonly locale: I18nLocale;
+    /** Resolver name or application-defined source that selected the locale. */
+    readonly source?: string;
+}
+/**
+ * Explicit locale resolver used by `resolveLocale(...)` in application-defined order.
+ */
+export type LocaleAdapterResolver<TContext> = (input: LocaleAdapterResolverInput<TContext>) => unknown;
+/**
+ * Adapter-owned locale metadata store for transport contexts that have session, socket, call, or request state.
+ */
+export interface LocaleAdapterStore<TContext> {
+    /** Reads previously stored locale metadata from the context. */
+    get(context: TContext): LocaleAdapterContext | undefined;
+    /** Stores locale metadata on or alongside the context. */
+    set(context: TContext, locale: LocaleAdapterContext): void;
+}
+/**
+ * Options for resolving a locale from an ordered non-HTTP resolver chain.
+ */
+export interface ResolveLocaleOptions<TContext> {
+    /** Supported locale allow-list. Empty or omitted lists allow any syntactically valid locale. */
+    readonly supportedLocales?: readonly I18nLocale[];
+    /** Default locale returned when no resolver selects a supported locale. */
+    readonly defaultLocale: I18nLocale;
+    /** Resolver chain executed in array order. */
+    readonly resolvers?: readonly LocaleAdapterResolver<TContext>[];
+}
+/**
+ * Options for resolving and storing a locale in a transport-local store.
+ */
+export interface BindLocaleOptions<TContext> extends ResolveLocaleOptions<TContext> {
+    /** Store used to persist the selected locale metadata for the active context. */
+    readonly store: LocaleAdapterStore<TContext>;
+}
+/**
+ * Options for creating an `Accept-Language`-style header resolver without importing HTTP types.
+ */
+export interface HeaderLocaleResolverOptions<TContext> {
+    /** Reads the relevant header value from a WebSocket handshake, gRPC metadata object, or server request abstraction. */
+    readonly getHeader: (context: TContext) => string | readonly string[] | undefined;
+    /** Resolver source label returned with matches. Defaults to `accept-language`. */
+    readonly source?: string;
+}
+/**
+ * Options for creating an opt-in `Accept-Language` policy resolver without importing HTTP types.
+ */
+export interface HeaderLocalePolicyResolverOptions<TContext> extends HeaderLocaleResolverOptions<TContext>, AcceptLanguageLocalePolicyOptions {
+}
+/**
+ * Options for creating a query parameter resolver.
+ */
+export interface QueryLocaleResolverOptions<TContext> {
+    /** Reads a query value from a socket handshake, RPC metadata bag, CLI args object, or request abstraction. */
+    readonly getQueryValue: (context: TContext) => string | readonly string[] | undefined;
+    /** Resolver source label returned with matches. Defaults to `query`. */
+    readonly source?: string;
+}
+/**
+ * Options for creating a cookie resolver.
+ */
+export interface CookieLocaleResolverOptions<TContext> {
+    /** Reads a cookie value from the application-provided context abstraction. */
+    readonly getCookieValue: (context: TContext) => string | undefined;
+    /** Resolver source label returned with matches. Defaults to `cookie`. */
+    readonly source?: string;
+}
+/**
+ * Options for creating a storage-backed resolver.
+ */
+export interface StorageLocaleResolverOptions<TContext> {
+    /** Reads a stored locale from local storage, server session state, socket data, or CLI configuration. */
+    readonly getStoredLocale: (context: TContext) => string | undefined;
+    /** Resolver source label returned with matches. Defaults to `storage`. */
+    readonly source?: string;
+}
+/**
+ * Creates an in-memory per-object locale store backed by `WeakMap`.
+ *
+ * @returns A store suitable for socket, call, or request objects without mutating them.
+ */
+export declare function createWeakMapLocaleStore<TContext extends object>(): LocaleAdapterStore<TContext>;
+/**
+ * Stores locale metadata through an application-provided store abstraction.
+ *
+ * @param store Store that owns persistence for the transport context.
+ * @param context Transport context to update.
+ * @param locale Locale selected for the context.
+ * @param metadata Additional locale metadata such as a resolver source.
+ */
+export declare function setAdapterLocale<TContext>(store: LocaleAdapterStore<TContext>, context: TContext, locale: I18nLocale, metadata?: Omit<LocaleAdapterContext, 'locale'>): void;
+/**
+ * Reads locale metadata from an application-provided store abstraction.
+ *
+ * @param store Store that owns persistence for the transport context.
+ * @param context Transport context to inspect.
+ * @returns Stored locale metadata, or `undefined` when the context has no locale.
+ */
+export declare function getAdapterLocale<TContext>(store: LocaleAdapterStore<TContext>, context: TContext): LocaleAdapterContext | undefined;
+/**
+ * Runs an explicit non-HTTP resolver chain and returns selected locale metadata.
+ *
+ * @param context Transport context supplied by the application boundary.
+ * @param options Default locale, supported locales, and ordered resolvers.
+ * @returns 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 declare function resolveLocale<TContext>(context: TContext, options: ResolveLocaleOptions<TContext>): LocaleAdapterContext;
+/**
+ * Runs a resolver chain and stores the selected locale metadata in the provided transport-local store.
+ *
+ * @param context Transport context supplied by the application boundary.
+ * @param options Default locale, supported locales, ordered resolvers, and metadata store.
+ * @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 declare function bindLocale<TContext>(context: TContext, options: BindLocaleOptions<TContext>): LocaleAdapterContext;
+/**
+ * Creates a resolver that selects the first supported locale from an `Accept-Language`-style header.
+ *
+ * @param options Header accessor and optional source label.
+ * @returns Locale resolver that remains independent of HTTP, WebSocket, gRPC, and browser APIs.
+ */
+export declare function createHeaderLocaleResolver<TContext>(options: HeaderLocaleResolverOptions<TContext>): LocaleAdapterResolver<TContext>;
+/**
+ * Creates an opt-in header policy resolver that normalizes supported locale ranges and can select wildcard fallbacks.
+ *
+ * @param options Header accessor, source, normalization, and wildcard policy options.
+ * @returns Locale resolver that treats `*` as fallback-only and preserves explicit locale preferences first.
+ */
+export declare function createHeaderLocalePolicyResolver<TContext>(options: HeaderLocalePolicyResolverOptions<TContext>): LocaleAdapterResolver<TContext>;
+/**
+ * Creates a resolver that reads the first query parameter value from an application-owned abstraction.
+ *
+ * @param options Query accessor and optional source label.
+ * @returns Locale resolver that ignores empty, invalid, and unsupported query values.
+ */
+export declare function createQueryLocaleResolver<TContext>(options: QueryLocaleResolverOptions<TContext>): LocaleAdapterResolver<TContext>;
+/**
+ * Creates a resolver that reads locale from an application-owned cookie abstraction.
+ *
+ * @param options Cookie accessor and optional source label.
+ * @returns Locale resolver that ignores empty, invalid, and unsupported cookie values.
+ */
+export declare function createCookieLocaleResolver<TContext>(options: CookieLocaleResolverOptions<TContext>): LocaleAdapterResolver<TContext>;
+/**
+ * Creates a resolver that reads locale from storage, session, socket, call, request, or CLI configuration state.
+ *
+ * @param options Storage accessor and optional source label.
+ * @returns Locale resolver that ignores empty, invalid, and unsupported stored values.
+ */
+export declare function createStorageLocaleResolver<TContext>(options: StorageLocaleResolverOptions<TContext>): LocaleAdapterResolver<TContext>;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iCAAiC,EAMvC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B,CAAC,QAAQ;IAClD,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,gGAAgG;IAChG,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAClD,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,QAAQ,IAAI,CAAC,KAAK,EAAE,0BAA0B,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC;AAEvG;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,QAAQ;IAC1C,gEAAgE;IAChE,GAAG,CAAC,OAAO,EAAE,QAAQ,GAAG,oBAAoB,GAAG,SAAS,CAAC;IACzD,0DAA0D;IAC1D,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC5D;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,QAAQ;IAC5C,gGAAgG;IAChG,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAClD,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,qBAAqB,CAAC,QAAQ,CAAC,EAAE,CAAC;CACjE;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,QAAQ,CAAE,SAAQ,oBAAoB,CAAC,QAAQ,CAAC;IACjF,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B,CAAC,QAAQ;IACnD,uHAAuH;IACvH,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAClF,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iCAAiC,CAAC,QAAQ,CACzD,SAAQ,2BAA2B,CAAC,QAAQ,CAAC,EAC3C,iCAAiC;CAAG;AAExC;;GAEG;AACH,MAAM,WAAW,0BAA0B,CAAC,QAAQ;IAClD,8GAA8G;IAC9G,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACtF,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B,CAAC,QAAQ;IACnD,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,SAAS,CAAC;IACnE,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B,CAAC,QAAQ;IACpD,yGAAyG;IACzG,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,SAAS,CAAC;IACpE,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,SAAS,MAAM,KAAK,kBAAkB,CAAC,QAAQ,CAAC,CAWhG;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EACvC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EACnC,OAAO,EAAE,QAAQ,EACjB,MAAM,EAAE,UAAU,EAClB,QAAQ,GAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAM,GAClD,IAAI,CAEN;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EACvC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EACnC,OAAO,EAAE,QAAQ,GAChB,oBAAoB,GAAG,SAAS,CAElC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GAAG,oBAAoB,CAsBxH;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,CAAC,QAAQ,CAAC,GAAG,oBAAoB,CAIlH;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EACjD,OAAO,EAAE,2BAA2B,CAAC,QAAQ,CAAC,GAC7C,qBAAqB,CAAC,QAAQ,CAAC,CAgBjC;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EACvD,OAAO,EAAE,iCAAiC,CAAC,QAAQ,CAAC,GACnD,qBAAqB,CAAC,QAAQ,CAAC,CAiBjC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAChD,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,qBAAqB,CAAC,QAAQ,CAAC,CAajC;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EACjD,OAAO,EAAE,2BAA2B,CAAC,QAAQ,CAAC,GAC7C,qBAAqB,CAAC,QAAQ,CAAC,CAYjC;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAClD,OAAO,EAAE,4BAA4B,CAAC,QAAQ,CAAC,GAC9C,qBAAqB,CAAC,QAAQ,CAAC,CAYjC"}

package/dist/adapters.js

@@ -0,0 +1,266 @@
+import { isSupportedLocale, isValidLocale, normalizeLocaleResolverResult, parseLocalePreferences, selectLocaleFromAcceptLanguagePolicy } from './locale-resolution.js';
+
+/**
+ * Locale metadata resolved for a non-HTTP transport context.
+ */
+
+/**
+ * Input shared by opt-in non-HTTP locale resolvers.
+ */
+
+/**
+ * Result returned by one non-HTTP locale resolver.
+ */
+
+/**
+ * Explicit locale resolver used by `resolveLocale(...)` in application-defined order.
+ */
+
+/**
+ * Adapter-owned locale metadata store for transport contexts that have session, socket, call, or request state.
+ */
+
+/**
+ * Options for resolving a locale from an ordered non-HTTP resolver chain.
+ */
+
+/**
+ * Options for resolving and storing a locale in a transport-local store.
+ */
+
+/**
+ * Options for creating an `Accept-Language`-style header resolver without importing HTTP types.
+ */
+
+/**
+ * Options for creating an opt-in `Accept-Language` policy resolver without importing HTTP types.
+ */
+
+/**
+ * Options for creating a query parameter resolver.
+ */
+
+/**
+ * Options for creating a cookie resolver.
+ */
+
+/**
+ * Options for creating a storage-backed resolver.
+ */
+
+/**
+ * Creates an in-memory per-object locale store backed by `WeakMap`.
+ *
+ * @returns A store suitable for socket, call, or request objects without mutating them.
+ */
+export function createWeakMapLocaleStore() {
+  const locales = new WeakMap();
+  return {
+    get(context) {
+      return locales.get(context);
+    },
+    set(context, locale) {
+      locales.set(context, Object.freeze({
+        ...locale
+      }));
+    }
+  };
+}
+
+/**
+ * Stores locale metadata through an application-provided store abstraction.
+ *
+ * @param store Store that owns persistence for the transport context.
+ * @param context Transport context to update.
+ * @param locale Locale selected for the context.
+ * @param metadata Additional locale metadata such as a resolver source.
+ */
+export function setAdapterLocale(store, context, locale, metadata = {}) {
+  store.set(context, Object.freeze({
+    ...metadata,
+    locale
+  }));
+}
+
+/**
+ * Reads locale metadata from an application-provided store abstraction.
+ *
+ * @param store Store that owns persistence for the transport context.
+ * @param context Transport context to inspect.
+ * @returns Stored locale metadata, or `undefined` when the context has no locale.
+ */
+export function getAdapterLocale(store, context) {
+  return store.get(context);
+}
+
+/**
+ * Runs an explicit non-HTTP resolver chain and returns selected locale metadata.
+ *
+ * @param context Transport context supplied by the application boundary.
+ * @param options Default locale, supported locales, and ordered resolvers.
+ * @returns 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 resolveLocale(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;
+    }
+    return Object.freeze({
+      locale: result.locale,
+      source: result.source
+    });
+  }
+  return Object.freeze({
+    locale: options.defaultLocale,
+    source: 'default'
+  });
+}
+
+/**
+ * Runs a resolver chain and stores the selected locale metadata in the provided transport-local store.
+ *
+ * @param context Transport context supplied by the application boundary.
+ * @param options Default locale, supported locales, ordered resolvers, and metadata store.
+ * @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 bindLocale(context, options) {
+  const resolved = resolveLocale(context, options);
+  setAdapterLocale(options.store, context, resolved.locale, {
+    source: resolved.source
+  });
+  return getAdapterLocale(options.store, context) ?? resolved;
+}
+
+/**
+ * Creates a resolver that selects the first supported locale from an `Accept-Language`-style header.
+ *
+ * @param options Header accessor and optional source label.
+ * @returns Locale resolver that remains independent of HTTP, WebSocket, gRPC, and browser APIs.
+ */
+export function createHeaderLocaleResolver(options) {
+  const source = options.source ?? 'accept-language';
+  return ({
+    context,
+    supportedLocales
+  }) => {
+    for (const preference of parseLocalePreferences(options.getHeader(context))) {
+      if (preference.locale === '*') {
+        continue;
+      }
+      if (isSupportedLocale(preference.locale, supportedLocales)) {
+        return {
+          locale: preference.locale,
+          source
+        };
+      }
+    }
+    return undefined;
+  };
+}
+
+/**
+ * Creates an opt-in header policy resolver that normalizes supported locale ranges and can select wildcard fallbacks.
+ *
+ * @param options Header accessor, source, normalization, and wildcard policy options.
+ * @returns Locale resolver that treats `*` as fallback-only and preserves explicit locale preferences first.
+ */
+export function createHeaderLocalePolicyResolver(options) {
+  const source = options.source ?? 'accept-language';
+  return ({
+    context,
+    defaultLocale,
+    supportedLocales
+  }) => {
+    const locale = selectLocaleFromAcceptLanguagePolicy(parseLocalePreferences(options.getHeader(context)), defaultLocale, supportedLocales, options);
+    if (locale === undefined) {
+      return undefined;
+    }
+    return {
+      locale,
+      source
+    };
+  };
+}
+
+/**
+ * Creates a resolver that reads the first query parameter value from an application-owned abstraction.
+ *
+ * @param options Query accessor and optional source label.
+ * @returns Locale resolver that ignores empty, invalid, and unsupported query values.
+ */
+export function createQueryLocaleResolver(options) {
+  const source = options.source ?? 'query';
+  return ({
+    context,
+    supportedLocales
+  }) => {
+    const rawValue = options.getQueryValue(context);
+    const locale = Array.isArray(rawValue) ? rawValue[0] : rawValue;
+    if (locale === undefined || !isValidLocale(locale) || !isSupportedLocale(locale, supportedLocales)) {
+      return undefined;
+    }
+    return {
+      locale,
+      source
+    };
+  };
+}
+
+/**
+ * Creates a resolver that reads locale from an application-owned cookie abstraction.
+ *
+ * @param options Cookie accessor and optional source label.
+ * @returns Locale resolver that ignores empty, invalid, and unsupported cookie values.
+ */
+export function createCookieLocaleResolver(options) {
+  const source = options.source ?? 'cookie';
+  return ({
+    context,
+    supportedLocales
+  }) => {
+    const locale = options.getCookieValue(context);
+    if (locale === undefined || !isValidLocale(locale) || !isSupportedLocale(locale, supportedLocales)) {
+      return undefined;
+    }
+    return {
+      locale,
+      source
+    };
+  };
+}
+
+/**
+ * Creates a resolver that reads locale from storage, session, socket, call, request, or CLI configuration state.
+ *
+ * @param options Storage accessor and optional source label.
+ * @returns Locale resolver that ignores empty, invalid, and unsupported stored values.
+ */
+export function createStorageLocaleResolver(options) {
+  const source = options.source ?? 'storage';
+  return ({
+    context,
+    supportedLocales
+  }) => {
+    const locale = options.getStoredLocale(context);
+    if (locale === undefined || !isValidLocale(locale) || !isSupportedLocale(locale, supportedLocales)) {
+      return undefined;
+    }
+    return {
+      locale,
+      source
+    };
+  };
+}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+import { FluoError } from '@fluojs/core';
+import type { I18nErrorCode } from './types.js';
+/**
+ * Base error type for caller-visible i18n package failures.
+ */
+export declare class I18nError extends FluoError {
+    /** Stable i18n error code. */
+    readonly code: I18nErrorCode;
+    /**
+     * Creates an i18n package error with a stable code.
+     *
+     * @param message Human-readable error message.
+     * @param code Stable error code for programmatic handling.
+     */
+    constructor(message: string, code?: I18nErrorCode);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;GAEG;AACH,qBAAa,SAAU,SAAQ,SAAS;IACtC,8BAA8B;IAC9B,SAAiB,IAAI,EAAE,aAAa,CAAC;IAErC;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,aAA4B;CAGhE"}

package/dist/errors.js

@@ -0,0 +1,19 @@
+import { FluoError } from '@fluojs/core';
+/**
+ * Base error type for caller-visible i18n package failures.
+ */
+export class I18nError extends FluoError {
+  /** Stable i18n error code. */
+
+  /**
+   * Creates an i18n package error with a stable code.
+   *
+   * @param message Human-readable error message.
+   * @param code Stable error code for programmatic handling.
+   */
+  constructor(message, code = 'I18N_ERROR') {
+    super(message, {
+      code
+    });
+  }
+}

package/dist/http.d.ts

@@ -0,0 +1,120 @@
+import { type RequestContext } from '@fluojs/http';
+import { type AcceptLanguageLocalePolicyOptions } from './locale-resolution.js';
+import type { I18nLocale } from './types.js';
+/**
+ * Locale metadata stored on a fluo HTTP request context.
+ */
+export interface HttpLocaleContext {
+    /** Locale selected for the active request. */
+    readonly locale: I18nLocale;
+    /** Optional resolver name or application-defined source that selected the locale. */
+    readonly source?: string;
+}
+/**
+ * Parsed `Accept-Language` preference ordered by caller priority.
+ */
+export interface AcceptLanguagePreference {
+    /** Locale range from the header, such as `ko-KR`, `en`, or `*`. */
+    readonly locale: I18nLocale;
+    /** Normalized q-value between 0 and 1. */
+    readonly quality: number;
+}
+/**
+ * Input shared by explicit HTTP locale resolvers.
+ */
+export interface HttpLocaleResolverInput {
+    /** Current request context being resolved. */
+    readonly context: RequestContext;
+    /** Supported locale allow-list. Empty or omitted lists allow any syntactically valid locale. */
+    readonly supportedLocales?: readonly I18nLocale[];
+    /** Default locale used when no resolver selects a supported locale. */
+    readonly defaultLocale: I18nLocale;
+}
+/**
+ * Result returned by one HTTP locale resolver.
+ */
+export interface HttpLocaleResolverResult {
+    /** Locale selected by the resolver. */
+    readonly locale: I18nLocale;
+    /** Resolver name or application-defined source that selected the locale. */
+    readonly source?: string;
+}
+/**
+ * Explicit locale resolver used by `resolveHttpLocale(...)` in application-defined order.
+ */
+export type HttpLocaleResolver = (input: HttpLocaleResolverInput) => unknown;
+/**
+ * Options for resolving a request locale from an ordered resolver chain.
+ */
+export interface ResolveHttpLocaleOptions {
+    /** Supported locale allow-list. Empty or omitted lists allow any syntactically valid locale. */
+    readonly supportedLocales?: readonly I18nLocale[];
+    /** Default locale returned when no resolver selects a supported locale. */
+    readonly defaultLocale: I18nLocale;
+    /** Resolver chain executed in array order. */
+    readonly resolvers?: readonly HttpLocaleResolver[];
+}
+/**
+ * Options for creating an `Accept-Language` resolver.
+ */
+export interface AcceptLanguageLocaleResolverOptions {
+    /** Header name to inspect. Defaults to `accept-language`. */
+    readonly headerName?: string;
+    /** Resolver source label returned with matches. Defaults to `accept-language`. */
+    readonly source?: string;
+}
+/**
+ * Options for the opt-in `Accept-Language` policy resolver.
+ */
+export interface AcceptLanguageLocalePolicyResolverOptions extends AcceptLanguageLocaleResolverOptions, AcceptLanguageLocalePolicyOptions {
+}
+/**
+ * Request-context key used by `setHttpLocale(...)` and `getHttpLocale(...)`.
+ */
+export declare const HTTP_LOCALE_CONTEXT_KEY: import("@fluojs/http").ContextKey<HttpLocaleContext>;
+/**
+ * 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 declare function setHttpLocale(context: RequestContext, locale: I18nLocale, metadata?: Omit<HttpLocaleContext, 'locale'>): void;
+/**
+ * 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 declare function getHttpLocale(context: RequestContext): HttpLocaleContext | undefined;
+/**
+ * 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 declare function parseAcceptLanguage(header: string | readonly string[] | undefined): readonly AcceptLanguagePreference[];
+/**
+ * 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 declare function createAcceptLanguageLocaleResolver(options?: AcceptLanguageLocaleResolverOptions): HttpLocaleResolver;
+/**
+ * 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 declare function createAcceptLanguageLocalePolicyResolver(options?: AcceptLanguageLocalePolicyResolverOptions): HttpLocaleResolver;
+/**
+ * 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 declare function resolveHttpLocale(context: RequestContext, options: ResolveHttpLocaleOptions): HttpLocaleContext;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EAEpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,iCAAiC,EAMvC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,gGAAgG;IAChG,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAClD,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,uBAAuB,KAAK,OAAO,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,gGAAgG;IAChG,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAClD,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,mCAAmC;IAClD,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,yCAA0C,SAAQ,mCAAmC,EAAE,iCAAiC;CAAG;AAE5I;;GAEG;AACH,eAAO,MAAM,uBAAuB,sDAA+D,CAAC;AAepG;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,UAAU,EAClB,QAAQ,GAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAM,GAC/C,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,iBAAiB,GAAG,SAAS,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,SAAS,wBAAwB,EAAE,CAEvH;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,GAAE,mCAAwC,GAChD,kBAAkB,CAoBpB;AAED;;;;;GAKG;AACH,wBAAgB,wCAAwC,CACtD,OAAO,GAAE,yCAA8C,GACtD,kBAAkB,CAkBpB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAwB/G"}