@owlmeans/i18n 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -11,7 +11,7 @@ Multi-level translation resource registration for OwlMeans applications.
 ## Installation
 
 ```bash
-bun add @owlmeans/i18n@^0.1.18-rc.7
+bun add @owlmeans/i18n@^0.1.18
 ```
 
 ## Usage
@@ -19,32 +19,42 @@ bun add @owlmeans/i18n@^0.1.18-rc.7
 Register translations for a package at startup:
 
 ```typescript
-import { addI18nApp } from '@owlmeans/i18n'
+import { i18nHelper } from '@owlmeans/i18n'
 
 // Register app-level translations (highest priority)
-addI18nApp('en', 'manager-web', {
+i18nHelper.addI18nApp('en', 'manager-web', {
   'project.create.title': 'Create Project',
   'project.create.submit': 'Create',
 })
 
 // Register library-level translations (lower priority — overridable by apps)
-import { addI18n } from '@owlmeans/i18n'
-addI18n('en', 'client-panel', { 'form.submit': 'Submit' })
+i18nHelper.addI18nLib('en', 'client-panel', { 'form.submit': 'Submit' })
 ```
 
 ## API
 
-### `addI18nApp(lng, resource, data, opts?)`
+All registration and loading goes through the `i18nHelper` object (`createI18nHelper()` builds one
+over the same process-wide storage).
 
-Register translations at app priority (highest). Typically called in `src/i18n.ts`.
+### `i18nHelper.addI18nApp(lng, resource, data, opts?)`
 
-### `addI18n(level, lng, resource, data, opts?)`
+Register translations at app tier (highest). Typically called in `src/i18n.ts`.
 
-Register translations at a specific `I18nLevel`. Lower levels are overridden by higher ones.
+### `i18nHelper.addI18nLib(lng, resource, data, opts?)`
 
-### `I18nLevel`
+Register translations at library tier (namespace `lib` by default). App-tier bundles override them.
 
-Priority levels: `Lib` < `Package` < `App`. App-level translations win over library translations for the same key.
+### `i18nHelper.initI18nResource(lng, resource, ns?)` / `i18nHelper.resolveI18nResource(lng, resource, ns?)`
+
+Drain the bundles of one slot in merge order, or read their merged result without draining.
+
+### `i18nHelper.addI18nLoader(lng, loader)` / `i18nHelper.loadI18nLanguage(lng)` / `i18nHelper.isI18nLanguageLoaded(lng)`
+
+Register lazy language loaders, await them, and check whether they completed.
+
+### `I18nTier`
+
+Priority tiers: `Library` < `App`. App-tier translations win over library translations for the same key.
 
 ### `i18nStorage`
 
@@ -62,7 +72,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.13
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/i18n",
-  "version": "0.1.18-rc.9",
-  "generatedAt": "2026-09-10T18:54:42.484Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.701Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/i18n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: i18n
-description: How to use @owlmeans/i18n — the core localization registry (no runtime deps). Auto-invoked when adding translatable strings to a library package, importing from this package, or working with the tier/priority system.
+description: How to use @owlmeans/i18n — the core localization registry (no runtime deps). Auto-invoked when adding translatable strings to a library package, importing from this package, working with the tier/priority system, or deferring a language pack with i18nHelper.addI18nLoader/loadI18nLanguage.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,19 +8,23 @@ user-invocable: false
 # @owlmeans/i18n
 
 **Layer:** Core (no runtime deps)
-**Install:** `"@owlmeans/i18n": "^0.1.18-rc.9"` in `dependencies`
+**Install:** `"@owlmeans/i18n": "^0.1.18"` in `dependencies`
 
 ## Purpose
 
