@fluojs/i18n 1.0.0-beta.1

package/dist/locale-resolution.js

@@ -0,0 +1,201 @@
+/**
+ * Normalized locale candidate returned by HTTP or non-HTTP locale resolvers.
+ */
+
+/**
+ * Parsed `Accept-Language` preference with a validated locale range and q-value.
+ */
+
+/**
+ * Input passed to wildcard locale policy callbacks.
+ */
+
+/**
+ * Opt-in policy for resolving an `Accept-Language: *` fallback.
+ */
+
+/**
+ * Options for locale policy helpers that extend `Accept-Language` matching without changing defaults.
+ */
+
+const LOCALE_PATTERN = /^[A-Za-z]{1,8}(?:-[A-Za-z0-9]{1,8})*$/;
+const ACCEPT_LANGUAGE_QVALUE_PATTERN = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/;
+
+/**
+ * Checks whether a value is a syntactically valid locale identifier for resolver input.
+ *
+ * @param locale Value to validate as a locale identifier.
+ * @returns Whether the value is a string matching the locale grammar accepted by i18n resolvers.
+ */
+export function isValidLocale(locale) {
+  return typeof locale === 'string' && LOCALE_PATTERN.test(locale);
+}
+
+/**
+ * Checks whether a valid locale is allowed by an optional supported-locale list.
+ *
+ * @param locale Locale identifier to check.
+ * @param supportedLocales Optional list of supported locale identifiers.
+ * @returns Whether the locale is supported, or `true` when no supported-locale list is configured.
+ */
+export function isSupportedLocale(locale, supportedLocales) {
+  return supportedLocales === undefined || supportedLocales.length === 0 || supportedLocales.includes(locale);
+}
+
+/**
+ * Normalizes a valid locale candidate to the configured supported locale surface.
+ *
+ * @param locale Locale candidate from an explicit resolver or language range.
+ * @param supportedLocales Optional supported locale allow-list.
+ * @param allowBaseLocaleMatch Whether `en-US` may resolve to supported `en`.
+ * @returns The supported locale spelling selected by the caller, or `undefined` when unsupported.
+ */
+export function normalizeSupportedLocale(locale, supportedLocales, allowBaseLocaleMatch = true) {
+  if (supportedLocales === undefined || supportedLocales.length === 0) {
+    return locale;
+  }
+  const normalizedLocale = locale.toLowerCase();
+  const exact = supportedLocales.find(supportedLocale => supportedLocale.toLowerCase() === normalizedLocale);
+  if (exact !== undefined) {
+    return exact;
+  }
+  if (!allowBaseLocaleMatch) {
+    return undefined;
+  }
+  const localeSegments = normalizedLocale.split('-');
+  while (localeSegments.length > 1) {
+    localeSegments.pop();
+    const parentLocale = localeSegments.join('-');
+    const supportedParent = supportedLocales.find(supportedLocale => supportedLocale.toLowerCase() === parentLocale);
+    if (supportedParent !== undefined) {
+      return supportedParent;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Normalizes resolver output into a locale candidate object when the output shape is supported.
+ *
+ * @param result Resolver output to normalize.
+ * @returns A locale candidate, or `undefined` when the resolver output should be ignored.
+ */
+export function normalizeLocaleResolverResult(result) {
+  if (result === undefined) {
+    return undefined;
+  }
+  if (typeof result === 'string') {
+    return {
+      locale: result
+    };
+  }
+  if (typeof result !== 'object' || result === null || !Object.hasOwn(result, 'locale')) {
+    return undefined;
+  }
+  const candidate = result;
+  if (candidate.source !== undefined && typeof candidate.source !== 'string') {
+    return undefined;
+  }
+  return {
+    locale: candidate.locale,
+    source: candidate.source
+  };
+}
+function parseAcceptLanguageQuality(parameters) {
+  let quality = 1;
+  let hasQuality = false;
+  for (const parameter of parameters) {
+    const normalizedParameter = parameter.trim();
+    const qualityMatch = /^q=(.+)$/i.exec(normalizedParameter);
+    if (qualityMatch === null || hasQuality) {
+      return undefined;
+    }
+    const [, value] = qualityMatch;
+    if (value === undefined || !ACCEPT_LANGUAGE_QVALUE_PATTERN.test(value)) {
+      return undefined;
+    }
+    hasQuality = true;
+    quality = Number(value);
+  }
+  return quality;
+}
+
+/**
+ * Parses one or more `Accept-Language` header values into sorted locale preferences.
+ *
+ * @param header Header value or values to parse.
+ * @returns Valid preferences sorted by descending q-value and original header order.
+ */
+export function parseLocalePreferences(header) {
+  const rawHeader = typeof header === 'string' ? header : header?.join(',');
+  if (rawHeader === undefined || rawHeader.trim() === '') {
+    return [];
+  }
+  const preferences = [];
+  for (const [index, rawPart] of rawHeader.split(',').entries()) {
+    const [rawLocale, ...parameters] = rawPart.split(';');
+    const locale = rawLocale?.trim();
+    if (locale === undefined || locale === '' || locale !== '*' && !isValidLocale(locale)) {
+      continue;
+    }
+    const quality = parseAcceptLanguageQuality(parameters);
+    if (quality !== undefined && quality > 0) {
+      preferences.push({
+        index,
+        locale,
+        quality
+      });
+    }
+  }
+  return [...preferences].sort((left, right) => right.quality - left.quality || left.index - right.index).map(({
+    locale,
+    quality
+  }) => ({
+    locale,
+    quality
+  }));
+}
+function resolveWildcardLocale(policy, defaultLocale, supportedLocales) {
+  if (policy === 'defaultLocale') {
+    return normalizeSupportedLocale(defaultLocale, supportedLocales, false);
+  }
+  if (policy === 'firstSupportedLocale') {
+    return supportedLocales?.[0] ?? defaultLocale;
+  }
+  return policy({
+    defaultLocale,
+    supportedLocales
+  });
+}
+
+/**
+ * Selects a locale from parsed `Accept-Language` preferences using opt-in policy rules.
+ *
+ * @param preferences Parsed header preferences ordered by q-value.
+ * @param defaultLocale Default locale configured for resolver fallback.
+ * @param supportedLocales Optional supported locale allow-list.
+ * @param options Wildcard and normalization policy options.
+ * @returns The selected supported locale, or `undefined` when no policy-selected locale matches.
+ */
+export function selectLocaleFromAcceptLanguagePolicy(preferences, defaultLocale, supportedLocales, options = {}) {
+  const allowBaseLocaleMatch = options.normalizeToSupportedLocale ?? true;
+  let hasWildcard = false;
+  for (const preference of preferences) {
+    if (preference.locale === '*') {
+      hasWildcard = true;
+      continue;
+    }
+    const normalizedLocale = normalizeSupportedLocale(preference.locale, supportedLocales, allowBaseLocaleMatch);
+    if (normalizedLocale !== undefined) {
+      return normalizedLocale;
+    }
+  }
+  if (!hasWildcard || options.wildcardLocale === undefined) {
+    return undefined;
+  }
+  const wildcardLocale = resolveWildcardLocale(options.wildcardLocale, defaultLocale, supportedLocales);
+  if (wildcardLocale === undefined || !isValidLocale(wildcardLocale)) {
+    return undefined;
+  }
+  return normalizeSupportedLocale(wildcardLocale, supportedLocales, allowBaseLocaleMatch);
+}

package/dist/module.d.ts

@@ -0,0 +1,22 @@
+import type { I18nModuleOptions } from './types.js';
+/**
+ * Module facade that registers the fluo-native core i18n service surface.
+ */
+export declare class I18nModule {
+    /**
+     * Creates a module class that registers `I18nService` with captured root options.
+     *
+     * @param options Root i18n module options for catalogs, fallback behavior, and service registration.
+     * @returns A module type that can be listed in `imports` during bootstrap.
+     *
+     * @example
+     * ```ts
+     * @Module({
+     *   imports: [I18nModule.forRoot({ defaultLocale: 'en' })],
+     * })
+     * class AppModule {}
+     * ```
+     */
+    static forRoot(options?: I18nModuleOptions): new () => I18nModule;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAWpD;;GAEG;AACH,qBAAa,UAAU;IACrB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,UAAU;CAsBlE"}

package/dist/module.js

@@ -0,0 +1,60 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Inject } from '@fluojs/core';
+import { defineModuleMetadata } from '@fluojs/core/internal';
+import { snapshotI18nModuleOptions } from './options.js';
+import { I18nService } from './service.js';
+const I18N_MODULE_OPTIONS = Symbol('fluo.i18n.module-options');
+let _I18nServiceFactory;
+class I18nServiceFactory extends I18nService {
+  static {
+    [_I18nServiceFactory, _initClass] = _applyDecs(this, [Inject(I18N_MODULE_OPTIONS)], [], 0, void 0, I18nService).c;
+  }
+  constructor(options) {
+    super(options);
+  }
+  static {
+    _initClass();
+  }
+}
+
+/**
+ * Module facade that registers the fluo-native core i18n service surface.
+ */
+export class I18nModule {
+  /**
+   * Creates a module class that registers `I18nService` with captured root options.
+   *
+   * @param options Root i18n module options for catalogs, fallback behavior, and service registration.
+   * @returns A module type that can be listed in `imports` during bootstrap.
+   *
+   * @example
+   * ```ts
+   * @Module({
+   *   imports: [I18nModule.forRoot({ defaultLocale: 'en' })],
+   * })
+   * class AppModule {}
+   * ```
+   */
+  static forRoot(options) {
+    const moduleOptions = snapshotI18nModuleOptions(options);
+    class I18nModuleImpl extends I18nModule {}
+    const providers = [{
+      provide: I18N_MODULE_OPTIONS,
+      useValue: moduleOptions
+    }, {
+      provide: I18nService,
+      useClass: _I18nServiceFactory
+    }];
+    defineModuleMetadata(I18nModuleImpl, {
+      global: moduleOptions.global ?? true,
+      exports: [I18nService],
+      providers
+    });
+    return I18nModuleImpl;
+  }
+}

package/dist/options.d.ts

@@ -0,0 +1,9 @@
+import type { I18nModuleOptions } from './types.js';
+/**
+ * Creates a detached copy of root i18n module options.
+ *
+ * @param options Root i18n module options provided by the caller.
+ * @returns A detached options snapshot for module registration or standalone service creation.
+ */
+export declare function snapshotI18nModuleOptions(options?: I18nModuleOptions): I18nModuleOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAgF,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAwMlI;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,iBAAsB,GAAG,iBAAiB,CAU5F"}

package/dist/options.js

@@ -0,0 +1,169 @@
+import { I18nError } from './errors.js';
+function isPlainObject(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function assertLocale(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new I18nError(`${label} must be a non-empty string.`, 'I18N_INVALID_LOCALE_CONFIG');
+  }
+}
+function assertLocaleList(value, label) {
+  if (!Array.isArray(value)) {
+    throw new I18nError(`${label} must be an array of locale strings.`, 'I18N_INVALID_LOCALE_CONFIG');
+  }
+  for (const locale of value) {
+    assertLocale(locale, label);
+  }
+}
+function assertSupportedLocale(locale, supportedLocales, label) {
+  if (supportedLocales !== undefined && !supportedLocales.includes(locale)) {
+    throw new I18nError(`${label} must be listed in supportedLocales.`, 'I18N_INVALID_LOCALE_CONFIG');
+  }
+}
+function snapshotIntlOptions(value, path) {
+  if (!isPlainObject(value)) {
+    throw new I18nError(`${path} must be a plain object option bag.`, 'I18N_INVALID_OPTIONS');
+  }
+  return Object.freeze({
+    ...value
+  });
+}
+function snapshotNamedIntlFormats(value, path) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!isPlainObject(value)) {
+    throw new I18nError(`${path} must be a named format map.`, 'I18N_INVALID_OPTIONS');
+  }
+  const snapshot = {};
+  for (const [name, options] of Object.entries(value)) {
+    if (name.trim() === '') {
+      throw new I18nError(`${path} contains an empty format name.`, 'I18N_INVALID_OPTIONS');
+    }
+    snapshot[name] = snapshotIntlOptions(options, `${path}.${name}`);
+  }
+  return Object.freeze(snapshot);
+}
+function snapshotFormats(formats) {
+  if (formats === undefined) {
+    return undefined;
+  }
+  if (!isPlainObject(formats)) {
+    throw new I18nError('formats must be a plain object when provided.', 'I18N_INVALID_OPTIONS');
+  }
+  return Object.freeze({
+    dateTime: snapshotNamedIntlFormats(formats.dateTime, 'formats.dateTime'),
+    list: snapshotNamedIntlFormats(formats.list, 'formats.list'),
+    number: snapshotNamedIntlFormats(formats.number, 'formats.number'),
+    relativeTime: snapshotNamedIntlFormats(formats.relativeTime, 'formats.relativeTime')
+  });
+}
+function snapshotMessageTree(value, path) {
+  if (!isPlainObject(value)) {
+    throw new I18nError(`${path} must be a plain object message tree.`, 'I18N_INVALID_CATALOG');
+  }
+  const snapshot = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (key.trim() === '') {
+      throw new I18nError(`${path} contains an empty message key segment.`, 'I18N_INVALID_CATALOG');
+    }
+    if (typeof entry === 'string') {
+      snapshot[key] = entry;
+      continue;
+    }
+    if (isPlainObject(entry)) {
+      snapshot[key] = snapshotMessageTree(entry, `${path}.${key}`);
+      continue;
+    }
+    throw new I18nError(`${path}.${key} must be a string or nested message tree.`, 'I18N_INVALID_CATALOG');
+  }
+  return Object.freeze(snapshot);
+}
+function snapshotCatalogs(catalogs, supportedLocales) {
+  if (catalogs === undefined) {
+    return undefined;
+  }
+  if (!isPlainObject(catalogs)) {
+    throw new I18nError('catalogs must be a locale-scoped object.', 'I18N_INVALID_CATALOG');
+  }
+  const snapshot = {};
+  for (const [locale, tree] of Object.entries(catalogs)) {
+    assertLocale(locale, 'catalog locale');
+    assertSupportedLocale(locale, supportedLocales, 'catalog locale');
+    snapshot[locale] = snapshotMessageTree(tree, `catalogs.${locale}`);
+  }
+  return Object.freeze(snapshot);
+}
+function snapshotFallbackLocales(fallbackLocales, supportedLocales) {
+  if (fallbackLocales === undefined) {
+    return undefined;
+  }
+  if (Array.isArray(fallbackLocales)) {
+    assertLocaleList(fallbackLocales, 'fallbackLocales');
+    for (const fallbackLocale of fallbackLocales) {
+      assertSupportedLocale(fallbackLocale, supportedLocales, 'fallbackLocales locale');
+    }
+    return Object.freeze([...fallbackLocales]);
+  }
+  if (!isPlainObject(fallbackLocales)) {
+    throw new I18nError('fallbackLocales must be an array or locale map.', 'I18N_INVALID_LOCALE_CONFIG');
+  }
+  const snapshot = {};
+  for (const [locale, chain] of Object.entries(fallbackLocales)) {
+    assertLocale(locale, 'fallbackLocales locale');
+    assertSupportedLocale(locale, supportedLocales, 'fallbackLocales locale');
+    assertLocaleList(chain, `fallbackLocales.${locale}`);
+    for (const fallbackLocale of chain) {
+      assertSupportedLocale(fallbackLocale, supportedLocales, `fallbackLocales.${locale} locale`);
+    }
+    snapshot[locale] = Object.freeze([...chain]);
+  }
+  return Object.freeze(snapshot);
+}
+function validateModuleOptions(options) {
+  if (!isPlainObject(options)) {
+    throw new I18nError('i18n module options must be a plain object.', 'I18N_INVALID_OPTIONS');
+  }
+  if (options.defaultLocale !== undefined) {
+    assertLocale(options.defaultLocale, 'defaultLocale');
+  }
+  if (options.global !== undefined && typeof options.global !== 'boolean') {
+    throw new I18nError('global must be a boolean when provided.', 'I18N_INVALID_OPTIONS');
+  }
+  if (options.missingMessage !== undefined && typeof options.missingMessage !== 'function') {
+    throw new I18nError('missingMessage must be a function when provided.', 'I18N_INVALID_OPTIONS');
+  }
+  if (options.formats !== undefined && !isPlainObject(options.formats)) {
+    throw new I18nError('formats must be a plain object when provided.', 'I18N_INVALID_OPTIONS');
+  }
+  if (options.supportedLocales !== undefined) {
+    assertLocaleList(options.supportedLocales, 'supportedLocales');
+    if (options.defaultLocale !== undefined) {
+      assertSupportedLocale(options.defaultLocale, options.supportedLocales, 'defaultLocale');
+    }
+  }
+  if (options.catalogs !== undefined && options.defaultLocale === undefined) {
+    throw new I18nError('defaultLocale is required when catalogs are configured.', 'I18N_INVALID_OPTIONS');
+  }
+}
+
+/**
+ * Creates a detached copy of root i18n module options.
+ *
+ * @param options Root i18n module options provided by the caller.
+ * @returns A detached options snapshot for module registration or standalone service creation.
+ */
+export function snapshotI18nModuleOptions(options = {}) {
+  validateModuleOptions(options);
+  return Object.freeze({
+    ...options,
+    catalogs: snapshotCatalogs(options.catalogs, options.supportedLocales),
+    fallbackLocales: snapshotFallbackLocales(options.fallbackLocales, options.supportedLocales),
+    formats: snapshotFormats(options.formats),
+    supportedLocales: options.supportedLocales ? Object.freeze([...options.supportedLocales]) : undefined
+  });
+}

