@quazardous/qdadm 1.19.3

package/src/i18n/IncrementalDomainProvider.ts

@@ -0,0 +1,153 @@
+/**
+ * IncrementalDomainProvider - declares one loader per top-level translation
+ * domain (`core`, `shop`, `legal`, …) and only fetches each (locale, domain)
+ * pair when it's first needed.
+ *
+ * On `load(locale)` (bootstrap / locale change) the provider only resolves
+ * the domains listed in `eagerDomains` (typically `['core']`). The rest stay
+ * dormant until `loadDomain(locale, domain)` is called — which `I18n.t()`
+ * triggers automatically on a miss whose top-level segment is a
+ * known-but-not-yet-loaded domain. The host app can also pre-warm explicitly
+ * via `i18n.loadDomain(domain, locale?)`. Inflight loads are deduped per
+ * `(locale, domain)`.
+ *
+ * Bundles returned by domain loaders are wrapped under their domain key so
+ * the registry merges them at the right place:
+ *   loader('shop')(locale) → { cart: {...} } → merged as { shop: { cart: {...} } }
+ *
+ * ## When to use this vs `LazyTranslationProvider`
+ *
+ * Use **`IncrementalDomainProvider`** when at least one of these matters:
+ *   - **Bundle size**: large app with rarely-used sections (admin, legal,
+ *     marketing) and you want to defer their cost.
+ *   - **Per-domain caching**: domains have different freshness needs, or
+ *     come from different transports.
+ *   - **Granularity**: you want to know exactly when a domain has landed
+ *     (`i18n:domain-loaded` signal).
+ *
+ * Use **`LazyTranslationProvider`** when the full locale bundle is
+ * reasonable to fetch up-front and you just want to organise translations
+ * across multiple files. See `LazyTranslationProvider.ts`.
+ *
+ * ## Tradeoff
+ *
+ * `t()` returns synchronously even for an unloaded domain — on first miss
+ * it returns the raw key (which renders as a placeholder for one frame),
+ * kicks off the async load, then emits `i18n:domain-loaded` once merged.
+ * The host app subscribes to that signal if it wants to react (e.g. force a
+ * re-render of components that hit the placeholder). Pre-warming via
+ * `i18n.loadDomain(domain)` avoids the placeholder entirely.
+ */
+
+import type { MessagesBundle, MessagesNode, TranslationProvider } from '@quazardous/qdcore'
+
+export type DomainLoader = (locale: string) => Promise<MessagesNode | null>
+
+export interface IncrementalDomainProviderOptions {
+  /** Provider name (for debugging / introspection). */
+  name?: string
+  /** Loader per top-level domain. Key is the domain (e.g. `core`, `shop`). */
+  domains: Record<string, DomainLoader>
+  /**
+   * Domains to load eagerly during `load(locale)` (i.e. on bootstrap or
+   * locale change). Default: empty — every domain is purely lazy.
+   */
+  eagerDomains?: string[]
+  /** Locales advertised through `availableLocales()`. */
+  locales?: string[]
+}
+
+export class IncrementalDomainProvider implements TranslationProvider {
+  readonly name: string
+  private readonly _domains: Record<string, DomainLoader>
+  private readonly _eagerDomains: string[]
+  private readonly _locales: string[] | undefined
+  private readonly _inflight: Map<string, Promise<MessagesBundle | null>> = new Map()
+
+  constructor(options: IncrementalDomainProviderOptions) {
+    this.name = options.name ?? 'incremental-domain'
+    this._domains = { ...options.domains }
+    this._eagerDomains = options.eagerDomains ? [...options.eagerDomains] : []
+    this._locales = options.locales ? [...options.locales] : undefined
+  }
+
+  /**
+   * Eagerly load only the domains listed in `eagerDomains`. Other domains
+   * are loaded on demand via `loadDomain`.
+   */
+  async load(locale: string): Promise<MessagesBundle> {
+    if (this._eagerDomains.length === 0) return {}
+    const merged: MessagesBundle = {}
+    await Promise.all(
+      this._eagerDomains.map(async (domain) => {
+        const partial = await this._loadDomain(locale, domain)
+        if (partial) Object.assign(merged, partial)
+      })
+    )
+    return merged
+  }
+
+  /**
+   * Returns whether this provider has a loader registered for `domain`.
+   * Used by `I18n.t()` to decide whether a miss can be recovered by a lazy
+   * load.
+   */
+  knowsDomain(domain: string): boolean {
+    return Object.prototype.hasOwnProperty.call(this._domains, domain)
+  }
+
+  /**
+   * Lazy-load a single domain. Concurrent calls for the same (locale, domain)
+   * pair share one in-flight promise. Returns the wrapped bundle (i.e.
+   * `{ [domain]: <node> }`) or `null` if the domain is unknown / loader
+   * returns nothing.
+   */
+  loadDomain(locale: string, domain: string): Promise<MessagesBundle | null> {
+    if (!this.knowsDomain(domain)) return Promise.resolve(null)
+    const cacheKey = `${locale}::${domain}`
+    const existing = this._inflight.get(cacheKey)
+    if (existing) return existing
+    const promise = this._loadDomain(locale, domain)
+    this._inflight.set(cacheKey, promise)
+    // Keep the inflight cache populated until the promise settles so a second
+    // concurrent caller dedupes; once settled, drop the entry — successive
+    // calls go through the loader again only if the I18n caller has lost
+    // track. In practice I18n keeps its own loaded set and won't re-call.
+    void promise.finally(() => {
+      this._inflight.delete(cacheKey)
+    })
+    return promise
+  }
+
+  availableLocales(): string[] {
+    return this._locales ? [...this._locales] : []
+  }
+
+  private async _loadDomain(
+    locale: string,
+    domain: string
+  ): Promise<MessagesBundle | null> {
+    const loader = this._domains[domain]
+    if (!loader) return null
+    const node = await loader(locale)
+    if (node === null || node === undefined) return null
+    return { [domain]: node }
+  }
+}
+
+/**
+ * Type guard: detects a provider that supports per-domain lazy loading.
+ * Used by I18n.t() to recover from a domain-miss without coupling I18n to
+ * the IncrementalDomainProvider class.
+ */
+export function isDomainAwareProvider(
+  p: TranslationProvider
+): p is TranslationProvider & {
+  loadDomain(locale: string, domain: string): Promise<MessagesBundle | null>
+  knowsDomain(domain: string): boolean
+} {
+  return (
+    typeof (p as { loadDomain?: unknown }).loadDomain === 'function' &&
+    typeof (p as { knowsDomain?: unknown }).knowsDomain === 'function'
+  )
+}