-Global registration store that packages write into at import time. React clients drain it lazily via `@owlmeans/client-i18n`. The store is addressed by **(ns, resource, language)**.
+Global registration store that packages write into at import time — or, for an application's deferred language packs, from an async loader. React clients drain it lazily via `@owlmeans/client-i18n`. The store is addressed by **(ns, resource, language)**.
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `addI18nLib(lng, resource, data, opts?)` | Register library-owned strings (ns defaults to `'lib'`) |
-| `addI18nApp(lng, resource, data, opts?)` | Register app-owned strings (ns defaults to resource name) |
-| `initI18nResource(lng, resource, ns?)` | Drain a registered bundle for a language (called by client-i18n) |
+| `i18nHelper.addI18nLib(lng, resource, data, opts?)` | Register library-owned strings (ns defaults to `'lib'`) |
+| `i18nHelper.addI18nApp(lng, resource, data, opts?)` | Register app-owned strings (ns defaults to resource name) |
+| `i18nHelper.initI18nResource(lng, resource, ns?)` | Drain a registered bundle for a language (called by client-i18n) |
+| `i18nHelper.resolveI18nResource(lng, resource, ns = DEFAULT_NAMESPACE)` | The merged bundle of ANY language, read WITHOUT draining it — `null` when nothing is registered (see § Reading without draining) |
+| `i18nHelper.addI18nLoader(lng, loader)` | Register an async `I18nLoader` (`() => Promise<unknown>`, typically a dynamic `import()` of a module that calls `i18nHelper.addI18nLib` / `addI18nApp`) for a language — see Deferred language packs |
+| `i18nHelper.loadI18nLanguage(lng)` | Await every loader registered for `lng`; idempotent, retries a failed loader |
+| `i18nHelper.isI18nLanguageLoaded(lng)` | Whether every loader of `lng` has completed; `true` for a language with none |
 | `SUPPORTED_LNGS` / `SupportedLng` | `['en','pl','ru','be','uk','es','de']` — the canonical language set, and its union type |
 | `DEFAULT_LNG` | `'en'` |
 | `LIB_NAMESPACE` | `'lib'` |
@@ -30,35 +34,37 @@ Global registration store that packages write into at import time. React clients
 | `I18nResourceOptions` | `{ ns?, priority? }` — the `opts` every `add*` takes |
 | `MAX_PRIORITY` | `Number.MAX_SAFE_INTEGER` — the value substituted for an unset `priority`, which is what makes an unset one sort last |
 
-`opts` also accepts a bare string, which is read as `ns`: `addI18nLib('en', 'wallet', walletEn, 'did')`.
+`opts` also accepts a bare string, which is read as `ns`:
+`i18nHelper.addI18nLib('en', 'wallet', walletEn, 'did')`.
 
 ## Subpath Exports
 
-- `./utils` — the store itself: `_OwlMeansI18nStorage` (`{ data }`, keyed ns → resource → language),
-  `ensureStructure(lng, resource, ns?)` which creates and returns one slot, and `tierCost`, the
-  `I18nTier` → number map the sort is written against.
+- `./utils` — the store itself: `_OwlMeansI18nStorage` (`{ data }`, keyed ns → resource → language)
+  and `tierCost`, the `I18nTier` → number map the sort is written against; plus the separate loader
+  store `_OwlMeansI18nLoaders` (`{ data }`, keyed by language).
 
 Reach for `./utils` only to work around the drain-once rule below: assigning
 `_OwlMeansI18nStorage.data = {}` empties every slot including its `lngInitialized` marks, so a
-suite can register and drain the same resource repeatedly. This package's own tests do exactly
-that between cases. Application and library code registers through `addI18nLib` / `addI18nApp`.
+suite can register and drain the same resource repeatedly; `_OwlMeansI18nLoaders.data = {}`
+forgets every loader and request mark. This package's own tests reset both between cases.
+Application and library code registers through `i18nHelper.addI18nLib` / `addI18nApp`.
 
 ## Tiers
 
 | Tier | Helper | Default ns | When to use |
 |------|--------|-----------|-------------|
-| Library | `addI18nLib` | `'lib'` | Any `@owlmeans/*` package |
-| App | `addI18nApp` | resource name | Project-specific app / shared project package |
+| Library | `i18nHelper.addI18nLib` | `'lib'` | Any `@owlmeans/*` package |
+| App | `i18nHelper.addI18nApp` | resource name | Project-specific app / shared project package |
 
 App-tier strings deep-merge **over** Library-tier strings at resolution time — but only for the
 same **(ns, resource, language)** slot, because that triple is the address the store is keyed on
