@fluojs/i18n 1.0.0-beta.1

package/dist/service.js

@@ -0,0 +1,348 @@
+import { snapshotI18nModuleOptions } from './options.js';
+import { I18nError } from './errors.js';
+function hasOwn(value, key) {
+  return typeof value === 'object' && value !== null && Object.hasOwn(value, key);
+}
+function isPlainObject(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function normalizeTranslationKey(key, namespace) {
+  if (typeof key !== 'string') {
+    throw new I18nError('Translation key must be a string.', 'I18N_INVALID_OPTIONS');
+  }
+  if (key.trim() === '') {
+    throw new I18nError('Translation key must be a non-empty string.', 'I18N_INVALID_OPTIONS');
+  }
+  if (namespace === undefined) {
+    return key;
+  }
+  if (typeof namespace !== 'string') {
+    throw new I18nError('Translation namespace must be a string when provided.', 'I18N_INVALID_OPTIONS');
+  }
+  if (namespace.trim() === '') {
+    throw new I18nError('Translation namespace must be a non-empty string when provided.', 'I18N_INVALID_OPTIONS');
+  }
+  return `${namespace}.${key}`;
+}
+function assertInterpolationValues(values) {
+  if (values !== undefined && !isPlainObject(values)) {
+    throw new I18nError('Translation values must be a plain object when provided.', 'I18N_INVALID_OPTIONS');
+  }
+}
+function assertDefaultValue(defaultValue) {
+  if (defaultValue !== undefined && typeof defaultValue !== 'string') {
+    throw new I18nError('Translation defaultValue must be a string when provided.', 'I18N_INVALID_OPTIONS');
+  }
+}
+function assertFormatterOptions(options, label) {
+  if (!isPlainObject(options)) {
+    throw new I18nError(`${label} options are required.`, 'I18N_INVALID_OPTIONS');
+  }
+  if (typeof options.locale !== 'string' || options.locale.trim() === '') {
+    throw new I18nError(`${label} locale must be a non-empty string.`, 'I18N_INVALID_OPTIONS');
+  }
+  if (options.format !== undefined && (typeof options.format !== 'string' || options.format.trim() === '')) {
+    throw new I18nError(`${label} format must be a non-empty string when provided.`, 'I18N_INVALID_OPTIONS');
+  }
+}
+function assertIntlOptionBag(options, label) {
+  if (options !== undefined && !isPlainObject(options)) {
+    throw new I18nError(`${label} Intl options must be a plain object when provided.`, 'I18N_INVALID_OPTIONS');
+  }
+}
+function assertCurrency(currency) {
+  if (typeof currency !== 'string' || currency.trim() === '') {
+    throw new I18nError('Currency code must be a non-empty string.', 'I18N_INVALID_OPTIONS');
+  }
+}
+function assertListValues(values) {
+  if (!Array.isArray(values) || values.some(value => typeof value !== 'string')) {
+    throw new I18nError('List values must be an array of strings.', 'I18N_INVALID_OPTIONS');
+  }
+}
+function formatWithIntlErrorBoundary(label, action) {
+  try {
+    return action();
+  } catch (error) {
+    if (error instanceof RangeError || error instanceof TypeError) {
+      throw new I18nError(`${label} Intl options are invalid.`, 'I18N_INVALID_OPTIONS');
+    }
+    throw error;
+  }
+}
+function interpolate(message, values) {
+  if (values === undefined) {
+    return message;
+  }
+  return message.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (placeholder, name) => {
+    if (!Object.hasOwn(values, name)) {
+      return placeholder;
+    }
+    const value = values[name];
+    return value === undefined || value === null ? '' : String(value);
+  });
+}
+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 pushUnique(locales, locale) {
+  if (locale !== undefined && !locales.includes(locale)) {
+    locales.push(locale);
+  }
+}
+function isFallbackMap(value) {
+  return !Array.isArray(value);
+}
+
+/**
+ * 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 class I18nService {
+  options;
+
+  /**
+   * Creates a service with a detached options snapshot.
+   *
+   * @param options Root i18n options captured at the application boundary.
+   */
+  constructor(options = {}) {
+    this.options = snapshotI18nModuleOptions(options);
+  }
+
+  /**
+   * Returns a detached copy of the root i18n options snapshot.
+   *
+   * @returns The captured i18n module options without exposing mutable service internals.
+   */
+  snapshotOptions() {
+    return snapshotI18nModuleOptions(this.options);
+  }
+
+  /**
+   * 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) {
+    if (typeof locale !== 'string' || locale.trim() === '') {
+      throw new I18nError('Translation locale must be a non-empty string.', 'I18N_INVALID_OPTIONS');
+    }
+    if (this.options.supportedLocales !== undefined && !this.options.supportedLocales.includes(locale)) {
+      throw new I18nError(`Unsupported i18n locale: ${locale}`, 'I18N_INVALID_OPTIONS');
+    }
+    const chain = [];
+    pushUnique(chain, locale);
+    if (Array.isArray(this.options.fallbackLocales)) {
+      for (const fallbackLocale of this.options.fallbackLocales) {
+        pushUnique(chain, fallbackLocale);
+      }
+    } else if (this.options.fallbackLocales !== undefined && isFallbackMap(this.options.fallbackLocales)) {
+      for (const fallbackLocale of this.options.fallbackLocales[locale] ?? []) {
+        pushUnique(chain, fallbackLocale);
+      }
+    }
+    pushUnique(chain, this.options.defaultLocale);
+    return Object.freeze(chain);
+  }
+  resolveNamedOptions(formats, name, label) {
+    if (name === undefined) {
+      return undefined;
+    }
+    const options = formats?.[name];
+    if (options === undefined) {
+      throw new I18nError(`Unknown ${label} format: ${name}`, 'I18N_INVALID_OPTIONS');
+    }
+    return options;
+  }
+
+  /**
+   * 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, options) {
+    assertFormatterOptions(options, 'Date/time formatter');
+    assertIntlOptionBag(options.options, 'Date/time formatter');
+    this.resolveLocales(options.locale);
+    const namedOptions = this.resolveNamedOptions(this.options.formats?.dateTime, options.format, 'dateTime');
+    return formatWithIntlErrorBoundary('Date/time formatter', () => new Intl.DateTimeFormat(options.locale, {
+      ...namedOptions,
+      ...options.options
+    }).format(value));
+  }
+
+  /**
+   * 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, options) {
+    assertFormatterOptions(options, 'Number formatter');
+    assertIntlOptionBag(options.options, 'Number formatter');
+    this.resolveLocales(options.locale);
+    const namedOptions = this.resolveNamedOptions(this.options.formats?.number, options.format, 'number');
+    return formatWithIntlErrorBoundary('Number formatter', () => new Intl.NumberFormat(options.locale, {
+      ...namedOptions,
+      ...options.options
+    }).format(value));
+  }
+
+  /**
+   * 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, options) {
+    assertFormatterOptions(options, 'Currency formatter');
+    assertCurrency(options.currency);
+    assertIntlOptionBag(options.options, 'Currency formatter');
+    this.resolveLocales(options.locale);
+    const namedOptions = this.resolveNamedOptions(this.options.formats?.number, options.format, 'number');
+    return formatWithIntlErrorBoundary('Currency formatter', () => new Intl.NumberFormat(options.locale, {
+      ...namedOptions,
+      ...options.options,
+      currency: options.currency,
+      style: 'currency'
+    }).format(value));
+  }
+
+  /**
+   * 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, options) {
+    assertFormatterOptions(options, 'Percent formatter');
+    assertIntlOptionBag(options.options, 'Percent formatter');
+    this.resolveLocales(options.locale);
+    const namedOptions = this.resolveNamedOptions(this.options.formats?.number, options.format, 'number');
+    return formatWithIntlErrorBoundary('Percent formatter', () => new Intl.NumberFormat(options.locale, {
+      ...namedOptions,
+      ...options.options,
+      style: 'percent'
+    }).format(value));
+  }
+
+  /**
+   * 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, options) {
+    assertListValues(values);
+    assertFormatterOptions(options, 'List formatter');
+    assertIntlOptionBag(options.options, 'List formatter');
+    this.resolveLocales(options.locale);
+    const namedOptions = this.resolveNamedOptions(this.options.formats?.list, options.format, 'list');
+    return formatWithIntlErrorBoundary('List formatter', () => new Intl.ListFormat(options.locale, {
+      ...namedOptions,
+      ...options.options
+    }).format(values));
+  }
+
+  /**
+   * 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, unit, options) {
+    assertFormatterOptions(options, 'Relative time formatter');
+    assertIntlOptionBag(options.options, 'Relative time formatter');
+    this.resolveLocales(options.locale);
+    const namedOptions = this.resolveNamedOptions(this.options.formats?.relativeTime, options.format, 'relativeTime');
+    return formatWithIntlErrorBoundary('Relative time formatter', () => new Intl.RelativeTimeFormat(options.locale, {
+      ...namedOptions,
+      ...options.options
+    }).format(value, unit));
+  }
+
+  /**
+   * 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, options) {
+    if (options === undefined || typeof options !== 'object' || options === null) {
+      throw new I18nError('Translation options are required.', 'I18N_INVALID_OPTIONS');
+    }
+    assertInterpolationValues(options.values);
+    assertDefaultValue(options.defaultValue);
+    const resolvedKey = normalizeTranslationKey(key, options.namespace);
+    const locales = this.resolveLocales(options.locale);
+    for (const locale of locales) {
+      const message = resolveMessage(this.options.catalogs?.[locale], resolvedKey);
+      if (message !== undefined) {
+        return interpolate(message, options.values);
+      }
+    }
+    if (options.defaultValue !== undefined) {
+      return interpolate(options.defaultValue, options.values);
+    }
+    const missing = this.options.missingMessage?.({
+      attemptedLocales: locales,
+      key: resolvedKey,
+      locale: options.locale,
+      values: options.values
+    });
+    if (missing !== undefined) {
+      return interpolate(missing, options.values);
+    }
+    throw new I18nError(`Missing i18n message: ${resolvedKey}`, 'I18N_MISSING_MESSAGE');
+  }
+}
+
+/**
+ * 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 function createI18n(options = {}) {
+  return new I18nService(options);
+}

package/dist/typegen.d.ts

@@ -0,0 +1,60 @@
+import type { I18nLocale, I18nMessageTree, I18nTranslationKey } from './types.js';
+/**
+ * Catalog input consumed by the i18n catalog type generator.
+ */
+export interface I18nCatalogTypegenInput {
+    /** Locale that owns this catalog tree. */
+    readonly locale: I18nLocale;
+    /** Optional filesystem or remote loader namespace path, for example `common` or `admin/common`. */
+    readonly namespace?: I18nTranslationKey;
+    /** Nested message tree whose string leaves become generated translation keys. */
+    readonly messages: I18nMessageTree;
+}
+/**
+ * Options for rendering TypeScript declarations from catalog inputs.
+ */
+export interface I18nCatalogTypegenOptions {
+    /** Banner written at the top of the generated declaration output. */
+    readonly banner?: string;
+    /** Exported union type name for fully qualified translation keys. */
+    readonly keyTypeName?: string;
+    /** Exported union type name for discovered namespace paths. */
+    readonly namespaceTypeName?: string;
+    /** Exported mapped type name that stores leaf keys by namespace path. */
+    readonly keyByNamespaceTypeName?: string;
+    /** Exported helper type name that resolves leaf keys for a namespace path. */
+    readonly namespaceKeyTypeName?: string;
+    /** Exported options type name for fully qualified typed translation calls. */
+    readonly typedTranslateOptionsTypeName?: string;
+    /** Exported callable type name for fully qualified key translation. */
+    readonly typedTranslateTypeName?: string;
+    /** Exported facade type name for opt-in typed translation callsites. */
+    readonly typedServiceTypeName?: string;
+}
+/**
+ * Options for loading JSON catalog files from a locale/namespace directory tree before type generation.
+ */
+export interface I18nCatalogTypegenDirectoryOptions extends I18nCatalogTypegenOptions {
+    /** Root directory containing locale directories and nested JSON namespace files. */
+    readonly rootDir: string;
+    /** Optional locale allow-list. When omitted, all immediate directories under `rootDir` are scanned. */
+    readonly locales?: readonly I18nLocale[];
+}
+/**
+ * Generates deterministic TypeScript translation-key declarations from catalog message trees.
+ *
+ * @param inputs Locale and optional namespace catalog trees to inspect.
+ * @param options Optional exported type names and output banner controls.
+ * @returns TypeScript declaration text containing key and namespace helper types.
+ * @throws {I18nError} When catalog inputs, namespaces, or output type names are invalid.
+ */
+export declare function generateI18nCatalogTypes(inputs: readonly I18nCatalogTypegenInput[], options?: I18nCatalogTypegenOptions): string;
+/**
+ * Reads locale/namespace JSON catalogs from disk and generates deterministic TypeScript key declarations.
+ *
+ * @param options Directory scanning and output rendering options.
+ * @returns TypeScript declaration text containing key and namespace helper types.
+ * @throws {I18nError} When directory options, catalog JSON, namespaces, or message trees are invalid.
+ */
+export declare function generateI18nCatalogTypesFromDirectory(options: I18nCatalogTypegenDirectoryOptions): Promise<string>;
+//# sourceMappingURL=typegen.d.ts.map