package/src/i18n/InlineTranslationProvider.ts

@@ -0,0 +1,4 @@
+/**
+ * InlineTranslationProvider — qdadm re-export from `@quazardous/qdcore/i18n`.
+ */
+export { InlineTranslationProvider } from '@quazardous/qdcore'

package/src/i18n/LazyTranslationProvider.ts

@@ -0,0 +1,102 @@
+/**
+ * LazyTranslationProvider - generic, format-agnostic provider that resolves
+ * locale bundles via a cascade of lazy loaders.
+ *
+ * Each loader is a `(locale) => Promise<MessagesBundle | null>` function. On
+ * `load(locale)`, the provider runs **all** loaders in order and deep-merges
+ * the partial bundles they return (later loaders override earlier ones —
+ * "last-merge-wins" semantics, same as the rest of the i18n stack).
+ *
+ * This lets consumers split bundles across multiple files — e.g. one loader
+ * for `core.*`, one for `entities.*`, one for `nav.*` — each backed by its
+ * own source (YAML file, JSON, fetch, etc.) without the provider knowing
+ * about any of those formats.
+ *
+ * ## When to use this vs `IncrementalDomainProvider`
+ *
+ * Use **`LazyTranslationProvider`** when you want one bundle per locale and
+ * don't care about loading domains independently:
+ *   - All loaders run on `_loadLocale(locale)` (i.e. bootstrap or locale
+ *     change). No partial state — once `bootstrap()` resolves, every key in
+ *     every domain is in the registry for that locale.
+ *   - Best for small/medium apps where the full bundle for a locale is
+ *     reasonable to fetch up-front.
+ *   - Domains are still split across files (the "cascade" lets you organise
+ *     translations by topic), they're just resolved together.
+ *
+ * Use **`IncrementalDomainProvider`** when domains should be loaded only on
+ * demand — `t('shop.cart.title')` for an unloaded `shop` domain triggers an
+ * async load in the background and emits `i18n:domain-loaded` once merged.
+ * Best for large apps with rarely-used sections (admin, legal, marketing
+ * landing pages, …) where shipping every domain on bootstrap would be
+ * wasteful. See `IncrementalDomainProvider.ts`.
+ */
+
+import type { MessagesBundle, MessagesNode, TranslationProvider } from '@quazardous/qdcore'
+
+export type LazyLoader = (locale: string) => Promise<MessagesBundle | null>
+
+export interface LazyTranslationProviderOptions {
+  /** Provider name (for debugging / introspection). */
+  name?: string
+  /** Cascade of loaders. Earlier loaders are overridden by later ones. */
+  loaders: LazyLoader[]
+  /**
+   * Locales advertised through `availableLocales()`. If omitted, the provider
+   * doesn't advertise any (callers should still be able to ask `load(locale)`
+   * — loaders that don't have the locale return null and are skipped).
+   */
+  locales?: string[]
+}
+
+export class LazyTranslationProvider implements TranslationProvider {
+  readonly name: string
+  private readonly _loaders: LazyLoader[]
+  private readonly _locales: string[] | undefined
+
+  constructor(options: LazyTranslationProviderOptions) {
+    this.name = options.name ?? 'lazy'
+    this._loaders = [...options.loaders]
+    this._locales = options.locales ? [...options.locales] : undefined
+  }
+
+  async load(locale: string): Promise<MessagesBundle> {
+    let merged: MessagesBundle = {}
+    for (const loader of this._loaders) {
+      const partial = await loader(locale)
+      if (partial && Object.keys(partial).length > 0) {
+        merged = deepMerge(merged, partial)
+      }
+    }
+    return merged
+  }
+
+  availableLocales(): string[] {
+    return this._locales ? [...this._locales] : []
+  }
+}
+
+/**
+ * Recursive merge of two MessagesBundle (or any plain-object MessagesNode):
+ * objects merge recursively, leaf values from `b` override leaf values from
+ * `a`. Arrays are replaced wholesale (we don't expect arrays in bundles, but
+ * be safe). Returns a new object — does not mutate inputs.
+ */
+function deepMerge(a: MessagesBundle, b: MessagesBundle): MessagesBundle
+function deepMerge(a: MessagesNode, b: MessagesNode): MessagesNode
+function deepMerge(a: MessagesNode, b: MessagesNode): MessagesNode {
+  if (!isPlainObject(a) || !isPlainObject(b)) return b
+  const out: Record<string, MessagesNode> = { ...(a as Record<string, MessagesNode>) }
+  for (const [key, bv] of Object.entries(b as Record<string, MessagesNode>)) {
+    const av = out[key]
+    out[key] =
+      isPlainObject(av) && isPlainObject(bv) ? (deepMerge(av, bv) as MessagesNode) : bv
+  }
+  return out as MessagesNode
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}