-and the only thing `initI18nResource` drains. The default namespaces differ (`'lib'` for
+and the only thing `i18nHelper.initI18nResource` drains. The default namespaces differ (`'lib'` for
 `addI18nLib`, the resource name for `addI18nApp`), so overriding a library bundle means saying so:
 
 ```typescript
-import { addI18nApp, LIB_NAMESPACE } from '@owlmeans/i18n'
+import { i18nHelper, LIB_NAMESPACE } from '@owlmeans/i18n'
 
-addI18nApp('en', 'errors', myErrors, { ns: LIB_NAMESPACE })
+i18nHelper.addI18nApp('en', 'errors', myErrors, { ns: LIB_NAMESPACE })
 ```
 
 Without `{ ns: LIB_NAMESPACE }` the app bundle lands in namespace `errors` while the library's sits
@@ -69,11 +75,35 @@ it — so the **last** applied wins. A registration that states no `priority` so
 therefore beats every one that states a number: `priority` lowers a bundle in the stack rather than
 raising it. Leave it unset unless one library must lose to another.
 
-**A bundle only reaches i18next if it was registered before the first draw for its language.**
-`initI18nResource` marks the (ns, resource, language) slot drained and answers `null` for every
-later call, so an `import '@owlmeans/<pkg>'` evaluated after a screen has rendered adds nothing a
-component can read. Register at module load — a side-effect import at the top of the entry file,
-which is what re-exporting `./i18n.js` from `src/index.ts` achieves.
+**A bundle only reaches i18next if it was REGISTERED before its slot is first drained.**
+`i18nHelper.initI18nResource` reads a (ns, resource, language) slot exactly once — it marks the slot
+drained and answers `null` for every later call — so a bundle registered through `addI18nLib` /
+`addI18nApp` after a screen has drawn that language adds nothing a component can read. Registering
+synchronously at import time is the simplest way to guarantee it — a side-effect import at the top
+of the entry file, which is what re-exporting `./i18n.js` from `src/index.ts` achieves. The loader
+API (`i18nHelper.addI18nLoader` / `loadI18nLanguage`) lets an application defer registration to an
+async load instead, AS LONG AS it awaits `i18nHelper.loadI18nLanguage` — or
+`@owlmeans/client-i18n`'s `i18nInstanceHelper.prepareI18n` — before the first render that would
+drain that language.
+
+## Reading without draining
+
+`i18nHelper.resolveI18nResource(lng, resource, ns)` deep-merges every bundle registered for the slot
+in the exact order `initI18nResource` hands them out — library tier, then app tier, `priority`
+ascending, an unset priority last — so an app override wins as it does in i18next. Plain objects
+merge key by key; any other value replaces (arrays are copied). It never marks the slot drained and
+never creates an empty slot, so a later `initI18nResource` still returns the same bundles, and a
+drained slot still resolves. The result never aliases a registered bundle.
+
+Use it where there is no i18next instance or the language is not the active one: a server
+rendering an e-mail or a paygate text, a legal text shown in the billing country's language while
+the interface speaks another (`@owlmeans/payment`'s `consumerCopyHelper.consumerRightsCopy` is built
+on it). Pass the namespace the bundle lives in — `LIB_NAMESPACE` for an `i18nHelper.addI18nLib`
+bundle; the default is i18next's own `'translation'`.
+
+It reads only what is REGISTERED: a language an application defers to a loader (Deferred language
+packs) resolves `null` — or without its app-tier overrides — until
+`await i18nHelper.loadI18nLanguage(lng)` has run for it.
 
 ## Per-package pattern
 
@@ -81,7 +111,7 @@ Every package that ships translatable strings exports a side-effect `i18n.ts`:
 
 ```typescript
 // src/i18n.ts
-import { addI18nLib } from '@owlmeans/i18n'
+import { i18nHelper } from '@owlmeans/i18n'
 import en from './i18n/en.json' with { type: 'json' }
 import pl from './i18n/pl.json' with { type: 'json' }
 import ru from './i18n/ru.json' with { type: 'json' }
@@ -89,14 +119,16 @@ import be from './i18n/be.json' with { type: 'json' }
 import uk from './i18n/uk.json' with { type: 'json' }
 import es from './i18n/es.json' with { type: 'json' }
 import de from './i18n/de.json' with { type: 'json' }
-
-addI18nLib('en', 'my-package', en)
-addI18nLib('pl', 'my-package', pl)
-addI18nLib('ru', 'my-package', ru)
-addI18nLib('be', 'my-package', be)
-addI18nLib('uk', 'my-package', uk)
-addI18nLib('es', 'my-package', es)
-addI18nLib('de', 'my-package', de)
+import fr from './i18n/fr.json' with { type: 'json' }
+
+i18nHelper.addI18nLib('en', 'my-package', en)
+i18nHelper.addI18nLib('pl', 'my-package', pl)
+i18nHelper.addI18nLib('ru', 'my-package', ru)
+i18nHelper.addI18nLib('be', 'my-package', be)
+i18nHelper.addI18nLib('uk', 'my-package', uk)
+i18nHelper.addI18nLib('es', 'my-package', es)
+i18nHelper.addI18nLib('de', 'my-package', de)
+i18nHelper.addI18nLib('fr', 'my-package', fr)
 ```
 
 Then re-export from `src/index.ts`:
@@ -123,12 +155,45 @@ Consumers use `useI18nLib('my-package', 'mySection')` → `t('title')` → resol
 
 Use the optional `opts.ns` when keys must live in a namespace other than `'lib'`:
 ```typescript
-addI18nLib('en', 'wallet', walletEn, { ns: 'did' })
+i18nHelper.addI18nLib('en', 'wallet', walletEn, { ns: 'did' })
 ```
 
 ## Languages
 
-All packages **must** ship all 7 languages from `SUPPORTED_LNGS`. Adding a new key → add it to all 7 files in the same commit.
+All packages **must** ship the 7 languages from `SUPPORTED_LNGS`. Adding a new key → add it to all
+7 files in the same commit. An application may opt into an additional language without changing the
+global constant; a reusable package used by that application then ships and synchronously registers
+the same extra bundle, while other applications retain their existing selectable languages.
+
+### Deferred language packs (applications only)
+
+An application may keep a language's bundles out of its initial chunk and register them from a
+loader. The loader store is separate from the resource store: a loader only REGISTERS (it calls
+`i18nHelper.addI18nLib` / `addI18nApp` once its module evaluates); draining stays
+`initI18nResource`'s, once per slot, unchanged.
+
+```typescript
+// app entry, module scope — each module calls i18nHelper.addI18nApp('<lng>', …) when it evaluates
+i18nHelper.addI18nLoader('de', () => import('./i18n/de.js'))
+i18nHelper.addI18nLoader('pl', () => import('./i18n/pl.js'))
+```
+
+- A loader does not run until its language is requested by `i18nHelper.loadI18nLanguage(lng)`; one
+  registered AFTER the language was requested starts at once, so a module evaluated late is never
+  skipped.
+- `i18nHelper.loadI18nLanguage(lng)` resolves once every loader of `lng` has completed — including
+  loaders added while the call is in flight; one added after a call resolved is awaited by the next
+  call. Concurrent and repeated calls share in-flight runs and never re-run a completed loader.
+- A failure rejects the call once the pass has settled; the failed loader alone is retried by the
+  next call, never cached as failed.
+- The app awaits the fallback and the initial language before its first render —
+  `@owlmeans/client-i18n`'s `i18nInstanceHelper.prepareI18n` does both — and its
+  `i18nInstanceHelper.setLanguage` / `useLanguage` load a language before switching to it.
+  `@owlmeans/web-panel` re-exports `i18nHelper` (the loader API included) but not
+  `i18nInstanceHelper` — import that from `@owlmeans/client-i18n`.
+
+A library package never defers: it registers every language synchronously at import (Per-package
+pattern), because it cannot know the application it lands in awaits a boot step.
 
 ## Depends On
 

package/agent-meta/skills/localization/SKILL.md

@@ -21,8 +21,8 @@ Keys are addressed as: `(namespace, resource.prefix.key)`.
 
 | Who registers | Helper | namespace | key path |
 |---|---|---|---|
-| `@owlmeans/*` library package | `addI18nLib` | `'lib'` | `resource.prefix.key` |
-| App or shared project package | `addI18nApp` | resource name | `resource.prefix.key` |
+| `@owlmeans/*` library package | `i18nHelper.addI18nLib` | `'lib'` | `resource.prefix.key` |
+| App or shared project package | `i18nHelper.addI18nApp` | resource name | `resource.prefix.key` |
 
 The **resource name** is a stable identifier for the registering package, e.g. `'errors'`, `'payment'`, `'viable-manager-web'`.
 
@@ -32,7 +32,7 @@ A key like `t('title')` resolves to `namespace : resource.prefix.key`. The prefi
 
 Example chain:
 ```
-addI18nApp('en', 'viable-manager-web', data)
+i18nHelper.addI18nApp('en', 'viable-manager-web', data)
 // data = { "home-screen": { "title": "Welcome" } }
 
 const t = useI18nApp(undefined, 'home-screen')
@@ -84,14 +84,14 @@ fallbacks; a surrounding `PanelContext` is what redirects it.
 ## App-level override of library strings
 
 App-tier registrations deep-merge over Library-tier for the same `(ns, resource)` — and the
-namespace has to be said out loud, because `addI18nApp` defaults it to the **resource** name while
-the library's bundle sits in `lib`:
+namespace has to be said out loud, because `i18nHelper.addI18nApp` defaults it to the **resource**
+name while the library's bundle sits in `lib`:
 ```typescript
 import '@owlmeans/error'                              // Library tier: lib:errors.*
-import { addI18nApp, LIB_NAMESPACE } from '@owlmeans/i18n'
+import { i18nHelper, LIB_NAMESPACE } from '@owlmeans/i18n'
 import myErrors from './i18n/en.json'
 
-addI18nApp('en', 'errors', myErrors, { ns: LIB_NAMESPACE })   // App tier wins for matching keys
+i18nHelper.addI18nApp('en', 'errors', myErrors, { ns: LIB_NAMESPACE })   // App tier wins for matching keys
 ```
 
 Drop `{ ns: LIB_NAMESPACE }` and the app bundle lands in namespace `errors` while `useI18nLib('errors')`
@@ -106,9 +106,17 @@ When adding translatable strings to any package:
 3. Re-export from `src/index.ts`: `export * from './i18n.js'`
 4. In components, use `useI18nLib` (library package) or `useI18nApp` (app package) — never hardcode UI strings
 
+A library package (`@owlmeans/*`) always registers every language synchronously at import: it has
+no boot step that could await a loader, and a bundle registered after its slot was first drained
+never renders. An APPLICATION may instead defer a language's pack with `i18nHelper.addI18nLoader`,
+provided it `await`s `i18nInstanceHelper.prepareI18n(config)` before its first render (`i18n`,
+`client-i18n` skills).
+
 ## Language switcher
 
 Use `useLanguage()` from `@owlmeans/client-i18n`. The selection is persisted to `localStorage`.
+The setter is async — it loads a deferred pack before switching — and the returned language is
+i18next's own, so it changes only once the switch has happened.
 
 ```tsx
 import { useLanguage } from '@owlmeans/client-i18n'

package/build/consts.d.ts

@@ -2,7 +2,6 @@ export declare const DEFAULT_NAMESPACE = "translation";
 export declare const LIB_NAMESPACE = "lib";
 export declare const DEFAULT_LNG = "en";
 export declare const SUPPORTED_LNGS: readonly ['en', 'pl', 'ru', 'be', 'uk', 'es', 'de'];
-export type SupportedLng = (typeof SUPPORTED_LNGS)[number];
 export declare const MAX_PRIORITY: number;
 export declare enum I18nTier {
     Library = "library",

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,iBAAiB,gBAAgB,CAAA;AAE9C,eAAO,MAAM,aAAa,QAAQ,CAAA;AAElC,eAAO,MAAM,WAAW,OAAO,CAAA;AAE/B,eAAO,MAAM,cAAc,YAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAA;AAEjF,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAE1D,eAAO,MAAM,YAAY,QAA0B,CAAA;AAEnD,oBAAY,QAAQ;IAClB,OAAO,YAAY;IACnB,GAAG,QAAQ;CACZ;AAED,+BAA+B;AAC/B,eAAO,MAAM,SAAS,iBAAW,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,iBAAiB,gBAAgB,CAAA;AAE9C,eAAO,MAAM,aAAa,QAAQ,CAAA;AAElC,eAAO,MAAM,WAAW,OAAO,CAAA;AAE/B,eAAO,MAAM,cAAc,YAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAA;AAEjF,eAAO,MAAM,YAAY,QAA0B,CAAA;AAEnD,oBAAY,QAAQ;IAClB,OAAO,YAAY;IACnB,GAAG,QAAQ;CACZ;AAED,+BAA+B;AAC/B,eAAO,MAAM,SAAS,iBAAW,CAAA"}

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAA;AAE9C,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAA;AAElC,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAA;AAE/B,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAA;AAIjF,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,gBAAgB,CAAA;AAEnD,MAAM,CAAN,IAAY,QAGX;AAHD,WAAY,QAAQ;IAClB,+BAAmB,CAAA;IACnB,uBAAW,CAAA;AACb,CAAC,EAHW,QAAQ,KAAR,QAAQ,QAGnB;AAED,+BAA+B;AAC/B,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAA;AAE9C,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAA;AAElC,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAA;AAE/B,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAA;AAEjF,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,gBAAgB,CAAA;AAEnD,MAAM,CAAN,IAAY,QAGX;AAHD,WAAY,QAAQ;IAClB,+BAAmB,CAAA;IACnB,uBAAW,CAAA;AACb,CAAC,EAHW,QAAQ,KAAR,QAAQ,QAGnB;AAED,+BAA+B;AAC/B,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAA"}

package/build/helper/types.d.ts

@@ -0,0 +1,46 @@
+import type { I18nLeveledResourceSignature, I18nLoader, I18nResource } from '../types.js';
+/** The process-wide i18n registry: resource bundles per (ns, resource, language) and language loaders. */
+export interface I18nHelper {
+    /** Registers a library-tier bundle; its namespace defaults to `lib`. */
+    addI18nLib: I18nLeveledResourceSignature;
+    /** Registers an app-tier bundle; its namespace defaults to the resource name. */
+    addI18nApp: I18nLeveledResourceSignature;
+    /**
+     * Drains the bundles of one (ns, resource, language) slot in merge order — library tier before app
+     * tier, then `priority` ascending. `null` once the slot was drained for the language.
+     */
+    initI18nResource: (lng: string, resource: string, ns?: string) => null | I18nResource[];
+    /**
+     * The merged bundle of one (ns, resource, language) slot, read WITHOUT draining it.
+     *
+     * Every registered bundle is deep-merged in the order `initI18nResource` hands them out — library
+     * tier before app tier, then `priority` ascending, a bundle with no priority last — so an app
+     * override wins exactly as it does in i18next. The slot is never marked drained and no empty slot
+     * is created, so a later `initI18nResource` still returns the same bundles. This is the read for
+     * code with no i18next instance (a server rendering an e-mail) and for a language other than the
+     * active one (a legal text shown in the billing country's language). `null` when nothing is
+     * registered for the slot.
+     */
+    resolveI18nResource: (lng: string, resource: string, ns?: string) => Record<string, unknown> | null;
+    /**
+     * Register a loader for a language's resources — typically a dynamic `import()` of a module that
+     * calls `addI18nLib` / `addI18nApp`. If the language was already requested (`loadI18nLanguage` was
+     * called for it), the loader starts at once: one registered late, by a module that only evaluates
+     * after the app started, is never silently skipped. Its failure then surfaces through the next
+     * `loadI18nLanguage` call, which retries it.
+     */
+    addI18nLoader: (lng: string, loader: I18nLoader) => void;
+    /**
+     * Await every loader registered for `lng` — including those registered while this call is in
+     * flight — then resolve. Concurrent and repeated calls share in-flight runs and never re-run a
+     * completed loader; a loader registered after an earlier call resolved is awaited by the next one.
+     * A language with no loaders resolves at once.
+     *
+     * Rejects with the first failure once every loader of the pass has settled; the failed loader
+     * alone is re-run by the next call.
+     */
+    loadI18nLanguage: (lng: string) => Promise<void>;
+    /** Whether every loader registered for `lng` has completed; true for a language with none. */
+    isI18nLanguageLoaded: (lng: string) => boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/helper/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/helper/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAEzF,0GAA0G;AAC1G,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,UAAU,EAAE,4BAA4B,CAAA;IACxC,iFAAiF;IACjF,UAAU,EAAE,4BAA4B,CAAA;IACxC;;;OAGG;IACH,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,YAAY,EAAE,CAAA;IACvF;;;;;;;;;;OAUG;IACH,mBAAmB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACnG;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAA;IACxD;;;;;;;;OAQG;IACH,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAChD,8FAA8F;IAC9F,oBAAoB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CAC/C"}

package/build/helper/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/helper/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/helper/types.ts"],"names":[],"mappings":""}

package/build/helper.d.ts

@@ -1,5 +1,19 @@
-import type { I18nLeveledResourceSignature, I18nResource } from './types.js';
+import type { I18nLeveledResourceSignature, I18nLoader, I18nResource } from './types.js';
+import type { I18nHelper } from './helper/types.js';
+export declare const createI18nHelper: () => I18nHelper;
+export declare const i18nHelper: I18nHelper;
+/** @deprecated compat:factory-refactor — use `i18nHelper.addI18nLib(…)` */
 export declare const addI18nLib: I18nLeveledResourceSignature;
+/** @deprecated compat:factory-refactor — use `i18nHelper.addI18nApp(…)` */
 export declare const addI18nApp: I18nLeveledResourceSignature;
+/** @deprecated compat:factory-refactor — use `i18nHelper.initI18nResource(…)` */
 export declare const initI18nResource: (lng: string, resource: string, ns?: string) => null | I18nResource[];
+/** @deprecated compat:factory-refactor — use `i18nHelper.resolveI18nResource(…)` */
+export declare const resolveI18nResource: (lng: string, resource: string, ns?: string) => Record<string, unknown> | null;
+/** @deprecated compat:factory-refactor — use `i18nHelper.addI18nLoader(…)` */
+export declare const addI18nLoader: (lng: string, loader: I18nLoader) => void;
+/** @deprecated compat:factory-refactor — use `i18nHelper.loadI18nLanguage(…)` */
+export declare const loadI18nLanguage: (lng: string) => Promise<void>;
+/** @deprecated compat:factory-refactor — use `i18nHelper.isI18nLanguageLoaded(…)` */
+export declare const isI18nLanguageLoaded: (lng: string) => boolean;
 //# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,4BAA4B,EAAE,YAAY,EAA8C,MAAM,YAAY,CAAA;AA6BxH,eAAO,MAAM,UAAU,EAAE,4BAGxB,CAAA;AAED,eAAO,MAAM,UAAU,EAAE,4BAGxB,CAAA;AAED,eAAO,MAAM,gBAAgB,QAAS,MAAM,YAAY,MAAM,OAAO,MAAM,KAAG,IAAI,GAAG,YAAY,EAoBhG,CAAA"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,4BAA4B,EAAE,UAAU,EAAmB,YAAY,EACxE,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAInD,eAAO,MAAM,gBAAgB,QAAO,UA6InC,CAAA;AAED,eAAO,MAAM,UAAU,YAAqB,CAAA;AAE5C,2EAA2E;AAC3E,eAAO,MAAM,UAAU,EAAE,4BAA8G,CAAA;AAEvI,2EAA2E;AAC3E,eAAO,MAAM,UAAU,EAAE,4BAA8G,CAAA;AAEvI,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,QAAS,MAAM,YAAY,MAAM,OAAO,MAAM,KAAG,IAAI,GAAG,YAAY,EAAoD,CAAA;AAErJ,oFAAoF;AACpF,eAAO,MAAM,mBAAmB,QAAS,MAAM,YAAY,MAAM,OAAO,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAyD,CAAA;AAEpK,8EAA8E;AAC9E,eAAO,MAAM,aAAa,QAAS,MAAM,UAAU,UAAU,KAAG,IAA6C,CAAA;AAE7G,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,QAAS,MAAM,KAAG,OAAO,CAAC,IAAI,CAAqC,CAAA;AAEhG,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,QAAS,MAAM,KAAG,OAA+C,CAAA"}

package/build/helper.js

@@ -1,42 +1,39 @@
 import { DEFAULT_NAMESPACE, I18nTier, LIB_NAMESPACE, MAX_PRIORITY } from './consts.js';
-import { tierCost } from './utils/consts.js';
-import { ensureStructure } from './utils/storage.js';
-const prepareOptions = (opts, ns) => {
-    if (typeof opts === 'string') {
-        opts = { ns: opts };
-    }
-    else if (typeof opts === 'undefined') {
-        opts = {};
-    }
-    if (opts.ns == null && ns != null) {
-        opts.ns = ns;
-    }
-    return opts;
-};
-const _addI18n = (tier, lng, resource, data, opts) => {
-    opts = prepareOptions(opts);
-    const storage = ensureStructure(lng, resource, opts.ns);
-    const ns = opts.ns ?? DEFAULT_NAMESPACE;
-    const entry = {
-        ns, lng, tier, resource, data, priority: opts.priority
-    };
-    storage.resources.push(entry);
-};
-export const addI18nLib = (lng, resource, data, opts) => {
-    opts = prepareOptions(opts, LIB_NAMESPACE);
-    _addI18n(I18nTier.Library, lng, resource, data, opts);
-};
-export const addI18nApp = (lng, resource, data, opts) => {
-    opts = prepareOptions(opts, resource);
-    _addI18n(I18nTier.App, lng, resource, data, opts);
-};
-export const initI18nResource = (lng, resource, ns) => {
-    ns = ns ?? DEFAULT_NAMESPACE;
-    const translation = ensureStructure(lng, resource, ns);
-    if (translation.lngInitialized.includes(lng)) {
-        return null;
-    }
-    const result = [...translation.resources].sort((a, b) => {
+import { tierCost, _OwlMeansI18nLoaders, _OwlMeansI18nStorage } from './utils/consts.js';
+import { i18nStorageUtils } from './utils/storage.js';
+export const createI18nHelper = () => {
+    const { ensureLoaders, ensureStructure } = i18nStorageUtils;
+    const prepareOptions = (opts, ns) => {
+        if (typeof opts === 'string') {
+            opts = { ns: opts };
+        }
+        else if (typeof opts === 'undefined') {
+            opts = {};
+        }
+        if (opts.ns == null && ns != null) {
+            opts.ns = ns;
+        }
+        return opts;
+    };
+    const _addI18n = (tier, lng, resource, data, opts) => {
+        opts = prepareOptions(opts);
+        const storage = ensureStructure(lng, resource, opts.ns);
+        const ns = opts.ns ?? DEFAULT_NAMESPACE;
+        const entry = {
+            ns, lng, tier, resource, data, priority: opts.priority
+        };
+        storage.resources.push(entry);
+    };
+    const addI18nLib = (lng, resource, data, opts) => {
+        opts = prepareOptions(opts, LIB_NAMESPACE);
+        _addI18n(I18nTier.Library, lng, resource, data, opts);
+    };
+    const addI18nApp = (lng, resource, data, opts) => {
+        opts = prepareOptions(opts, resource);
+        _addI18n(I18nTier.App, lng, resource, data, opts);
+    };
+    /** Library tier before app tier, then `priority` ascending — the order bundles are merged in. */
+    const ordered = (resources) => [...resources].sort((a, b) => {
         const aTier = tierCost[a.tier];
         const bTier = tierCost[b.tier];
         if (aTier !== bTier) {
@@ -44,7 +41,87 @@ export const initI18nResource = (lng, resource, ns) => {
         }
         return (a.priority ?? MAX_PRIORITY) - (b.priority ?? MAX_PRIORITY);
     });
-    translation.lngInitialized.push(lng);
-    return result;
+    const initI18nResource = (lng, resource, ns) => {
+        ns = ns ?? DEFAULT_NAMESPACE;
+        const translation = ensureStructure(lng, resource, ns);
+        if (translation.lngInitialized.includes(lng)) {
+            return null;
+        }
+        const result = ordered(translation.resources);
+        translation.lngInitialized.push(lng);
+        return result;
+    };
+    const isPlainObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value);
+    /** Merge `source` over `target` in place; nested objects are copied, never shared with a bundle. */
+    const mergeInto = (target, source) => {
+        for (const [key, value] of Object.entries(source)) {
+            const current = target[key];
+            target[key] = isPlainObject(value)
+                ? mergeInto(isPlainObject(current) ? current : {}, value)
+                : Array.isArray(value) ? structuredClone(value) : value;
+        }
+        return target;
+    };
+    const resolveI18nResource = (lng, resource, ns = DEFAULT_NAMESPACE) => {
+        const translation = _OwlMeansI18nStorage.data[ns]?.[resource]?.[lng];
+        if (translation == null || translation.resources.length === 0) {
+            return null;
+        }
+        return ordered(translation.resources).reduce((merged, bundle) => mergeInto(merged, bundle.data), {});
+    };
+    /**
+     * Start `entry`'s loader, or join the run already in flight. A completed entry never runs again;
+     * a failed run clears `running`, so the next caller starts it afresh.
+     */
+    const runLoader = (entry) => {
+        if (entry.done) {
+            return Promise.resolve();
+        }
+        return entry.running ??= Promise.resolve().then(() => entry.loader()).then(() => { entry.done = true; }, (error) => {
+            entry.running = undefined;
+            throw error;
+        });
+    };
+    const addI18nLoader = (lng, loader) => {
+        const bucket = ensureLoaders(lng);
+        const entry = { loader, done: false };
+        bucket.entries.push(entry);
+        if (bucket.requested) {
+            runLoader(entry).catch(() => { });
+        }
+    };
+    const loadI18nLanguage = async (lng) => {
+        const bucket = ensureLoaders(lng);
+        bucket.requested = true;
+        // Each pass settles what was pending when it began; a loader added meanwhile is left for the
+        // next pass, so the call resolves only once nothing is pending.
+        for (let pending = bucket.entries.filter(entry => !entry.done); pending.length > 0; pending = bucket.entries.filter(entry => !entry.done)) {
+            const results = await Promise.allSettled(pending.map(runLoader));
+            const failure = results.find(result => result.status === 'rejected');
+            if (failure != null) {
+                throw failure.reason;
+            }
+        }
+    };
+    const isI18nLanguageLoaded = (lng) => _OwlMeansI18nLoaders.data[lng]?.entries.every(entry => entry.done) ?? true;
+    return {
+        addI18nLib, addI18nApp, initI18nResource, resolveI18nResource,
+        addI18nLoader, loadI18nLanguage, isI18nLanguageLoaded
+    };
 };
+export const i18nHelper = createI18nHelper();
+/** @deprecated compat:factory-refactor — use `i18nHelper.addI18nLib(…)` */
+export const addI18nLib = (lng, resource, data, opts) => i18nHelper.addI18nLib(lng, resource, data, opts);
+/** @deprecated compat:factory-refactor — use `i18nHelper.addI18nApp(…)` */
+export const addI18nApp = (lng, resource, data, opts) => i18nHelper.addI18nApp(lng, resource, data, opts);
+/** @deprecated compat:factory-refactor — use `i18nHelper.initI18nResource(…)` */
+export const initI18nResource = (lng, resource, ns) => i18nHelper.initI18nResource(lng, resource, ns);
+/** @deprecated compat:factory-refactor — use `i18nHelper.resolveI18nResource(…)` */
+export const resolveI18nResource = (lng, resource, ns) => i18nHelper.resolveI18nResource(lng, resource, ns);
+/** @deprecated compat:factory-refactor — use `i18nHelper.addI18nLoader(…)` */
+export const addI18nLoader = (lng, loader) => i18nHelper.addI18nLoader(lng, loader);
+/** @deprecated compat:factory-refactor — use `i18nHelper.loadI18nLanguage(…)` */
+export const loadI18nLanguage = (lng) => i18nHelper.loadI18nLanguage(lng);
+/** @deprecated compat:factory-refactor — use `i18nHelper.isI18nLanguageLoaded(…)` */
+export const isI18nLanguageLoaded = (lng) => i18nHelper.isI18nLanguageLoaded(lng);
 //# sourceMappingURL=helper.js.map