@gravito/cosmos 3.0.0 → 3.1.0

package/src/I18nService.ts

@@ -1,59 +1,281 @@
-import type { MiddlewareHandler } from '@gravito/photon'
+/**
+ * @file packages/cosmos/src/I18nService.ts
+ * @module @gravito/cosmos/service
+ * @description Core services and interfaces for internationalization.
+ */
 
+import type { GravitoMiddleware } from '@gravito/core'
+import { loadLocale } from './loader'
+
+/**
+ * Interface for locale detectors used to determine the user's preferred locale from a request context.
+ *
+ * @public
+ * @since 3.0.0
+ */
+export interface LocaleDetector {
+  /** The unique name of the detector (e.g., 'query', 'header'). */
+  name: string
+  /**
+   * Detect the locale from the given context.
+   *
+   * @param c - The application context (e.g., Hono context).
+   * @returns The detected locale string, or undefined if not found.
+   */
+  detect(c: any): string | undefined | Promise<string | undefined>
+}
+
+/**
+ * A map of translations where keys are translation keys and values
+ * are either the translated string or a nested map for grouping.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export type TranslationMap = {
   [key: string]: string | TranslationMap
 }
 
+/**
+ * Utility type to extract all possible dot-notation keys from a nested translation schema.
+ *
+ * @template T - The translation schema object.
+ * @public
+ */
+export type NestedKeyOf<T> = T extends object
+  ? {
+      [K in keyof T & (string | number)]: T[K] extends object
+        ? `${K}` | `${K}.${NestedKeyOf<T[K]>}`
+        : `${K}`
+    }[keyof T & (string | number)]
+  : never
+
+/**
+ * Configuration for lazy loading translation files.
+ *
+ * @public
+ */
+export interface LazyLoadConfig {
+  /** The base directory where translation files are located. */
+  baseDir: string
+  /** Optional list of locales to preload on startup. */
+  preload?: string[]
+}
+
+/**
+ * Configuration for translation fallback strategies.
+ *
+ * @public
+ */
+export interface FallbackConfig {
+  /**
+   * Custom fallback chains for specific locales.
+   * Key is the requested locale, value is an array of fallback locales.
+   */
+  fallbackChain?: Record<string, string[]>
+  /**
+   * Strategy to use when a translation key is missing.
+   * - 'key': Return the key itself (default).
+   * - 'empty': Return an empty string.
+   * - 'throw': Throw an error.
+   * - (key, locale) => string: Custom handler function.
+   */
+  onMissingKey?: 'key' | 'empty' | 'throw' | ((key: string, locale: string) => string)
+  /** Whether to log a warning when a key is missing. */
+  warnOnMissing?: boolean
+}
+
+/**
+ * Configuration for the I18n service.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export interface I18nConfig {
+  /** The default locale to use when no locale is detected or for fallbacks. */
   defaultLocale: string
+  /** List of locales officially supported by the application. */
   supportedLocales: string[]
-  // Path to translation files, or a Record of translations
-  // If undefined, it will look into `resources/lang` by default (conceptually, handled by loader)
+  /**
+   * Static translations indexed by locale.
+   * Keys are locale strings (e.g., 'en', 'zh-TW').
+   */
   translations?: Record<string, TranslationMap>
+  /**
+   * Configuration for lazy loading translation files from the filesystem.
+   */
+  lazyLoad?: LazyLoadConfig
+  /**
+   * Configuration for fallback strategies and missing key handling.
+   */
+  fallback?: FallbackConfig
+}
+
+/**
+ * Statistics about the I18n service state and performance.
+ *
+ * @public
+ */
+export interface I18nStats {
+  /** Number of locales currently loaded. */
+  localesCount: number
+  /** Estimated total number of translation keys across all locales. */
+  totalKeys: number
+  /** Percentage of translation requests served from cache. */
+  cacheHitRate: number
+  /** Number of entries currently in the translation cache. */
+  cacheSize: number
 }
 