package/src/i18n/MessagesRegistry.ts

@@ -0,0 +1,4 @@
+/**
+ * MessagesRegistry — qdadm re-export from `@quazardous/qdcore/i18n`.
+ */
+export { MessagesRegistry } from '@quazardous/qdcore'

package/src/i18n/Resolver.ts

@@ -0,0 +1,4 @@
+/**
+ * Resolver — qdadm re-export from `@quazardous/qdcore/i18n`.
+ */
+export { Resolver, snakeCaseToTitle } from '@quazardous/qdcore'

package/src/i18n/__tests__/I18n.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest'
+
+import { I18n } from '../I18n'
+import type { TranslationProvider } from '../types'
+
+describe('I18n — bootstrap and lookup', () => {
+  it('ships default core EN bundle', async () => {
+    const i18n = new I18n()
+    await i18n.bootstrap()
+    expect(i18n.t('core.actions.save')).toBe('Save')
+    expect(i18n.t('core.errors.required')).toBe('Required')
+  })
+
+  it('disableDefaultCoreBundle skips default core', async () => {
+    const i18n = new I18n({ disableDefaultCoreBundle: true })
+    await i18n.bootstrap()
+    expect(i18n.t('core.actions.save')).toBe('core.actions.save')
+  })
+
+  it('addMessages from kernel options', async () => {
+    const i18n = new I18n({
+      messages: {
+        en: { entities: { books: { fields: { title: 'Title' } } } },
+      },
+    })
+    await i18n.bootstrap()
+    expect(i18n.t('entities.books.fields.title')).toBe('Title')
+  })
+
+  it('addMessages after bootstrap is immediately visible', async () => {
+    const i18n = new I18n()
+    await i18n.bootstrap()
+    i18n.addMessages('en', { entities: { books: { fields: { author: 'Author' } } } })
+    expect(i18n.t('entities.books.fields.author')).toBe('Author')
+  })
+})
+
+describe('I18n — global strategy (default)', () => {
+  it('routes entities.*.actions.* to core.actions.*', async () => {
+    const i18n = new I18n()
+    await i18n.bootstrap()
+    expect(i18n.t('entities.books.actions.save')).toBe('Save')
+    expect(i18n.t('entities.users.actions.delete')).toBe('Delete')
+  })
+
+  it('routes entities.*.fields.created_at to core.fields.created_at', async () => {
+    const i18n = new I18n()
+    await i18n.bootstrap()
+    expect(i18n.t('entities.books.fields.created_at')).toBe('Created at')
+  })
+})
+
+describe('I18n — module strategy', () => {
+  it('routes entities.<entity>.* to modules.<module>.* with fallback to core', async () => {
+    const i18n = new I18n({ keyStrategy: 'module' })
+    i18n.registerEntityModule('books', 'BooksModule')
+    await i18n.bootstrap()
+    i18n.addMessages('en', {
+      modules: {
+        BooksModule: { actions: { delete: 'Discard' } },
+      },
+    })
+    // Module override wins
+    expect(i18n.t('entities.books.actions.delete')).toBe('Discard')
+    // Fallback through module → core
+    expect(i18n.t('entities.books.actions.save')).toBe('Save')
+  })
+})
+
+describe('I18n — locale change', () => {
+  it('emits locale:changed signal', async () => {
+    const events: Array<{ signal: string; data: unknown }> = []
+    const signals = {
+      emit: (signal: string, data: unknown) => {
+        events.push({ signal, data })
+      },
+      on: () => () => {},
+    }
+    const i18n = new I18n({ defaultLocale: 'en' }, { signals })
+    await i18n.bootstrap()
+    i18n.addMessages('fr', { core: { actions: { save: 'Enregistrer' } } })
+    await i18n.changeLocale('fr')
+    expect(i18n.locale.value).toBe('fr')
+    expect(i18n.t('core.actions.save')).toBe('Enregistrer')
+    const emitted = events.find((e) => e.signal === 'locale:changed')
+    expect(emitted).toBeDefined()
+    expect(emitted?.data).toBe('fr')
+  })
+
+  it('falls back to fallbackLocale for missing keys', async () => {
+    // disableDefaultCoreBundle so we can assert pure fallback behavior without
+    // the shipped FR bundle filling `core.actions.save` first.
+    const i18n = new I18n({
+      defaultLocale: 'en',
+      fallbackLocale: 'en',
+      disableDefaultCoreBundle: true,
+    })
+    i18n.addMessages('en', { core: { actions: { save: 'Save' } } })
+    i18n.addMessages('fr', { entities: { books: { fields: { title: 'Titre' } } } })
+    await i18n.bootstrap()
+    await i18n.changeLocale('fr')
+    expect(i18n.t('entities.books.fields.title')).toBe('Titre')
+    // 'core.actions.save' not declared in fr → falls back to en
+    expect(i18n.t('core.actions.save')).toBe('Save')
+  })
+})
+
+describe('I18n — providers', () => {
+  it('loads from a custom TranslationProvider during bootstrap', async () => {
+    const provider: TranslationProvider = {
+      name: 'mock',
+      load: (locale) => {
+        if (locale === 'en') {
+          return { entities: { tasks: { fields: { name: 'Task name' } } } }
+        }
+        return {}
+      },
+      availableLocales: () => ['en'],
+    }
+    const i18n = new I18n({ providers: [provider] })
+    await i18n.bootstrap()
+    expect(i18n.t('entities.tasks.fields.name')).toBe('Task name')
+  })
+
+  it('async provider load works', async () => {
+    const provider: TranslationProvider = {
+      name: 'async-mock',
+      load: async (locale) => {
+        await new Promise((r) => setTimeout(r, 5))
+        if (locale === 'en') {
+          return { foo: { bar: 'Async value' } }
+        }
+        return {}
+      },
+    }
+    const i18n = new I18n({ providers: [provider] })
+    await i18n.bootstrap()
+    expect(i18n.t('foo.bar')).toBe('Async value')
+  })
+
+  it('availableLocales unions across providers', async () => {
+    const a: TranslationProvider = {
+      name: 'a',
+      load: () => ({}),
+      availableLocales: () => ['en', 'fr'],
+    }
+    const b: TranslationProvider = {
+      name: 'b',
+      load: () => ({}),
+      availableLocales: async () => ['de', 'fr'],
+    }
+    const i18n = new I18n({ providers: [a, b] })
+    const locales = await i18n.availableLocales()
+    expect(new Set(locales)).toEqual(new Set(['en', 'fr', 'de']))
+  })
+})
+
+describe('I18n — dump', () => {
+  it('returns the inline bundle (app-level messages only, not framework defaults)', async () => {
+    const i18n = new I18n()
+    await i18n.bootstrap()
+    i18n.addMessages('en', { entities: { books: { fields: { title: 'Title' } } } })
+    const dumped = i18n.dump('en')
+    expect(dumped.entities?.books?.fields?.title).toBe('Title')
+    // Framework defaults (core.*) ship via DefaultCoreProvider, not the inline
+    // provider, so they don't show up in dump().
+    expect(dumped.core).toBeUndefined()
+  })
+})