package/dist/typegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typegen.d.ts","sourceRoot":"","sources":["../src/typegen.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAkBlF;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,mGAAmG;IACnG,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,8EAA8E;IAC9E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,8EAA8E;IAC9E,QAAQ,CAAC,6BAA6B,CAAC,EAAE,MAAM,CAAC;IAChD,uEAAuE;IACvE,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,wEAAwE;IACxE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,kCAAmC,SAAQ,yBAAyB;IACnF,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CAC1C;AA+JD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,uBAAuB,EAAE,EAC1C,OAAO,GAAE,yBAA8B,GACtC,MAAM,CA8ER;AAED;;;;;;GAMG;AACH,wBAAsB,qCAAqC,CAAC,OAAO,EAAE,kCAAkC,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBxH"}

package/dist/typegen.js

@@ -0,0 +1,215 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { extname, join, relative, sep } from 'node:path';
+import { I18nError } from './errors.js';
+import { isPlainObject, snapshotLoaderMessageTree, validateLoaderLocale, validateLoaderNamespace } from './loaders/shared.js';
+const DEFAULT_BANNER = '/* Generated by @fluojs/i18n/typegen. Do not edit manually. */';
+const DEFAULT_KEY_TYPE_NAME = 'I18nCatalogKey';
+const DEFAULT_NAMESPACE_TYPE_NAME = 'I18nCatalogNamespace';
+const DEFAULT_KEY_BY_NAMESPACE_TYPE_NAME = 'I18nCatalogKeyByNamespace';
+const DEFAULT_NAMESPACE_KEY_TYPE_NAME = 'I18nCatalogNamespaceKey';
+const DEFAULT_TYPED_TRANSLATE_OPTIONS_TYPE_NAME = 'I18nCatalogTypedTranslateOptions';
+const DEFAULT_TYPED_TRANSLATE_TYPE_NAME = 'I18nCatalogTypedTranslate';
+const DEFAULT_TYPED_SERVICE_TYPE_NAME = 'I18nCatalogTypedService';
+const IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * Catalog input consumed by the i18n catalog type generator.
+ */
+
+/**
+ * Options for rendering TypeScript declarations from catalog inputs.
+ */
+
+/**
+ * Options for loading JSON catalog files from a locale/namespace directory tree before type generation.
+ */
+
+function assertIdentifier(value, fallback, label) {
+  const name = value ?? fallback;
+  if (!IDENTIFIER_PATTERN.test(name)) {
+    throw new I18nError(`${label} must be a valid TypeScript identifier.`, 'I18N_INVALID_OPTIONS');
+  }
+  return name;
+}
+function normalizeBanner(value) {
+  if (value === undefined) {
+    return DEFAULT_BANNER;
+  }
+  if (typeof value !== 'string') {
+    throw new I18nError('Catalog typegen banner must be a string when provided.', 'I18N_INVALID_OPTIONS');
+  }
+  return value;
+}
+function assertDirectoryOptions(options) {
+  if (!isPlainObject(options) || typeof options.rootDir !== 'string' || options.rootDir.trim() === '') {
+    throw new I18nError('Catalog typegen rootDir must be a non-empty string.', 'I18N_INVALID_OPTIONS');
+  }
+  if (options.locales !== undefined) {
+    if (!Array.isArray(options.locales)) {
+      throw new I18nError('Catalog typegen locales must be an array when provided.', 'I18N_INVALID_OPTIONS');
+    }
+    for (const locale of options.locales) {
+      validateLoaderLocale(locale, 'Catalog typegen');
+    }
+  }
+}
+function normalizeInput(input) {
+  if (!isPlainObject(input)) {
+    throw new I18nError('Catalog typegen input must be a plain object.', 'I18N_INVALID_OPTIONS');
+  }
+  validateLoaderLocale(input.locale, 'Catalog typegen');
+  if (input.namespace !== undefined) {
+    validateLoaderNamespace(input.namespace, 'Catalog typegen');
+  }
+  return {
+    locale: input.locale,
+    messages: snapshotLoaderMessageTree(input.messages, `catalogs.${input.locale}${input.namespace === undefined ? '' : `.${input.namespace}`}`),
+    namespace: input.namespace
+  };
+}
+function collectLeafKeys(tree, prefix = '') {
+  const keys = [];
+  for (const key of Object.keys(tree).sort()) {
+    const value = tree[key];
+    const nextPrefix = prefix === '' ? key : `${prefix}.${key}`;
+    if (typeof value === 'string') {
+      keys.push(nextPrefix);
+    } else {
+      keys.push(...collectLeafKeys(value, nextPrefix));
+    }
+  }
+  return keys;
+}
+function unionLiteral(values) {
+  if (values.length === 0) {
+    return 'never';
+  }
+  return values.map(value => JSON.stringify(value)).join(' | ');
+}
+function renderNamespaceMap(typeName, entries) {
+  if (entries.size === 0) {
+    return [`export type ${typeName} = Record<never, never>;`];
+  }
+  const lines = [`export interface ${typeName} {`];
+  for (const namespace of [...entries.keys()].sort()) {
+    lines.push(`  readonly ${JSON.stringify(namespace)}: ${unionLiteral(entries.get(namespace) ?? [])};`);
+  }
+  lines.push('}');
+  return lines;
+}
+function renderTypedHelpers(names) {
+  return [`export type ${names.namespaceKeyTypeName}<Namespace extends ${names.namespaceTypeName}> = ${names.keyByNamespaceTypeName}[Namespace];`, `export type ${names.typedTranslateOptionsTypeName} = Omit<import('@fluojs/i18n').I18nTranslateOptions, 'namespace'>;`, `export type ${names.typedTranslateTypeName} = <Key extends ${names.keyTypeName}>(`, '  key: Key,', `  options: ${names.typedTranslateOptionsTypeName},`, ') => string;', `export interface ${names.typedServiceTypeName} {`, `  readonly translate: ${names.typedTranslateTypeName};`, '  readonly translateInNamespace: <', `    Namespace extends ${names.namespaceTypeName},`, `    Key extends ${names.namespaceKeyTypeName}<Namespace>,`, '  >(', '    namespace: Namespace,', '    key: Key,', "    options: Omit<import('@fluojs/i18n').I18nTranslateOptions, 'namespace'>,", '  ) => string;', '}'];
+}
+function relativeJsonNamespace(localeDir, filePath) {
+  const relativePath = relative(localeDir, filePath).split(sep).join('/');
+  return relativePath.slice(0, -extname(relativePath).length);
+}
+async function collectCatalogFiles(directory) {
+  const entries = await readdir(directory, {
+    withFileTypes: true
+  });
+  const files = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const entryPath = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectCatalogFiles(entryPath)));
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith('.json')) {
+      files.push(entryPath);
+    }
+  }
+  return files;
+}
+async function readCatalogFile(locale, namespace, filePath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    throw new I18nError(`Malformed i18n catalog JSON: ${locale}/${namespace}.json`, 'I18N_INVALID_CATALOG');
+  }
+  return {
+    locale,
+    messages: snapshotLoaderMessageTree(parsed, `catalogs.${locale}.${namespace}`),
+    namespace
+  };
+}
+
+/**
+ * Generates deterministic TypeScript translation-key declarations from catalog message trees.
+ *
+ * @param inputs Locale and optional namespace catalog trees to inspect.
+ * @param options Optional exported type names and output banner controls.
+ * @returns TypeScript declaration text containing key and namespace helper types.
+ * @throws {I18nError} When catalog inputs, namespaces, or output type names are invalid.
+ */
+export function generateI18nCatalogTypes(inputs, options = {}) {
+  if (!Array.isArray(inputs)) {
+    throw new I18nError('Catalog typegen inputs must be an array.', 'I18N_INVALID_OPTIONS');
+  }
+  const keyTypeName = assertIdentifier(options.keyTypeName, DEFAULT_KEY_TYPE_NAME, 'Catalog typegen keyTypeName');
+  const namespaceTypeName = assertIdentifier(options.namespaceTypeName, DEFAULT_NAMESPACE_TYPE_NAME, 'Catalog typegen namespaceTypeName');
+  const keyByNamespaceTypeName = assertIdentifier(options.keyByNamespaceTypeName, DEFAULT_KEY_BY_NAMESPACE_TYPE_NAME, 'Catalog typegen keyByNamespaceTypeName');
+  const namespaceKeyTypeName = assertIdentifier(options.namespaceKeyTypeName, DEFAULT_NAMESPACE_KEY_TYPE_NAME, 'Catalog typegen namespaceKeyTypeName');
+  const typedTranslateTypeName = assertIdentifier(options.typedTranslateTypeName, DEFAULT_TYPED_TRANSLATE_TYPE_NAME, 'Catalog typegen typedTranslateTypeName');
+  const typedTranslateOptionsTypeName = assertIdentifier(options.typedTranslateOptionsTypeName, DEFAULT_TYPED_TRANSLATE_OPTIONS_TYPE_NAME, 'Catalog typegen typedTranslateOptionsTypeName');
+  const typedServiceTypeName = assertIdentifier(options.typedServiceTypeName, DEFAULT_TYPED_SERVICE_TYPE_NAME, 'Catalog typegen typedServiceTypeName');
+  const keys = new Set();
+  const namespaces = new Set();
+  const keysByNamespace = new Map();
+  for (const input of inputs.map(normalizeInput)) {
+    const leafKeys = collectLeafKeys(input.messages);
+    const namespace = input.namespace;
+    if (namespace !== undefined) {
+      namespaces.add(namespace);
+      const namespaceKeys = keysByNamespace.get(namespace) ?? new Set();
+      for (const leafKey of leafKeys) {
+        namespaceKeys.add(leafKey);
+        keys.add(`${namespace}.${leafKey}`);
+      }
+      keysByNamespace.set(namespace, namespaceKeys);
+      continue;
+    }
+    for (const leafKey of leafKeys) {
+      keys.add(leafKey);
+    }
+  }
+  const sortedNamespaceMap = new Map();
+  for (const namespace of [...keysByNamespace.keys()].sort()) {
+    sortedNamespaceMap.set(namespace, [...(keysByNamespace.get(namespace) ?? [])].sort());
+  }
+  return [normalizeBanner(options.banner), '', `export type ${keyTypeName} = ${unionLiteral([...keys].sort())};`, `export type ${namespaceTypeName} = ${unionLiteral([...namespaces].sort())};`, ...renderNamespaceMap(keyByNamespaceTypeName, sortedNamespaceMap), ...renderTypedHelpers({
+    keyByNamespaceTypeName,
+    keyTypeName,
+    namespaceKeyTypeName,
+    namespaceTypeName,
+    typedServiceTypeName,
+    typedTranslateOptionsTypeName,
+    typedTranslateTypeName
+  }), ''].join('\n');
+}
+
+/**
+ * Reads locale/namespace JSON catalogs from disk and generates deterministic TypeScript key declarations.
+ *
+ * @param options Directory scanning and output rendering options.
+ * @returns TypeScript declaration text containing key and namespace helper types.
+ * @throws {I18nError} When directory options, catalog JSON, namespaces, or message trees are invalid.
+ */
+export async function generateI18nCatalogTypesFromDirectory(options) {
+  assertDirectoryOptions(options);
+  const localeNames = options.locales === undefined ? (await readdir(options.rootDir, {
+    withFileTypes: true
+  })).filter(entry => entry.isDirectory()).map(entry => entry.name) : [...options.locales];
+  const inputs = [];
+  for (const locale of localeNames.sort()) {
+    validateLoaderLocale(locale, 'Catalog typegen');
+    const localeDir = join(options.rootDir, locale);
+    for (const filePath of await collectCatalogFiles(localeDir)) {
+      const namespace = relativeJsonNamespace(localeDir, filePath);
+      validateLoaderNamespace(namespace, 'Catalog typegen');
+      inputs.push(await readCatalogFile(locale, namespace, filePath));
+    }
+  }
+  return generateI18nCatalogTypes(inputs, options);
+}