-export interface I18nService {
+/**
+ * Interface for the I18n service providing translation capabilities.
+ *
+ * It allows for setting and getting the current locale, translating strings
+ * with optional replacements, and checking for key existence.
+ *
+ * @template Schema - The translation schema for type-safe keys.
+ * @public
+ * @since 3.0.0
+ */
+export interface I18nService<Schema = TranslationMap> {
+  /** The current active locale for this instance. */
   locale: string
+  /**
+   * Set the active locale for this service instance.
+   *
+   * @param locale - Valid locale string from supportedLocales.
+   * @throws Error if locale is not supported (depending on implementation).
+   */
   setLocale(locale: string): void
+  /**
+   * Get the current active locale.
+   *
+   * @returns Current locale string.
+   */
   getLocale(): string
-  t(key: string, replacements?: Record<string, string | number>): string
-  has(key: string): boolean
-  // Create a request-scoped instance
-  clone(locale?: string): I18nService
+  /**
+   * Ensure translations for a locale are loaded (useful for lazy loading).
+   *
+   * @param locale - The locale to load.
+   * @returns Promise that resolves when loading is complete.
+   */
+  ensureLocale(locale: string): Promise<void>
+  /**
+   * Translate a key into the current locale.
+   *
+   * Supports parameter replacement using `:key` syntax and pluralization
+   * if a `count` parameter is provided.
+   *
+   * @param key - The translation key (e.g., 'auth.login_success').
+   * @param replacements - Optional placeholders replaced by values.
+   * @returns The translated string, or the key itself if not found.
+   *
+   * @example
+   * ```typescript
+   * i18n.t('messages.hello', { name: 'John' }); // "Hello John"
+   * i18n.t('items.count', { count: 5 }); // "5 items"
+   * ```
+   */
+  t(
+    key: NestedKeyOf<Schema> | (string & {}),
+    replacements?: Record<string, string | number>
+  ): string
+  /**
+   * Translate multiple keys at once.
+   *
+   * @param keysOrEntries - Array of keys or [key, replacements] tuples.
+   * @returns Object mapping each key to its translated string.
+   */
+  tMany(
+    keysOrEntries: Array<
+      | NestedKeyOf<Schema>
+      | (string & {})
+      | [NestedKeyOf<Schema> | (string & {}), Record<string, string | number>?]
+    >
+  ): Record<string, string>
+  /**
+   * Check if a translation key exists for the current locale.
+   *
+   * @param key - The key to check.
+   * @returns True if the key exists, false otherwise.
+   */
+  has(key: NestedKeyOf<Schema> | (string & {})): boolean
+  /**
+   * Create a new request-scoped instance of the I18n service.
+   *
+   * This is typically used in middleware to provide a fresh instance per request
+   * that shares the same translation resources but has its own locale state.
+   *
+   * @param locale - Optional initial locale for the new instance.
+   * @returns A new I18nService instance.
+   */
+  clone(locale?: string): I18nService<Schema>
+
+  /**
+   * Get list of all currently loaded locales.
+   * @returns Array of locale strings.
+   */
+  getLocales(): string[]
+  /**
+   * Check if translations for a specific locale are already loaded.
+   * @param locale - Locale to check.
+   * @returns True if loaded.
+   */
+  isLocaleLoaded(locale: string): boolean
+  /**
+   * Get performance and usage statistics.
+   * @returns I18nStats object.
+   */
+  getStats(): I18nStats
 }
 
 /**
- * Request-scoped I18n Instance
- * Holds the state (locale) for a single request, but shares the heavy resources (translations)
+ * Request-scoped I18n Instance.
+ *
+ * Holds the state (current locale) for a single request, but shares the heavy
+ * resources (translation bundles) through the central I18nManager.
+ *
+ * @template Schema - The translation schema for type-safe keys.
+ * @public
+ * @since 3.0.0
  */
-export class I18nInstance implements I18nService {
+export class I18nInstance<Schema = TranslationMap> implements I18nService<Schema> {
+  /** The current active locale for this instance. */
   private _locale: string
 
   /**
    * Create a new I18nInstance.
    *
-   * @param manager - The I18nManager instance.
+   * @param manager - The central I18nManager instance.
    * @param initialLocale - The initial locale for this instance.
    */
   constructor(
-    private manager: I18nManager,
+    public readonly manager: I18nManager<Schema>,
     initialLocale: string
   ) {
     this._locale = initialLocale
   }
 
+  /**
+   * Get the current active locale.
+   */
   get locale(): string {
     return this._locale
   }
 
+  /**
+   * Set the current active locale.
+   */
   set locale(value: string) {
     this.setLocale(value)
   }
 
   /**
-   * Set the current locale.
+   * Set the active locale for this instance.
+   *
+   * Validates that the locale is among the supported locales defined in config.
    *
-   * @param locale - The locale to set.
+   * @param locale - Valid locale string from supportedLocales.
    */
   setLocale(locale: string) {
     if (this.manager.getConfig().supportedLocales.includes(locale)) {
@@ -62,54 +284,151 @@ export class I18nInstance implements I18nService {
   }
 
   /**
-   * Get the current locale.
+   * Ensure translations for a locale are loaded.
+   *
+   * Delegates to the manager's loading mechanism (e.g., filesystem read).
+   *
+   * @param locale - Locale to load.
+   */
+  async ensureLocale(locale: string): Promise<void> {
+    return this.manager.ensureLocale(locale)
+  }
+
+  /**
+   * Get the current locale string.
    *
-   * @returns The current locale string.
+   * @returns Current locale.
    */
   getLocale(): string {
     return this._locale
   }
 
   /**
-   * Translate a key.
+   * Translate a key into the current locale.
+   *
+   * Supports parameter replacement and pluralization.
    *
-   * @param key - The translation key (e.g., 'messages.welcome').
-   * @param replacements - Optional replacements for parameters in the translation string.
-   * @returns The translated string, or the key if not found.
+   * @param key - The translation key (dot notation supported).
+   * @param replacements - Key-value pairs for parameter replacement.
+   * @returns The translated string.
    */
-  t(key: string, replacements?: Record<string, string | number>): string {
+  t(
+    key: NestedKeyOf<Schema> | (string & {}),
+    replacements?: Record<string, string | number>
+  ): string {
     return this.manager.translate(this._locale, key, replacements)
   }
 
   /**
-   * Check if a translation key exists.
+   * Translate multiple keys at once for the current locale.
    *
-   * @param key - The translation key to check.
-   * @returns True if the key exists, false otherwise.
+   * @param keysOrEntries - Array of keys or [key, replacements] tuples.
+   * @returns Map of key to translated string.
+   */
+  tMany(
+    keysOrEntries: Array<
+      | NestedKeyOf<Schema>
+      | (string & {})
+      | [NestedKeyOf<Schema> | (string & {}), Record<string, string | number>?]
+    >
+  ): Record<string, string> {
+    const result: Record<string, string> = {}
+    for (const item of keysOrEntries) {
+      if (typeof item === 'string') {
+        result[item] = this.t(item)
+      } else {
+        const [key, replacements] = item
+        result[key] = this.t(key, replacements)
+      }
+    }
+    return result
+  }
+
+  /**
+   * Check if a translation key exists for the current locale.
+   *
+   * @param key - Key to check.
+   * @returns True if key exists.
    */
-  has(key: string): boolean {
+  has(key: NestedKeyOf<Schema> | (string & {})): boolean {
     return this.t(key) !== key
   }
 
   /**
    * Clone the current instance with a potentially new locale.
    *
-   * @param locale - Optional new locale for the cloned instance.
+   * Shares the same manager and underlying resources.
+   *
+   * @param locale - Optional new locale for the clone.
    * @returns A new I18nInstance.
    */
-  clone(locale?: string): I18nService {
+  clone(locale?: string): I18nService<Schema> {
     return new I18nInstance(this.manager, locale || this._locale)
   }
+
+  /**
+   * Get the current I18n configuration from the manager.
+   * @returns I18nConfig
+   */
+  getConfig(): I18nConfig {
+    return this.manager.getConfig()
+  }
+
+  /**
+   * Access the central translation bundles.
+   */
+  get translations(): Record<string, TranslationMap> {
+    return this.manager.translations
+  }
+
+  /**
+   * Get list of all currently loaded locales.
+   */
+  getLocales(): string[] {
+    return this.manager.getLocales()
+  }
+
+  /**
+   * Check if translations for a specific locale are already loaded.
+   */
+  isLocaleLoaded(locale: string): boolean {
+    return this.manager.isLocaleLoaded(locale)
+  }
+
+  /**
+   * Get performance and usage statistics.
+   */
+  getStats(): I18nStats {
+    return this.manager.getStats()
+  }
 }
 
 /**
- * Global I18n Manager
- * Holds shared configuration and translation resources
+ * Global I18n Manager.
+ *
+ * The central hub for internationalization. Holds configuration, shared translation
+ * resources, pluralization rules, and handles the actual translation logic
+ * including fallbacks and caching.
+ *
+ * @template Schema - The translation schema for type-safe keys.
+ * @public
+ * @since 3.0.0
  */
-export class I18nManager implements I18nService {
-  private translations: Record<string, TranslationMap> = {}
-  // Default instance for global usage (e.g. CLI or background jobs)
-  private globalInstance: I18nInstance
+export class I18nManager<Schema = TranslationMap> implements I18nService<Schema> {
+  /** Map of translation bundles indexed by locale. */
+  public translations: Record<string, TranslationMap> = {}
+  /** Internal cache for resolved translation strings. */
+  private cache = new Map<string, string>()
+  /** Cache for Intl.PluralRules instances. */
+  private pluralRules = new Map<string, Intl.PluralRules>()
+  /** Set of locales that have been successfully loaded. */
+  private loadedLocales = new Set<string>()
+  /** Counter for cache hits. */
+  private cacheHits = 0
+  /** Counter for cache misses. */
+  private cacheMisses = 0
+  /** Default instance for global/CLI usage. */
+  private globalInstance: I18nInstance<Schema>
 
   /**
    * Create a new I18nManager.
@@ -125,6 +444,7 @@ export class I18nManager implements I18nService {
 
   // --- I18nService Implementation (Delegates to global instance) ---
 
+  /** The global active locale. */
   get locale(): string {
     return this.globalInstance.locale
   }
@@ -135,8 +455,7 @@ export class I18nManager implements I18nService {
 
   /**
    * Set the global locale.
-   *
-   * @param locale - The locale to set.
+   * @param locale - Locale string.
    */
   setLocale(locale: string): void {
     this.globalInstance.setLocale(locale)
@@ -144,8 +463,6 @@ export class I18nManager implements I18nService {
 
   /**
    * Get the global locale.
-   *
-   * @returns The global locale string.
    */
   getLocale(): string {
     return this.globalInstance.getLocale()
@@ -154,125 +471,371 @@ export class I18nManager implements I18nService {
   /**
    * Translate a key using the global locale.
    *
-   * @param key - The translation key.
-   * @param replacements - Optional replacements.
-   * @returns The translated string.
+   * @param key - Translation key.
+   * @param replacements - Replacement parameters.
    */
-  t(key: string, replacements?: Record<string, string | number>): string {
+  t(
+    key: NestedKeyOf<Schema> | (string & {}),
+    replacements?: Record<string, string | number>
+  ): string {
     return this.globalInstance.t(key, replacements)
   }
 
+  /**
+   * Translate multiple keys at once using the global locale.
+   */
+  tMany(
+    keysOrEntries: Array<
+      | NestedKeyOf<Schema>
+      | (string & {})
+      | [NestedKeyOf<Schema> | (string & {}), Record<string, string | number>?]
+    >
+  ): Record<string, string> {
+    return this.globalInstance.tMany(keysOrEntries)
+  }
+
   /**
    * Check if a translation key exists in the global locale.
-   *
-   * @param key - The translation key.
-   * @returns True if found.
    */
-  has(key: string): boolean {
+  has(key: NestedKeyOf<Schema> | (string & {})): boolean {
     return this.globalInstance.has(key)
   }
 
   /**
-   * Clone the global instance.
+   * Create a request-scoped I18nInstance from this manager.
    *
-   * @param locale - Optional locale for the clone.
-   * @returns A new I18nInstance.
+   * @param locale - Optional initial locale.
    */
-  clone(locale?: string): I18nService {
+  clone(locale?: string): I18nService<Schema> {
     return new I18nInstance(this, locale || this.config.defaultLocale)
   }
 
-  // --- Manager Internal API ---
+  /**
+   * Get list of all currently loaded locales.
+   */
+  getLocales(): string[] {
+    return Object.keys(this.translations)
+  }
+
+  /**
+   * Check if translations for a specific locale are already loaded.
+   */
+  isLocaleLoaded(locale: string): boolean {
+    return this.loadedLocales.has(locale) || locale in this.translations
+  }
+
+  /**
+   * Get performance and usage statistics.
+   */
+  getStats(): I18nStats {
+    const totalKeys = Object.values(this.translations).reduce((acc, map) => {
+      // Very rough estimate of keys, deep counting is expensive
+      return acc + Object.keys(map).length
+    }, 0)
+
+    const totalRequests = this.cacheHits + this.cacheMisses
+    const cacheHitRate = totalRequests > 0 ? (this.cacheHits / totalRequests) * 100 : 0
+
+    return {
+      localesCount: Object.keys(this.translations).length,
+      totalKeys,
+      cacheHitRate,
+      cacheSize: this.cache.size,
+    }
+  }
 
   /**
-   * Get the I18n configuration.
+   * Ensure translations for a locale are loaded from the filesystem if lazy loading is enabled.
    *
-   * @returns The configuration object.
+   * @param locale - Locale to load.
+   */
+  async ensureLocale(locale: string): Promise<void> {
+    // If already loaded or no lazy load config, skip
+    if (this.loadedLocales.has(locale) || !this.config.lazyLoad) {
+      return
+    }
+
+    // Attempt to load
+    const translations = await loadLocale(this.config.lazyLoad.baseDir, locale)
+    if (translations) {
+      this.addResource(locale, translations)
+      this.loadedLocales.add(locale)
+    }
+  }
+
+  // --- Manager Internal API ---
+
+  /**
+   * Get the current shared I18n configuration.
    */
   getConfig(): I18nConfig {
     return this.config
   }
 
   /**
-   * Add a resource bundle for a specific locale.
+   * Add or merge a resource bundle for a specific locale.
+   *
+   * @param locale - The locale string (e.g., 'en', 'fr').
+   * @param translations - The translation map to merge into the existing bundle.
    *
-   * @param locale - The locale string.
-   * @param translations - The translations object.
+   * @example
+   * ```typescript
+   * manager.addResource('es', {
+   *   greeting: 'Hola',
+   *   auth: { login: 'Iniciar sesión' }
+   * });
+   * ```
    */
   addResource(locale: string, translations: TranslationMap) {
     this.translations[locale] = {
       ...(this.translations[locale] || {}),
       ...translations,
     }
+    this.invalidateCache(locale)
   }
 
   /**
-   * Internal translation logic used by instances
+   * Invalidate the translation cache.
+   *
+   * @param locale - If provided, only invalidates keys for this locale.
    */
-  translate(locale: string, key: string, replacements?: Record<string, string | number>): string {
+  private invalidateCache(locale?: string) {
+    if (locale) {
+      for (const key of this.cache.keys()) {
+        if (key.startsWith(`${locale}:`)) {
+          this.cache.delete(key)
+        }
+      }
+    } else {
+      this.cache.clear()
+    }
+  }
+
+  /**
+   * Get the plural form for a locale and count.
+   */
+  private getPluralForm(locale: string, count: number): string {
+    if (!this.pluralRules.has(locale)) {
+      this.pluralRules.set(locale, new Intl.PluralRules(locale))
+    }
+    return this.pluralRules.get(locale)!.select(count)
+  }
+
+  /**
+   * Resolve a dot-notation key to its value in a specific locale.
+   */
+  private resolveKey(locale: string, key: string): string | TranslationMap | undefined {
     const keys = key.split('.')
-    let value: any = this.translations[locale]
+    let value: string | TranslationMap | undefined = this.translations[locale]
 
-    // 1. Try current locale
     for (const k of keys) {
       if (value && typeof value === 'object' && k in value) {
-        value = value[k]
+        value = (value as TranslationMap)[k]
       } else {
-        value = undefined
-        break
+        return undefined
       }
     }
+    return value
+  }
 
-    // 2. If not found, try fallback (defaultLocale)
-    if (value === undefined && locale !== this.config.defaultLocale) {
-      let fallbackValue: any = this.translations[this.config.defaultLocale]
-      for (const k of keys) {
-        if (fallbackValue && typeof fallbackValue === 'object' && k in fallbackValue) {
-          fallbackValue = fallbackValue[k]
-        } else {
-          fallbackValue = undefined
-          break
-        }
+  /**
+   * Resolve a key using the configured fallback chain.
+   */
+  private resolveFallback(locale: string, key: string): string | TranslationMap | undefined {
+    const chain = this.config.fallback?.fallbackChain?.[locale] ?? [this.config.defaultLocale]
+
+    for (const fallbackLocale of chain) {
+      // Avoid infinite recursion if fallback points to itself
+      if (fallbackLocale === locale) continue
+
+      const value = this.resolveKey(fallbackLocale, key)
+      if (value !== undefined) {
+        return value
       }
-      value = fallbackValue
     }
 
-    if (value === undefined || typeof value !== 'string') {
-      return key // Return key if not found
+    return undefined
+  }
+
+  /**
+   * Handle cases where a translation key is missing after fallbacks.
+   */
+  private handleMissingKey(key: string, locale: string): string {
+    const handler = this.config.fallback?.onMissingKey ?? 'key'
+
+    if (this.config.fallback?.warnOnMissing) {
+      console.warn(`[i18n] Missing translation: ${key} (${locale})`)
+    }
+
+    if (typeof handler === 'function') {
+      return handler(key, locale)
+    }
+
+    switch (handler) {
+      case 'empty':
+        return ''
+      case 'throw':
+        throw new Error(`Missing translation: ${key}`)
+      default:
+        return key
+    }
+  }
+
+  /**
+   * The core translation logic. Handles caching, key resolution, fallbacks,
+   * pluralization, and parameter replacement.
+   *
+   * @param locale - Locale to translate into.
+   * @param key - Translation key.
+   * @param replacements - Placeholder replacements.
+   * @returns Translated string.
+   */
+  translate(locale: string, key: string, replacements?: Record<string, string | number>): string {
+    const cacheKey = `${locale}:${key}`
+    let value: string | TranslationMap | undefined
+
+    if (this.cache.has(cacheKey)) {
+      this.cacheHits++
+      value = this.cache.get(cacheKey)
+    } else {
+      this.cacheMisses++
+
+      // 1. Try current locale
+      value = this.resolveKey(locale, key)
+
+      // 2. Fallback
+      if (value === undefined) {
+        value = this.resolveFallback(locale, key)
+      }
+
+      if (value !== undefined && typeof value === 'string') {
+        this.cache.set(cacheKey, value)
+      }
     }
 
-    // 3. Replacements
-    if (replacements) {
-      for (const [search, replace] of Object.entries(replacements)) {
-        value = value.replace(new RegExp(`:${search}`, 'g'), String(replace))
+    // Pluralization
+    if (value && typeof value === 'object' && replacements?.count !== undefined) {
+      const count = Number(replacements.count)
+      const pluralMap = value as TranslationMap
+      const form = this.getPluralForm(locale, count)
+
+      if (count === 0 && 'zero' in pluralMap) {
+        value = pluralMap.zero
+      } else if (form in pluralMap) {
+        value = pluralMap[form]
+      } else if ('other' in pluralMap) {
+        value = pluralMap.other
       }
     }
 
+    if (value === undefined) {
+      return this.handleMissingKey(key, locale)
+    }
+
+    if (typeof value !== 'string') {
+      return key
+    }
+
+    if (replacements && Object.keys(replacements).length > 0) {
+      value = value.replace(REPLACEMENT_REGEX, (match, key) => {
+        return (replacements as Record<string, unknown>)[key] !== undefined
+          ? String((replacements as Record<string, unknown>)[key])
+          : match
+      })
+    }
+
     return value
   }
 }
 
+/** Regex for finding placeholders in translation strings. */
+const REPLACEMENT_REGEX = /:([a-zA-Z0-9_]+)/g
+
+/**
+ * Detector that extracts the locale from a route parameter named 'locale'.
+ *
+ * @example
+ * ```typescript
+ * // router.get('/:locale/home', ...)
+ * ```
+ * @public
+ */
+export const RouteParamDetector: LocaleDetector = {
+  name: 'routeParam',
+  detect: (c) => c.req.param('locale'),
+}
+
+/**
+ * Detector that extracts the locale from a query parameter named 'lang'.
+ *
+ * @example
+ * ```typescript
+ * // GET /home?lang=zh-TW
+ * ```
+ * @public
+ */
+export const QueryDetector: LocaleDetector = {
+  name: 'query',
+  detect: (c) => c.req.query('lang'),
+}
+
+/**
+ * Detector that extracts the locale from the 'Accept-Language' HTTP header.
+ *
+ * Picks the first (preferred) language from the comma-separated list.
+ *
+ * @public
+ */
+export const HeaderDetector: LocaleDetector = {
+  name: 'header',
+  detect: (c) => {
+    const acceptLang = c.req.header('Accept-Language')
+    if (acceptLang) {
+      return acceptLang.split(',')[0]?.trim()
+    }
+    return undefined
+  },
+}
+
 /**
- * Locale Middleware
+ * Default list of detectors used by the middleware.
+ * Order: Route Parameter > Query Parameter > Accept-Language Header.
  *
- * Detects locale from:
- * 1. Route Parameter (e.g. /:locale/foo) - Recommended for SEO
- * 2. Header (Accept-Language) - Recommended for APIs
+ * @public
  */
-export const localeMiddleware = (i18nManager: I18nService): MiddlewareHandler => {
+export const DefaultDetectors = [RouteParamDetector, QueryDetector, HeaderDetector]
+
+/**
+ * Middleware for Gravito/Photon that handles request-scoped internationalization.
+ *
+ * It uses a list of detectors to determine the locale, ensures it is loaded,
+ * and injects a request-scoped `I18nService` instance into the context under the key 'i18n'.
+ *
+ * @param i18nManager - The central I18nManager instance.
+ * @param detectors - Optional custom list of detectors.
+ * @returns GravitoMiddleware
+ *
+ * @public
+ */
+export const localeMiddleware = (
+  i18nManager: I18nService,
+  detectors: LocaleDetector[] = DefaultDetectors
+): GravitoMiddleware => {
   return async (c, next) => {
-    // Determine initial locale
-    // Priority: 1. Route Param 2. Query ?lang= 3. Header 4. Default
-    let locale = c.req.param('locale') || c.req.query('lang')
-
-    if (!locale) {
-      const acceptLang = c.req.header('Accept-Language')
-      if (acceptLang) {
-        // Simple extraction: 'en-US,en;q=0.9' -> 'en-US'
-        locale = acceptLang.split(',')[0]?.trim()
+    let locale: string | undefined
+
+    for (const detector of detectors) {
+      const result = await detector.detect(c)
+      if (result) {
+        locale = result
+        break
       }
     }
 
+    if (locale) {
+      await i18nManager.ensureLocale(locale)
+    }
+
     // Clone a request-scoped instance
     const i18n = i18nManager.clone(locale)