@owlmeans/i18n 0.1.18-rc.4 → 0.1.18-rc.40

package/README.md

@@ -11,7 +11,7 @@ Multi-level translation resource registration for OwlMeans applications.
 ## Installation
 
 ```bash
-bun add @owlmeans/i18n
+bun add @owlmeans/i18n@^0.1.18-rc.40
 ```
 
 ## Usage
@@ -19,32 +19,42 @@ bun add @owlmeans/i18n
 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
+npx @owlmeans/agent-skills@^0.1.18-rc.57
 ```
 
 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.0",
-  "generatedAt": "2026-08-16T22:20:50.497Z",
+  "version": "0.1.18-rc.40",
+  "generatedAt": "2026-10-20T23:19:58.598Z",
   "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,33 +8,102 @@ user-invocable: false
 # @owlmeans/i18n
 
 **Layer:** Core (no runtime deps)
-**Install:** `"@owlmeans/i18n": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/i18n": "^0.1.18-rc.40"` 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) |
-| `SUPPORTED_LNGS` | `['en','pl','ru','be','uk','es','de']` — the canonical language set |
+| `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'` |
+| `DEFAULT_NAMESPACE` | `'translation'` — i18next's own default namespace, used whenever a lookup names none and `I18nConfig.defaultNs` is unset |
 | `I18nTier` | `Library \| App` — enum used internally |
 | `I18nConfig` | `{ defaultLng?, defaultNs?, fallbackLng?, supportedLngs? }` |
+| `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`:
+`i18nHelper.addI18nLib('en', 'wallet', walletEn, 'did')`.
+
+## Subpath Exports
+
+- `./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; `_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 `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 { i18nHelper, LIB_NAMESPACE } from '@owlmeans/i18n'
+
+i18nHelper.addI18nApp('en', 'errors', myErrors, { ns: LIB_NAMESPACE })
+```
 
-App-tier strings deep-merge **over** Library-tier strings for the same keys at resolution time — this is the override mechanism.
+Without `{ ns: LIB_NAMESPACE }` the app bundle lands in namespace `errors` while the library's sits
+in `lib`. Nothing errors, nothing merges, and the library strings keep rendering.
+
+Within one tier the order is `priority`, ascending, and every bundle is merged over the one before
+it — so the **last** applied wins. A registration that states no `priority` sorts last and
+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 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
 
@@ -42,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' }
@@ -50,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`:
@@ -84,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,18 +21,18 @@ 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'`.
 
 ## Compound prefix keys
 
-A key like `t('title')` resolves to `namespace : resource.prefix.key`. The prefix is composed by joining segments with `.` via `composePrefix` (never by hand-concatenating strings).
+A key like `t('title')` resolves to `namespace : resource.prefix.key`. The prefix is composed by joining segments with `.` via `composePrefix` — exported from `@owlmeans/client-i18n` (and re-exported by `@owlmeans/web-panel` and `@owlmeans/mui-panel`), never by hand-concatenating strings.
 
 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')
@@ -44,31 +44,59 @@ t('title')
 
 ## Context-based prefix switching
 
-Use `PanelContext` (from `@owlmeans/client-panel`) to inject `resource`, `ns`, or `prefix` into a React sub-tree. Child components that call `usePanelI18n()` or `useFormI18n()` automatically pick up the context value.
+Use `PanelContext` (from `@owlmeans/client-panel`) to inject `resource`, `ns` or `prefix` into a
+React sub-tree. Child components that call `usePanelI18n()` pick those three up, and a nested
+`PanelContext` inherits the outer one field by field.
 
 ```tsx
-// Override the active namespace/resource for a sub-tree
-<PanelContext resource="wl-manager" ns="lib" prefix="wl-dns">
-  <DnsForm />  {/* DnsForm calls usePanelI18n() — gets ns='lib', resource='wl-manager', prefix='wl-dns' */}
+// Read a library's own bundle from inside an app sub-tree
+<PanelContext resource="payment" ns="lib" prefix="plan">
+  <Text name="label.monthly" />  {/* usePanelI18n() → lib:payment.plan.label.monthly */}
 </PanelContext>
 ```
 
-Use `i18n` props on individual components to override just one level:
+`suppress` is **not** one of them. `TPanelContext` accepts it because it spreads `I18nBaseProps`,
+but `usePanelI18n` reads only `prefix`, `resource` and `ns`, so a `<PanelContext suppress>` changes
+nothing for any child. Suppression is per component, from that component's own `i18n` prop — which
+is what `Button` and `ActionCtrl` check before translating a label.
+
+**Form fields sit in a different context.** `useFormI18n` reads the form context that `FormContext`
+publishes from the enclosing `Form`'s own `i18n` and `name` props; it never touches `PanelContext`.
+So wrapping a form or a field in `<PanelContext …>` changes nothing for any field — redirect a
+field by naming the enclosing `Form` or by giving that `Form` an `i18n` prop.
+
+Use the `i18n` prop on an individual component to override just one level. It is declared by the
+components whose props extend `I18nProps` — `Block`, `Text`, `Link`, `Status`, `Button` and `Form`
+in both panel families:
 ```tsx
-<StatusLabel i18n={{ prefix: 'my-status' }} />
+<Status i18n={{ prefix: 'my-status' }} />
 ```
 
+Not every component carrying copy has it, and the two that lack it read different contexts.
+`TextInput` — props extend `FormFieldProps` (`name`, `def`) and add `label`, `placeholder`, `hint`,
+`type` and `disableAutocomplete` — resolves `<name>.label`, `<name>.placeholder` and `<name>.hint`
+through `useFormI18n` when the matching prop is `true`, and renders the prop's own string when it
+is given one; redirect it through the enclosing `Form`. `ButtonSelector` — `SelectorProps` is `name`,
+`current`, `options` and `onSelect` — renders one `Button` per option labelled `<name>.<option>`,
+and `Button` resolves through `usePanelI18n` with the app `buttons` and `lib:client-panel.buttons`
+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)`:
+App-tier registrations deep-merge over Library-tier for the same `(ns, resource)` — and the
+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 } from '@owlmeans/i18n'
+import '@owlmeans/error'                              // Library tier: lib:errors.*
+import { i18nHelper, LIB_NAMESPACE } from '@owlmeans/i18n'
 import myErrors from './i18n/en.json'
 
-addI18nApp('en', 'errors', myErrors)        // 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')`
+reads `lib`. Nothing errors and the library strings keep rendering.
+
 ## Per-package checklist
 
 When adding translatable strings to any package:
@@ -78,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"}