@fluojs/i18n 1.0.0-beta.1

package/dist/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Locale identifier accepted by the i18n package surface.
+ */
+export type I18nLocale = string;
+/**
+ * Dot-path translation key resolved from a locale-scoped message catalog.
+ */
+export type I18nTranslationKey = string;
+/**
+ * Stable i18n package error codes for caller-visible failures.
+ */
+export type I18nErrorCode = 'I18N_ERROR' | 'I18N_INVALID_CATALOG' | 'I18N_INVALID_LOADER_OPTIONS' | 'I18N_INVALID_LOCALE_CONFIG' | 'I18N_INVALID_MESSAGE_FORMAT' | 'I18N_INVALID_OPTIONS' | 'I18N_LOADER_ABORTED' | 'I18N_LOADER_FAILED' | 'I18N_LOADER_TIMEOUT' | 'I18N_MISSING_CATALOG' | 'I18N_MISSING_MESSAGE';
+/**
+ * Named `Intl.DateTimeFormat` option bags captured during i18n registration.
+ */
+export type I18nNamedDateTimeFormats = Readonly<Record<string, Intl.DateTimeFormatOptions>>;
+/**
+ * Named `Intl.NumberFormat` option bags captured during i18n registration.
+ */
+export type I18nNamedNumberFormats = Readonly<Record<string, Intl.NumberFormatOptions>>;
+/**
+ * Named `Intl.ListFormat` option bags captured during i18n registration.
+ */
+export type I18nNamedListFormats = Readonly<Record<string, Intl.ListFormatOptions>>;
+/**
+ * Named `Intl.RelativeTimeFormat` option bags captured during i18n registration.
+ */
+export type I18nNamedRelativeTimeFormats = Readonly<Record<string, Intl.RelativeTimeFormatOptions>>;
+/**
+ * Reusable named option groups for standard `Intl` formatters.
+ */
+export interface I18nFormatOptions {
+    /** Named date/time format option bags. */
+    readonly dateTime?: I18nNamedDateTimeFormats;
+    /** Named number, currency, and percent format option bags. */
+    readonly number?: I18nNamedNumberFormats;
+    /** Named list format option bags. */
+    readonly list?: I18nNamedListFormats;
+    /** Named relative time format option bags. */
+    readonly relativeTime?: I18nNamedRelativeTimeFormats;
+}
+/**
+ * Common per-call options for helpers backed by standard `Intl` formatters.
+ */
+export interface I18nFormatterOptions {
+    /** Locale passed directly to the underlying `Intl` formatter. */
+    readonly locale: I18nLocale;
+    /** Optional named format option bag registered in `I18nModuleOptions.formats`. */
+    readonly format?: string;
+}
+/**
+ * Per-call date/time formatting options.
+ */
+export interface I18nDateTimeFormatOptions extends I18nFormatterOptions {
+    /** Inline `Intl.DateTimeFormat` options merged after the named option bag. */
+    readonly options?: Intl.DateTimeFormatOptions;
+}
+/**
+ * Per-call number, currency, and percent formatting options.
+ */
+export interface I18nNumberFormatOptions extends I18nFormatterOptions {
+    /** Inline `Intl.NumberFormat` options merged after the named option bag. */
+    readonly options?: Intl.NumberFormatOptions;
+}
+/**
+ * Per-call currency formatting options.
+ */
+export interface I18nCurrencyFormatOptions extends I18nNumberFormatOptions {
+    /** ISO 4217 currency code passed to `Intl.NumberFormat`. */
+    readonly currency: string;
+}
+/**
+ * Per-call list formatting options.
+ */
+export interface I18nListFormatOptions extends I18nFormatterOptions {
+    /** Inline `Intl.ListFormat` options merged after the named option bag. */
+    readonly options?: Intl.ListFormatOptions;
+}
+/**
+ * Per-call relative time formatting options.
+ */
+export interface I18nRelativeTimeFormatOptions extends I18nFormatterOptions {
+    /** Inline `Intl.RelativeTimeFormat` options merged after the named option bag. */
+    readonly options?: Intl.RelativeTimeFormatOptions;
+}
+/**
+ * Interpolation values available to simple `{{ name }}` placeholders.
+ */
+export type I18nInterpolationValues = Readonly<Record<string, string | number | boolean | null | undefined>>;
+/**
+ * Nested message tree for one locale.
+ */
+export interface I18nMessageTree {
+    /** Message leaf or nested message tree keyed by path segment. */
+    readonly [key: string]: string | I18nMessageTree;
+}
+/**
+ * Canonical locale-scoped catalog map consumed by the core translation service.
+ */
+export type I18nMessageCatalogs = Readonly<Record<I18nLocale, I18nMessageTree>>;
+/**
+ * Fallback locale chain applied globally or per requested locale.
+ */
+export type I18nFallbackLocales = readonly I18nLocale[] | Readonly<Record<I18nLocale, readonly I18nLocale[]>>;
+/**
+ * Context passed to the missing-message hook after catalog/default fallback resolution fails.
+ */
+export interface I18nMissingMessageContext {
+    /** Requested locale supplied explicitly by the translation caller. */
+    readonly locale: I18nLocale;
+    /** Translation key after optional namespace prefixing. */
+    readonly key: I18nTranslationKey;
+    /** Deterministic locale chain inspected before the hook was invoked. */
+    readonly attemptedLocales: readonly I18nLocale[];
+    /** Interpolation values supplied by the caller. */
+    readonly values?: I18nInterpolationValues;
+}
+/**
+ * Hook invoked when no message and no default value can satisfy a translation request.
+ */
+export type I18nMissingMessageHandler = (context: I18nMissingMessageContext) => string | undefined;
+/**
+ * Per-call translation options. Locale is always explicit in the framework-agnostic core.
+ */
+export interface I18nTranslateOptions {
+    /** Locale to resolve first. */
+    readonly locale: I18nLocale;
+    /** Optional namespace prefix, resolved as `${namespace}.${key}`. */
+    readonly namespace?: I18nTranslationKey;
+    /** Values interpolated into `{{ name }}` placeholders. */
+    readonly values?: I18nInterpolationValues;
+    /** Caller-provided fallback returned before the missing-message hook is invoked. */
+    readonly defaultValue?: string;
+}
+/**
+ * Root i18n module options captured during package registration.
+ */
+export interface I18nModuleOptions {
+    /** Default fallback locale used after the configured locale chain. */
+    defaultLocale?: I18nLocale;
+    /** Locale-scoped message catalogs. */
+    catalogs?: I18nMessageCatalogs;
+    /** Supported locale allow-list for configuration and per-call locale validation. */
+    supportedLocales?: readonly I18nLocale[];
+    /** Global or per-locale deterministic fallback chain inspected before the default locale. */
+    fallbackLocales?: I18nFallbackLocales;
+    /** Hook invoked when no catalog entry and no default value can satisfy a translation request. */
+    missingMessage?: I18nMissingMessageHandler;
+    /** Reusable named `Intl` formatter option bags captured as immutable service-owned snapshots. */
+    formats?: I18nFormatOptions;
+    /** Whether the module should expose `I18nService` globally. Defaults to `true`. */
+    global?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAExC;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,sBAAsB,GACtB,6BAA6B,GAC7B,4BAA4B,GAC5B,6BAA6B,GAC7B,sBAAsB,GACtB,qBAAqB,GACrB,oBAAoB,GACpB,qBAAqB,GACrB,sBAAsB,GACtB,sBAAsB,CAAC;AAE3B;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC;AAE5F;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;AAExF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAEpF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,yBAAyB,CAAC,CAAC,CAAC;AAEpG;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IAC7C,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IACzC,qCAAqC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAC;IACrC,8CAA8C;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,4BAA4B,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,oBAAoB;IACrE,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,qBAAqB,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,oBAAoB;IACnE,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,uBAAuB;IACxE,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,iBAAiB,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,6BAA8B,SAAQ,oBAAoB;IACzE,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,yBAAyB,CAAC;CACnD;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC;AAE7G;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC;AAEhF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,UAAU,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC,CAAC,CAAC;AAE9G;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC;IACjC,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,EAAE,SAAS,UAAU,EAAE,CAAC;IACjD,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,EAAE,yBAAyB,KAAK,MAAM,GAAG,SAAS,CAAC;AAEnG;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,uBAAuB,CAAC;IAC1C,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACzC,6FAA6F;IAC7F,eAAe,CAAC,EAAE,mBAAmB,CAAC;IACtC,iGAAiG;IACjG,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAC3C,iGAAiG;IACjG,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,74 @@
+import { DtoValidationError, type ValidationIssue } from '@fluojs/validation';
+import type { I18nLocale, I18nTranslationKey } from './types.js';
+import type { I18nService } from './service.js';
+/**
+ * Context used to derive translation keys for one validation issue.
+ */
+export interface ValidationIssueTranslationKeyContext {
+    /** Validation issue being localized. */
+    readonly issue: ValidationIssue;
+    /** Zero-based index of the issue in the caller-provided issue list. */
+    readonly index: number;
+}
+/**
+ * Builds candidate i18n translation keys for one validation issue.
+ */
+export type ValidationIssueTranslationKeyBuilder = (context: ValidationIssueTranslationKeyContext) => readonly I18nTranslationKey[];
+/**
+ * Options for opt-in validation issue localization.
+ */
+export interface LocalizeValidationIssuesOptions {
+    /** Locale used for validation issue message lookup. */
+    readonly locale: I18nLocale;
+    /** Optional namespace passed to `I18nService.translate(...)`. Defaults to `validation`. */
+    readonly namespace?: I18nTranslationKey;
+    /** Optional prefix prepended to generated candidate keys. */
+    readonly keyPrefix?: I18nTranslationKey;
+    /** Custom key builder for applications that own a different catalog shape. */
+    readonly keyBuilder?: ValidationIssueTranslationKeyBuilder;
+    /** Whether missing translations should preserve the original issue message. Defaults to `true`. */
+    readonly fallbackToIssueMessage?: boolean;
+}
+/**
+ * Creates default translation key candidates for a validation issue.
+ *
+ * @remarks
+ * Candidate order is most-specific to least-specific: `source.field.code`, `field.code`, `source.code`, then `code`.
+ * The optional `keyPrefix` is prepended to each candidate. Field paths are preserved as authored by
+ * `@fluojs/validation`, allowing catalogs to mirror dot/bracket validation paths explicitly.
+ *
+ * @param issue Validation issue to map into translation keys.
+ * @param keyPrefix Optional catalog prefix prepended before generated keys.
+ * @returns Ordered translation key candidates.
+ */
+export declare function createValidationIssueTranslationKeys(issue: ValidationIssue, keyPrefix?: I18nTranslationKey): readonly I18nTranslationKey[];
+/**
+ * Localizes one validation issue by resolving explicit translation key candidates.
+ *
+ * @param i18n I18n service used for catalog lookup.
+ * @param issue Validation issue whose message should be localized.
+ * @param options Explicit locale and optional key mapping controls.
+ * @param index Zero-based index used only by custom key builders.
+ * @returns A new validation issue with a localized message when a candidate resolves.
+ * @throws {I18nError} When no translation resolves and `fallbackToIssueMessage` is `false`.
+ */
+export declare function localizeValidationIssue(i18n: I18nService, issue: ValidationIssue, options: LocalizeValidationIssuesOptions, index?: number): ValidationIssue;
+/**
+ * Localizes validation issues without mutating the original issue objects.
+ *
+ * @param i18n I18n service used for catalog lookup.
+ * @param issues Validation issues from `@fluojs/validation`.
+ * @param options Explicit locale and optional key mapping controls.
+ * @returns Localized validation issue snapshots.
+ */
+export declare function localizeValidationIssues(i18n: I18nService, issues: readonly ValidationIssue[], options: LocalizeValidationIssuesOptions): readonly ValidationIssue[];
+/**
+ * Creates a new `DtoValidationError` with localized issue messages.
+ *
+ * @param i18n I18n service used for catalog lookup.
+ * @param error Validation error from `@fluojs/validation`.
+ * @param options Explicit locale and optional key mapping controls.
+ * @returns A new validation error that preserves the original top-level error message and localized issue snapshots.
+ */
+export declare function localizeDtoValidationError(i18n: I18nService, error: DtoValidationError, options: LocalizeValidationIssuesOptions): DtoValidationError;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG9E,OAAO,KAAK,EAA2B,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,oCAAoC;IACnD,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,oCAAoC,GAAG,CACjD,OAAO,EAAE,oCAAoC,KAC1C,SAAS,kBAAkB,EAAE,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,2FAA2F;IAC3F,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,oCAAoC,CAAC;IAC3D,mGAAmG;IACnG,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAC3C;AAqBD;;;;;;;;;;;GAWG;AACH,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,eAAe,EACtB,SAAS,CAAC,EAAE,kBAAkB,GAC7B,SAAS,kBAAkB,EAAE,CAkB/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,+BAA+B,EACxC,KAAK,SAAI,GACR,eAAe,CA6BjB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,EAAE,+BAA+B,GACvC,SAAS,eAAe,EAAE,CAE5B;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,+BAA+B,GACvC,kBAAkB,CAEpB"}

package/dist/validation.js

@@ -0,0 +1,123 @@
+import { DtoValidationError } from '@fluojs/validation';
+import { I18nError } from './errors.js';
+
+/**
+ * Context used to derive translation keys for one validation issue.
+ */
+
+/**
+ * Builds candidate i18n translation keys for one validation issue.
+ */
+
+/**
+ * Options for opt-in validation issue localization.
+ */
+
+const DEFAULT_VALIDATION_NAMESPACE = 'validation';
+function isMissingMessageError(error) {
+  return error instanceof I18nError && error.code === 'I18N_MISSING_MESSAGE';
+}
+function appendWithPrefix(keys, keyPrefix, key) {
+  keys.push(keyPrefix === undefined ? key : `${keyPrefix}.${key}`);
+}
+function createValidationInterpolationValues(issue) {
+  return {
+    code: issue.code,
+    field: issue.field,
+    message: issue.message,
+    source: issue.source
+  };
+}
+
+/**
+ * Creates default translation key candidates for a validation issue.
+ *
+ * @remarks
+ * Candidate order is most-specific to least-specific: `source.field.code`, `field.code`, `source.code`, then `code`.
+ * The optional `keyPrefix` is prepended to each candidate. Field paths are preserved as authored by
+ * `@fluojs/validation`, allowing catalogs to mirror dot/bracket validation paths explicitly.
+ *
+ * @param issue Validation issue to map into translation keys.
+ * @param keyPrefix Optional catalog prefix prepended before generated keys.
+ * @returns Ordered translation key candidates.
+ */
+export function createValidationIssueTranslationKeys(issue, keyPrefix) {
+  const keys = [];
+  if (issue.source !== undefined && issue.field !== undefined) {
+    appendWithPrefix(keys, keyPrefix, `${issue.source}.${issue.field}.${issue.code}`);
+  }
+  if (issue.field !== undefined) {
+    appendWithPrefix(keys, keyPrefix, `${issue.field}.${issue.code}`);
+  }
+  if (issue.source !== undefined) {
+    appendWithPrefix(keys, keyPrefix, `${issue.source}.${issue.code}`);
+  }
+  appendWithPrefix(keys, keyPrefix, issue.code);
+  return Object.freeze(keys);
+}
+
+/**
+ * Localizes one validation issue by resolving explicit translation key candidates.
+ *
+ * @param i18n I18n service used for catalog lookup.
+ * @param issue Validation issue whose message should be localized.
+ * @param options Explicit locale and optional key mapping controls.
+ * @param index Zero-based index used only by custom key builders.
+ * @returns A new validation issue with a localized message when a candidate resolves.
+ * @throws {I18nError} When no translation resolves and `fallbackToIssueMessage` is `false`.
+ */
+export function localizeValidationIssue(i18n, issue, options, index = 0) {
+  const namespace = options.namespace ?? DEFAULT_VALIDATION_NAMESPACE;
+  const keys = options.keyBuilder?.({
+    index,
+    issue
+  }) ?? createValidationIssueTranslationKeys(issue, options.keyPrefix);
+  const values = createValidationInterpolationValues(issue);
+  for (const key of keys) {
+    try {
+      return {
+        ...issue,
+        message: i18n.translate(key, {
+          locale: options.locale,
+          namespace,
+          values
+        })
+      };
+    } catch (error) {
+      if (isMissingMessageError(error)) {
+        continue;
+      }
+      throw error;
+    }
+  }
+  if (options.fallbackToIssueMessage === false) {
+    throw new I18nError(`Missing validation i18n message for issue code: ${issue.code}`, 'I18N_MISSING_MESSAGE');
+  }
+  return {
+    ...issue
+  };
+}
+
+/**
+ * Localizes validation issues without mutating the original issue objects.
+ *
+ * @param i18n I18n service used for catalog lookup.
+ * @param issues Validation issues from `@fluojs/validation`.
+ * @param options Explicit locale and optional key mapping controls.
+ * @returns Localized validation issue snapshots.
+ */
+export function localizeValidationIssues(i18n, issues, options) {
+  return Object.freeze(issues.map((issue, index) => localizeValidationIssue(i18n, issue, options, index)));
+}
+
+/**
+ * Creates a new `DtoValidationError` with localized issue messages.
+ *
+ * @param i18n I18n service used for catalog lookup.
+ * @param error Validation error from `@fluojs/validation`.
+ * @param options Explicit locale and optional key mapping controls.
+ * @returns A new validation error that preserves the original top-level error message and localized issue snapshots.
+ */
+export function localizeDtoValidationError(i18n, error, options) {
+  return new DtoValidationError(error.message, localizeValidationIssues(i18n, error.issues, options));
+}

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@fluojs/i18n",
+  "description": "Framework-agnostic internationalization core surface for fluo applications.",
+  "keywords": [
+    "fluo",
+    "i18n",
+    "internationalization",
+    "localization",
+    "translations"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/i18n"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./loaders/fs": {
+      "types": "./dist/loaders/fs.d.ts",
+      "import": "./dist/loaders/fs.js"
+    },
+    "./loaders/remote": {
+      "types": "./dist/loaders/remote.d.ts",
+      "import": "./dist/loaders/remote.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters.d.ts",
+      "import": "./dist/adapters.js"
+    },
+    "./icu": {
+      "types": "./dist/icu.d.ts",
+      "import": "./dist/icu.js"
+    },
+    "./validation": {
+      "types": "./dist/validation.d.ts",
+      "import": "./dist/validation.js"
+    },
+    "./typegen": {
+      "types": "./dist/typegen.d.ts",
+      "import": "./dist/typegen.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fluojs/core": "^1.0.0-beta.6"
+  },
+  "peerDependencies": {
+    "intl-messageformat": "^11.2.4",
+    "@fluojs/http": "^1.0.0-beta.11",
+    "@fluojs/validation": "^1.0.0-beta.4"
+  },
+  "peerDependenciesMeta": {
+    "@fluojs/http": {
+      "optional": true
+    },
+    "@fluojs/validation": {
+      "optional": true
+    },
+    "intl-messageformat": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "intl-messageformat": "^11.2.4",
+    "vitest": "^3.2.4",
+    "@fluojs/http": "^1.0.0-beta.11",
+    "@fluojs/validation": "^1.0.0-beta.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit && pnpm exec tsc -p tsconfig.node.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}