package/src/i18n/__tests__/IncrementalDomainProvider.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi } from 'vitest'
+
+import { I18n } from '../I18n'
+import { IncrementalDomainProvider, type DomainLoader } from '../IncrementalDomainProvider'
+
+function makeSignals() {
+  const events: Array<{ signal: string; data: unknown }> = []
+  const handlers = new Map<string, Array<(e: { data: unknown }) => void>>()
+  return {
+    events,
+    bus: {
+      emit: (signal: string, data: unknown) => {
+        events.push({ signal, data })
+        for (const h of handlers.get(signal) ?? []) h({ data })
+      },
+      on: (signal: string, handler: (e: { data: unknown }) => void) => {
+        const list = handlers.get(signal) ?? []
+        list.push(handler)
+        handlers.set(signal, list)
+        return () => {}
+      },
+    },
+  }
+}
+
+describe('IncrementalDomainProvider — lazy-by-domain', () => {
+  it('only loads eagerDomains during bootstrap; lazy domains stay dormant', async () => {
+    const coreLoader = vi.fn(async () => ({ actions: { save: 'Save' } }))
+    const shopLoader = vi.fn(async () => ({ cart: { title: 'Cart' } }))
+
+    const provider = new IncrementalDomainProvider({
+      domains: { core: coreLoader, shop: shopLoader },
+      eagerDomains: ['core'],
+      locales: ['en'],
+    })
+
+    const i18n = new I18n({ disableDefaultCoreBundle: true, providers: [provider] })
+    await i18n.bootstrap()
+
+    expect(coreLoader).toHaveBeenCalledTimes(1)
+    expect(shopLoader).not.toHaveBeenCalled()
+    expect(i18n.t('core.actions.save')).toBe('Save')
+  })
+
+  it('t() on an unloaded domain triggers a lazy load + emits i18n:domain-loaded', async () => {
+    const shopLoader = vi.fn(async () => ({ cart: { title: 'Cart' } }))
+
+    const provider = new IncrementalDomainProvider({
+      domains: { shop: shopLoader },
+      locales: ['en'],
+    })
+
+    const sig = makeSignals()
+    const i18n = new I18n(
+      { disableDefaultCoreBundle: true, providers: [provider] },
+      { signals: sig.bus }
+    )
+    await i18n.bootstrap()
+
+    // First call: shop not loaded yet → returns the raw key, kicks off load
+    const first = i18n.t('shop.cart.title')
+    expect(first).toBe('shop.cart.title')
+
+    // Wait one microtask tick for the async load to settle
+    await vi.waitFor(() => {
+      expect(sig.events.find((e) => e.signal === 'i18n:domain-loaded')).toBeDefined()
+    })
+
+    expect(shopLoader).toHaveBeenCalledTimes(1)
+
+    // Second call: domain is in the registry now
+    expect(i18n.t('shop.cart.title')).toBe('Cart')
+
+    // Signal payload identifies the domain + locale
+    const loaded = sig.events.find((e) => e.signal === 'i18n:domain-loaded')
+    expect(loaded?.data).toEqual({ locale: 'en', domain: 'shop' })
+  })
+
+  it('dedupes concurrent lazy loads for the same (locale, domain)', async () => {
+    let resolveLoader: ((value: unknown) => void) | undefined
+    const shopLoader = vi.fn(
+      () =>
+        new Promise<{ cart: { title: string } }>((resolve) => {
+          resolveLoader = resolve as (v: unknown) => void
+        })
+    )
+
+    const provider = new IncrementalDomainProvider({
+      domains: { shop: shopLoader as DomainLoader },
+      locales: ['en'],
+    })
+
+    const i18n = new I18n({ disableDefaultCoreBundle: true, providers: [provider] })
+    await i18n.bootstrap()
+
+    // 50 concurrent lookups during the inflight window
+    for (let i = 0; i < 50; i++) i18n.t('shop.cart.title')
+
+    expect(shopLoader).toHaveBeenCalledTimes(1)
+    resolveLoader?.({ cart: { title: 'Cart' } })
+    await new Promise((r) => setTimeout(r, 0))
+
+    expect(i18n.t('shop.cart.title')).toBe('Cart')
+  })
+
+  it('loadDomain() lets the app pre-warm a domain explicitly', async () => {
+    const shopLoader = vi.fn(async () => ({ cart: { title: 'Cart' } }))
+
+    const provider = new IncrementalDomainProvider({
+      domains: { shop: shopLoader },
+      locales: ['en'],
+    })
+
+    const i18n = new I18n({ disableDefaultCoreBundle: true, providers: [provider] })
+    await i18n.bootstrap()
+
+    await i18n.loadDomain('shop')
+    // After explicit pre-warm, t() resolves immediately — no placeholder
+    expect(i18n.t('shop.cart.title')).toBe('Cart')
+    expect(shopLoader).toHaveBeenCalledTimes(1)
+  })
+
+  it('miss on a domain known to no provider stays a miss (no infinite trigger)', async () => {
+    const shopLoader = vi.fn(async () => ({ cart: { title: 'Cart' } }))
+    const provider = new IncrementalDomainProvider({
+      domains: { shop: shopLoader },
+      locales: ['en'],
+    })
+
+    const sig = makeSignals()
+    const i18n = new I18n(
+      { disableDefaultCoreBundle: true, providers: [provider] },
+      { signals: sig.bus }
+    )
+    await i18n.bootstrap()
+
+    // `legal.*` is unknown to every provider → no load attempt
+    i18n.t('legal.tos.title')
+    i18n.t('legal.tos.title')
+    i18n.t('legal.tos.title')
+    await new Promise((r) => setTimeout(r, 0))
+
+    expect(shopLoader).not.toHaveBeenCalled()
+    expect(sig.events.some((e) => e.signal === 'i18n:domain-loaded')).toBe(false)
+  })
+})