package/dist/service.d.ts

@@ -0,0 +1,104 @@
+import type { I18nCurrencyFormatOptions, I18nDateTimeFormatOptions, I18nListFormatOptions, I18nLocale, I18nModuleOptions, I18nNumberFormatOptions, I18nRelativeTimeFormatOptions, I18nTranslateOptions } from './types.js';
+/**
+ * Framework-agnostic core translation service backed by locale-scoped message catalogs.
+ *
+ * @remarks
+ * Locale selection is explicit per call. The core service performs deterministic catalog lookup and string
+ * interpolation only; request locale detection, loaders, ICU/messageformat, and framework adapters remain out of scope.
+ */
+export declare class I18nService {
+    private readonly options;
+    /**
+     * Creates a service with a detached options snapshot.
+     *
+     * @param options Root i18n options captured at the application boundary.
+     */
+    constructor(options?: I18nModuleOptions);
+    /**
+     * Returns a detached copy of the root i18n options snapshot.
+     *
+     * @returns The captured i18n module options without exposing mutable service internals.
+     */
+    snapshotOptions(): I18nModuleOptions;
+    /**
+     * Returns the deterministic locale chain used for a translation request.
+     *
+     * @param locale Explicit caller locale to resolve first.
+     * @returns Locale chain ordered as requested locale, configured fallback chain, then default locale.
+     * @throws {I18nError} When the locale is invalid or outside `supportedLocales`.
+     */
+    resolveLocales(locale: I18nLocale): readonly I18nLocale[];
+    private resolveNamedOptions;
+    /**
+     * Formats a date or timestamp for an explicit locale using `Intl.DateTimeFormat`.
+     *
+     * @param value Date instance or epoch timestamp accepted by `Intl.DateTimeFormat`.
+     * @param options Explicit locale, optional named format, and inline date/time options.
+     * @returns Locale-formatted date/time text from the host standard `Intl` implementation.
+     * @throws {I18nError} When options are invalid or a named date/time format is missing.
+     */
+    formatDateTime(value: Date | number, options: I18nDateTimeFormatOptions): string;
+    /**
+     * Formats a number for an explicit locale using `Intl.NumberFormat`.
+     *
+     * @param value Number value passed to `Intl.NumberFormat`.
+     * @param options Explicit locale, optional named format, and inline number options.
+     * @returns Locale-formatted number text from the host standard `Intl` implementation.
+     * @throws {I18nError} When options are invalid or a named number format is missing.
+     */
+    formatNumber(value: number, options: I18nNumberFormatOptions): string;
+    /**
+     * Formats a currency amount for an explicit locale using `Intl.NumberFormat`.
+     *
+     * @param value Currency amount passed to `Intl.NumberFormat`.
+     * @param options Explicit locale, ISO 4217 currency code, optional named format, and inline number options.
+     * @returns Locale-formatted currency text from the host standard `Intl` implementation.
+     * @throws {I18nError} When options are invalid or a named number format is missing.
+     */
+    formatCurrency(value: number, options: I18nCurrencyFormatOptions): string;
+    /**
+     * Formats a ratio as a percent for an explicit locale using `Intl.NumberFormat`.
+     *
+     * @param value Ratio value passed to `Intl.NumberFormat` with `style: 'percent'`.
+     * @param options Explicit locale, optional named format, and inline number options.
+     * @returns Locale-formatted percent text from the host standard `Intl` implementation.
+     * @throws {I18nError} When options are invalid or a named number format is missing.
+     */
+    formatPercent(value: number, options: I18nNumberFormatOptions): string;
+    /**
+     * Formats a string list for an explicit locale using `Intl.ListFormat`.
+     *
+     * @param values List item strings passed to `Intl.ListFormat`.
+     * @param options Explicit locale, optional named format, and inline list options.
+     * @returns Locale-formatted list text from the host standard `Intl` implementation.
+     * @throws {I18nError} When options are invalid or a named list format is missing.
+     */
+    formatList(values: readonly string[], options: I18nListFormatOptions): string;
+    /**
+     * Formats a relative time value for an explicit locale using `Intl.RelativeTimeFormat`.
+     *
+     * @param value Numeric offset passed to `Intl.RelativeTimeFormat`.
+     * @param unit Relative time unit such as `day`, `hour`, or `minute`.
+     * @param options Explicit locale, optional named format, and inline relative time options.
+     * @returns Locale-formatted relative time text from the host standard `Intl` implementation.
+     * @throws {I18nError} When options are invalid or a named relative time format is missing.
+     */
+    formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options: I18nRelativeTimeFormatOptions): string;
+    /**
+     * Resolves and interpolates a catalog message for an explicit locale.
+     *
+     * @param key Dot-path catalog key, optionally prefixed by `options.namespace`.
+     * @param options Per-call locale, interpolation values, and default value.
+     * @returns The resolved catalog message, default value, or missing-message hook result.
+     * @throws {I18nError} When options are invalid or the message cannot be resolved.
+     */
+    translate(key: string, options: I18nTranslateOptions): string;
+}
+/**
+ * Creates a standalone i18n service without registering a fluo module.
+ *
+ * @param options Root i18n options for the standalone service instance.
+ * @returns An `I18nService` configured with a detached options snapshot.
+ */
+export declare function createI18n(options?: I18nModuleOptions): I18nService;
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,yBAAyB,EACzB,yBAAyB,EAEzB,qBAAqB,EACrB,UAAU,EAEV,iBAAiB,EACjB,uBAAuB,EACvB,6BAA6B,EAC7B,oBAAoB,EACrB,MAAM,YAAY,CAAC;AA+IpB;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAE5C;;;;OAIG;gBACS,OAAO,GAAE,iBAAsB;IAI3C;;;;OAIG;IACH,eAAe,IAAI,iBAAiB;IAIpC;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,UAAU,EAAE;IA2BzD,OAAO,CAAC,mBAAmB;IAkB3B;;;;;;;OAOG;IACH,cAAc,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,EAAE,OAAO,EAAE,yBAAyB,GAAG,MAAM;IAWhF;;;;;;;OAOG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,MAAM;IAWrE;;;;;;;OAOG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,GAAG,MAAM;IAiBzE;;;;;;;OAOG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,GAAG,MAAM;IAWtE;;;;;;;OAOG;IACH,UAAU,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM;IAY7E;;;;;;;;OAQG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,sBAAsB,EAAE,OAAO,EAAE,6BAA6B,GAAG,MAAM;IAWpH;;;;;;;OAOG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM;CAoC9D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,WAAW,CAEvE"}