package/src/i18n/__tests__/LazyTranslationProvider.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest'
+
+import { I18n } from '../I18n'
+import { LazyTranslationProvider, type LazyLoader } from '../LazyTranslationProvider'
+
+describe('LazyTranslationProvider — domain cascade', () => {
+  it('merges partial bundles from multiple domain loaders', async () => {
+    const coreLoader: LazyLoader = async (locale) =>
+      locale === 'en'
+        ? { core: { actions: { save: 'Save', cancel: 'Cancel' } } }
+        : null
+    const shopLoader: LazyLoader = async (locale) =>
+      locale === 'en'
+        ? { shop: { cart: { title: 'Your cart', empty: 'Cart is empty' } } }
+        : null
+    const legalLoader: LazyLoader = async (locale) =>
+      locale === 'en' ? { legal: { tos: { title: 'Terms of Service' } } } : null
+
+    const provider = new LazyTranslationProvider({
+      name: 'composite',
+      loaders: [coreLoader, shopLoader, legalLoader],
+      locales: ['en'],
+    })
+
+    const i18n = new I18n({ disableDefaultCoreBundle: true, providers: [provider] })
+    await i18n.bootstrap()
+
+    expect(i18n.t('core.actions.save')).toBe('Save')
+    expect(i18n.t('shop.cart.title')).toBe('Your cart')
+    expect(i18n.t('shop.cart.empty')).toBe('Cart is empty')
+    expect(i18n.t('legal.tos.title')).toBe('Terms of Service')
+  })
+
+  it('later loaders override earlier ones (last-merge-wins)', async () => {
+    const baseLoader: LazyLoader = async () => ({
+      core: { actions: { save: 'Base save' } },
+      shop: { cart: { title: 'Base cart' } },
+    })
+    const overrideLoader: LazyLoader = async () => ({
+      core: { actions: { save: 'Override save' } },
+    })
+
+    const provider = new LazyTranslationProvider({
+      loaders: [baseLoader, overrideLoader],
+      locales: ['en'],
+    })
+
+    const i18n = new I18n({ disableDefaultCoreBundle: true, providers: [provider] })
+    await i18n.bootstrap()
+
+    // overridden by later loader
+    expect(i18n.t('core.actions.save')).toBe('Override save')
+    // untouched by override → still from base loader
+    expect(i18n.t('shop.cart.title')).toBe('Base cart')
+  })
+
+  it('loader returning null is skipped', async () => {
+    const presentLoader: LazyLoader = async () => ({
+      shop: { cart: { title: 'Cart' } },
+    })
+    const missingLoader: LazyLoader = async () => null
+
+    const provider = new LazyTranslationProvider({
+      loaders: [missingLoader, presentLoader, missingLoader],
+      locales: ['en'],
+    })
+
+    const i18n = new I18n({ disableDefaultCoreBundle: true, providers: [provider] })
+    await i18n.bootstrap()
+
+    expect(i18n.t('shop.cart.title')).toBe('Cart')
+  })
+
+  it('availableLocales reflects the configured locales', () => {
+    const provider = new LazyTranslationProvider({
+      loaders: [async () => ({})],
+      locales: ['en', 'fr', 'de'],
+    })
+    expect(new Set(provider.availableLocales())).toEqual(new Set(['en', 'fr', 'de']))
+  })
+
+  it('two providers chained: the later one in options.providers wins', async () => {
+    const baseProvider = new LazyTranslationProvider({
+      loaders: [async () => ({ shop: { cart: { title: 'Default cart' } } })],
+      locales: ['en'],
+    })
+    const overrideProvider = new LazyTranslationProvider({
+      loaders: [async () => ({ shop: { cart: { title: 'Override cart' } } })],
+      locales: ['en'],
+    })
+
+    const i18n = new I18n({
+      disableDefaultCoreBundle: true,
+      providers: [baseProvider, overrideProvider],
+    })
+    await i18n.bootstrap()
+
+    expect(i18n.t('shop.cart.title')).toBe('Override cart')
+  })
+})