@owlmeans/client-i18n 0.1.18-rc.4 → 0.1.18-rc.41

package/README.md

@@ -12,7 +12,7 @@ React i18next adapter that loads translations registered via `@owlmeans/i18n` in
 ## Installation
 
 ```bash
-bun add @owlmeans/client-i18n
+bun add @owlmeans/client-i18n@^0.1.18-rc.41
 ```
 
 ## Usage
@@ -68,7 +68,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.39
 ```
 
 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,
   "package": "@owlmeans/client-i18n",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.509Z",
+  "version": "0.1.18-rc.41",
+  "generatedAt": "2026-09-25T15:32:39.584Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 name: client-i18n
-description: How to use @owlmeans/client-i18n — React i18n context built on i18next. Auto-invoked when setting up translation in a React app, using translation hooks, or working with language switching.
+description: How to use @owlmeans/client-i18n — React i18n context built on i18next. Auto-invoked when setting up translation in a React app, using translation hooks, working with language switching, or awaiting deferred language packs with prepareI18n.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,11 +8,11 @@ user-invocable: false
 # @owlmeans/client-i18n
 
 **Layer:** Client (React)
-**Install:** `"@owlmeans/client-i18n": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/client-i18n": "^0.1.18-rc.41"` in `dependencies`
 
 ## Purpose
 
-Wraps i18next + react-i18next, lazily loads registered bundles from `@owlmeans/i18n` storage into the i18next instance, and provides hooks for translating strings.
+Wraps i18next + react-i18next, lazily loads registered bundles from `@owlmeans/i18n` storage into the i18next instance, awaits deferred language packs (`prepareI18n`, `setLanguage`), and provides hooks for translating strings.
 
 ## Key Exports
 
@@ -22,10 +22,44 @@ Wraps i18next + react-i18next, lazily loads registered bundles from `@owlmeans/i
 | `useI18nLib(resource, prefix?)` | Hook for library strings (ns=`'lib'`) |
 | `useI18nApp(resource?, prefix?)` | Hook for app strings (ns=resource name; defaults to `context.cfg.service`) |
 | `useI18n(resource, ns?, prefix?)` | Low-level hook with explicit ns — use when ns ≠ resource |
-| `useLanguage()` | `[currentLng, setLng]` — read and switch the active language |
+| `useLanguage()` | `[currentLng, setLng]` — the i18next instance's language, and an async switch — see Language persistence |
+| `prepareI18n`, `resolveInitialLanguage`, `setLanguage` | Re-exported from `./utils` — see below |
 | `composePrefix(parent?, child?)` | Canonical dot-join for prefix chaining; never call manually in panel code — used internally |
 | `I18nBaseProps` | `{ resource?, ns?, prefix?, suppress? }` |
 | `I18nProps` | `{ i18n?: I18nBaseProps }` |
+| `I18nContextProps` | `{ config: ClientConfig }` — what the provider takes |
+
+## Subpath: `./utils`
+
+The instance itself, for a host that has to configure i18next before the tree renders.
+
+| Export | Description |
+|---|---|
+| `useI18nInstance(config)` | The i18next instance for this application, memoised for the mount |
+| `getI18nInstance(config)` | The same instance outside React |
+| `setLanguage(lng)` | Async: load `lng`'s pack (`loadI18nLanguage`), then persist (if the persistence guard allows) and switch — what `useLanguage`'s setter calls |
+| `setLanguagePersistence(guard \| null)` | Install the guard that decides whether an explicit choice may be written to storage; `null` removes it. Call BEFORE `prepareI18n` |
+| `persistLanguage()` | Write the explicit choice storage refused earlier, now that the guard allows; `false` when nothing waits or storage is still refused |
+| `getExplicitLanguage()` | The language a person chose explicitly since this page loaded (stored or not), else `null` — what a host asks before applying a language that arrived some other way |
+| `prepareI18n(config)` | Await the fallback language's loaders, then the initial language's; resolves to the language the instance will start in. Call once, before the first render |
+| `resolveInitialLanguage(config)` | The persisted `owlmeans-lng` when it is in `supportedLngs`, else the browser's language (`preferredLanguageOf`), else `fallbackLng ?? defaultLng ?? DEFAULT_LNG` |
+| `preferredLanguageOf(supportedLngs, preferred)` | Pure: the first preferred tag the config supports, exact or by base (`de-DE` → `de`), else `null` |
+
+All of these live in `src/utils/instance.ts`; the package root re-exports `prepareI18n`,
+`resolveInitialLanguage`, `setLanguage` and the three persistence functions above.
+
+**There is exactly one instance per document**, created on first request and reused by every later
+call whatever config is passed. So configuration is read once, at the first creation, and a plugin
+is installed on the instance rather than passed to a second factory.
+
+**The instance is initialized at creation with an explicit `lng`**, which is why the language is
+resolved there and not by a plugin — by `resolveInitialLanguage` (or `prepareI18n`, which runs it):
+the persisted choice (`owlmeans-lng`, when supported), else the browser's own language
+(`navigator.languages` through `preferredLanguageOf` — a first visit from a German browser opens in
+German), else `fallbackLng`. A language detector installed afterwards (`instance.use(detector)`,
+which `@owlmeans/web-panel`'s `render` still does) is never consulted — harmless, but not what
+detects. A detected language is not persisted, not even by the start-up switch that follows a
+deferred pack's load; only an explicit choice (`setLanguage`) is.
 
 ## Setup (app root)
 
@@ -43,9 +77,55 @@ function App() {
 
 `clientConfig.i18n` is optional; it defaults to `SUPPORTED_LNGS` and `'en'` fallback.
 
+**An app that defers language packs** (`addI18nLoader`, the `i18n` skill) calls
+`await prepareI18n(config)` BEFORE its first render — never after:
+
+```ts
+import { prepareI18n } from '@owlmeans/client-i18n'
+
+await prepareI18n(context.cfg)   // fallback pack first, then the persisted / browser / fallback one
+render(context)
+```
+
+This composes with an async boot because `@owlmeans/web-client`'s `render` (and so `renderApp` and
+`@owlmeans/web-panel`'s `render`) checks `document.readyState` instead of waiting for a
+`DOMContentLoaded` that already fired. `prepareI18n` rejects only when the FALLBACK pack fails; when
+the initial language's pack fails it logs, resolves to the fallback and leaves the persisted choice
+alone, so the next visit retries it rather than stranding the user. Without `prepareI18n`, the
+instance starts in the fallback whenever the wanted language is not loaded yet and switches once its
+loaders finish (a brief fallback flash) — but nothing awaits a deferred FALLBACK pack, whose slots
+are then drained empty for the session.
+
 ## Language persistence
 
-The active language is persisted in `localStorage` under `owlmeans-lng` and restored on init.
+The active language is persisted in `localStorage` under `owlmeans-lng` and restored on init — but
+only when it is in `supportedLngs`, so a stored value that a later release dropped falls back to
+the browser's language, then `fallbackLng`, instead of resolving nothing. Every storage and
+`navigator` access is guarded, so a browser that refuses site data (or no browser) still renders.
+
+`tests/instance.spec.ts` pins `preferredLanguageOf` (base matching, browser order, exact tag first,
+`null` when nothing matches) and the persistence guard.
+
+**Persistence is guarded, not assumed.** With no guard installed every explicit choice is written, as
+always. An application that asks its visitors before remembering anything installs one
+(`setLanguagePersistence(() => allowed)`; `@owlmeans/web-panel/consent`'s `installConsentLanguage()` is
+the ready-made one for the cookie dialog's `functional` category — see the `consent` skill). While it
+says no: `setLanguage` still switches the UI but writes nothing and remembers the refused choice
+(`persistLanguage()` writes it when storage becomes allowed), and a value already in storage counts
+as ABSENT at start-up (`resolveInitialLanguage`), so a language nobody was allowed to remember is not
+used. Installing a guard also resets what this page has chosen so far — install it before anything
+calls `setLanguage`.
+
+`setLanguage(lng)` is async: it awaits `loadI18nLanguage(lng)`, then persists and calls i18next's
+`changeLanguage` — before the instance exists it records the language the instance will start in
+instead. The LAST call wins: an earlier call whose load finishes later does nothing. A failed load
+rejects, and nothing is persisted or switched.
+
+`useLanguage()` returns `i18n.language` from `useTranslation()`, not local state, so every caller
+re-renders on i18next's `languageChanged` and shows the same language whoever switched it. Its
+setter returns a promise that never rejects (a failure is logged): the value changes only once the
+pack has loaded and i18next switched, so a controlled `<select value={lng}>` stays on the current
+language meanwhile, and stays there when the load fails.
 
 ```tsx
 function LangSwitch() {
@@ -96,16 +176,24 @@ t('title')  // → did:wallet.createKey.title
 
 ## App-level override of library strings
 
-Import the library's i18n registration **and** register your own version at App tier:
+Import the library's i18n registration **and** register your own version at App tier **in the
+library's namespace**:
 ```typescript
-import '@owlmeans/error/i18n'          // library en strings
-import { addI18nApp } from '@owlmeans/i18n'
-import myErrors from './i18n/en.json'  // with { type: 'json' }
+import '@owlmeans/error'               // the library bundle, registered by side effect
+import { addI18nApp, LIB_NAMESPACE } from '@owlmeans/i18n'
+import myErrors from './i18n/en.json' with { type: 'json' }
 
-// App tier wins — these override the library's 'errors' strings
-addI18nApp('en', 'errors', myErrors)
+// App tier merges last within (ns, resource, lng) — these override the library's 'errors' strings
+addI18nApp('en', 'errors', myErrors, { ns: LIB_NAMESPACE })
 ```
 
+`{ ns: LIB_NAMESPACE }` is what makes it an override. `addI18nApp` defaults the namespace to the
+**resource** name, so without it the bundle lands in namespace `errors` while `useI18nLib('errors')`
+reads namespace `lib` — nothing errors, nothing merges, and the library strings keep rendering.
+
+A package registers its strings from its own root: `src/i18n.ts` is re-exported by `src/index.ts`,
+so importing the package is what loads them. No package publishes an `./i18n` subpath.
+
 ## Resource JSON format
 
 The shared instance runs i18next's **v4** JSON format — `compatibilityJSON` is not set and must
@@ -120,5 +208,6 @@ misbehaves at runtime.
 
 ## Depends On
 
-`@owlmeans/i18n`, `@owlmeans/client-context`, `i18next` (>= 26.2), `react-i18next` (>= 17),
-`react` (peer)
+`@owlmeans/i18n`, `@owlmeans/client`, `@owlmeans/client-context`, `i18next` (>= 26.2),
+`react-i18next` (>= 17), `react` (the one peer). `@owlmeans/client` is what `useI18nApp` reads the
+current context from, to default the resource to `context.cfg.service`.

package/build/context.d.ts

@@ -9,5 +9,11 @@ export declare const composePrefix: (parent?: string, child?: string) => string;
 export declare const useI18n: (resource: string, ns?: string, prefix?: string) => TFunction;
 export declare const useI18nLib: (libName: string, prefix?: string) => TFunction;
 export declare const useI18nApp: (appName?: string, prefix?: string) => TFunction;
-export declare const useLanguage: () => [string, (lng: string) => void];
+/**
+ * `[currentLng, setLng]`. The current language is read from the i18next instance itself, whose
+ * `languageChanged` event re-renders every subscriber, so all callers agree whoever switched it.
+ * The setter loads the language's pack first; a failed switch is logged and leaves the language
+ * unchanged.
+ */
+export declare const useLanguage: () => [string, (lng: string) => Promise<void>];
 //# sourceMappingURL=context.d.ts.map

package/build/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAA;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAKxC,eAAO,MAAM,WAAW,EAAE,EAAE,CAAC,gBAAgB,CAI3C,CAAA;AAEF,kGAAkG;AAClG,eAAO,MAAM,aAAa,YAAa,MAAM,UAAU,MAAM,KAAG,MAK/D,CAAA;AAyCD;4FAC4F;AAC5F,eAAO,MAAM,OAAO,aAAc,MAAM,OAAO,MAAM,WAAW,MAAM,KAAG,SAExE,CAAA;AAED,eAAO,MAAM,UAAU,YAAa,MAAM,WAAW,MAAM,KAAG,SAE7D,CAAA;AAED,eAAO,MAAM,UAAU,aAAc,MAAM,WAAW,MAAM,KAAG,SAK9D,CAAA;AAED,eAAO,MAAM,WAAW,QAAO,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAU5D,CAAA"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,OAAO,CAAA;AAC/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAKxC,eAAO,MAAM,WAAW,EAAE,EAAE,CAAC,gBAAgB,CAI3C,CAAA;AAEF,kGAAkG;AAClG,eAAO,MAAM,aAAa,YAAa,MAAM,UAAU,MAAM,KAAG,MAK/D,CAAA;AAyCD;4FAC4F;AAC5F,eAAO,MAAM,OAAO,aAAc,MAAM,OAAO,MAAM,WAAW,MAAM,KAAG,SAExE,CAAA;AAED,eAAO,MAAM,UAAU,YAAa,MAAM,WAAW,MAAM,KAAG,SAE7D,CAAA;AAED,eAAO,MAAM,UAAU,aAAc,MAAM,WAAW,MAAM,KAAG,SAK9D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAO,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAYrE,CAAA"}

package/build/context.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { memo, useCallback, useState } from 'react';
+import { memo, useCallback } from 'react';
 import { I18nextProvider, useTranslation } from 'react-i18next';
 import { setLanguage, useI18nInstance } from './utils/instance.js';
 import { DEFAULT_LNG, DEFAULT_NAMESPACE, initI18nResource, LIB_NAMESPACE } from '@owlmeans/i18n';
@@ -57,13 +57,22 @@ export const useI18nApp = (appName, prefix) => {
     const resolvedName = appName ?? context.cfg.service;
     return useI18nResource(resolvedName, resolvedName, prefix);
 };
+/**
+ * `[currentLng, setLng]`. The current language is read from the i18next instance itself, whose
+ * `languageChanged` event re-renders every subscriber, so all callers agree whoever switched it.
+ * The setter loads the language's pack first; a failed switch is logged and leaves the language
+ * unchanged.
+ */
 export const useLanguage = () => {
     const { i18n } = useTranslation();
-    const [lng, setLng] = useState(i18n.language);
-    const changeLng = useCallback((next) => {
-        setLanguage(next);
-        setLng(next);
+    const changeLng = useCallback(async (next) => {
+        try {
+            await setLanguage(next);
+        }
+        catch (error) {
+            console.error('[i18n] language switch failed', error);
+        }
     }, []);
-    return [lng, changeLng];
+    return [i18n.language, changeLng];
 };
 //# sourceMappingURL=context.js.map

package/build/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types.js';
 export { I18nContext, composePrefix, useI18n, useI18nLib, useI18nApp, useLanguage } from './context.js';
+export { prepareI18n, resolveInitialLanguage, setLanguage, setLanguagePersistence, persistLanguage, getExplicitLanguage, } from './utils/instance.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AACvG,OAAO,EACL,WAAW,EAAE,sBAAsB,EAAE,WAAW,EAAE,sBAAsB,EAAE,eAAe,EAAE,mBAAmB,GAC/G,MAAM,qBAAqB,CAAA"}

package/build/index.js

@@ -1,3 +1,4 @@
 export * from './types.js';
 export { I18nContext, composePrefix, useI18n, useI18nLib, useI18nApp, useLanguage } from './context.js';
+export { prepareI18n, resolveInitialLanguage, setLanguage, setLanguagePersistence, persistLanguage, getExplicitLanguage, } from './utils/instance.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AACvG,OAAO,EACL,WAAW,EAAE,sBAAsB,EAAE,WAAW,EAAE,sBAAsB,EAAE,eAAe,EAAE,mBAAmB,GAC/G,MAAM,qBAAqB,CAAA"}

package/build/utils/instance.d.ts

@@ -1,6 +1,51 @@
 import type { i18n } from 'i18next';
 import type { ClientConfig } from '@owlmeans/client-context';
+/**
+ * The language a person chose explicitly since this page loaded (`setLanguage`), or `null`. What a
+ * host asks before it applies a language that arrived some other way — a link — which must never
+ * override what the person just picked.
+ */
+export declare const getExplicitLanguage: () => string | null;
+/**
+ * Install (or, with `null`, remove) the guard that decides whether a language choice may be
+ * remembered. Call it BEFORE `prepareI18n`: the initial language is resolved from storage, and a
+ * guard that says no makes a stored value count as absent.
+ */
+export declare const setLanguagePersistence: (guard: (() => boolean) | null) => void;
+/**
+ * Write the explicit choice storage refused earlier, now that it may be — call it when the guard's
+ * answer turns to yes (the visitor granted functional storage). `false` when there was nothing
+ * waiting, storage is still refused, or the write failed.
+ */
+export declare const persistLanguage: () => boolean;
 export declare const useI18nInstance: (config: ClientConfig) => i18n;
 export declare const getI18nInstance: (config: ClientConfig) => i18n;
-export declare const setLanguage: (lng: string) => void;
+/**
+ * Load `lng`'s registered loaders, then persist it and switch the instance to it. Race-safe:
+ * when several calls overlap, the latest one wins whatever order their loads finish in.
+ * Rejects when the language's pack fails to load; nothing is persisted or switched then.
+ */
+export declare const setLanguage: (lng: string) => Promise<void>;
+/**
+ * Await the app's fallback language and its initial one (`resolveInitialLanguage`) before the app
+ * renders, so the first paint is already in the right language instead of flashing the
+ * fallback and then switching. Call it BEFORE `render(...)`. Resolves to the language the
+ * instance will start in: the fallback when the initial language's pack fails to load — the
+ * persisted choice is kept then, so the next visit retries it. Rejects only when the fallback
+ * language's own pack fails.
+ */
+export declare const prepareI18n: (config: ClientConfig) => Promise<string>;
+/**
+ * The language the app starts in: the one persisted under `owlmeans-lng` when it is still in
+ * `supportedLngs` (a person's explicit choice); else, on a first visit, the browser's own language
+ * (`navigator.languages` through `preferredLanguageOf` — a German browser opens in German); else
+ * `fallbackLng ?? defaultLng ?? DEFAULT_LNG`. The instance is initialized with this explicit `lng`,
+ * so a detector plugin installed afterwards (`instance.use(detector)`) is never consulted.
+ */
+export declare const resolveInitialLanguage: (config: ClientConfig) => string;
+/**
+ * The first of the browser's preferred languages the application supports — exact (`pt-BR`) or by
+ * its base (`de-DE` → `de`) — or `null` when none is. Pure, so a host (or a test) can pass the list.
+ */
+export declare const preferredLanguageOf: (supportedLngs: readonly string[], preferred: readonly (string | null | undefined)[]) => string | null;
 //# sourceMappingURL=instance.d.ts.map

package/build/utils/instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../src/utils/instance.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAEnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAO5D,eAAO,MAAM,eAAe,WAAY,YAAY,KAAG,IAItD,CAAA;AAED,eAAO,MAAM,eAAe,WAAY,YAAY,KAAG,IAC3B,CAAA;AAE5B,eAAO,MAAM,WAAW,QAAS,MAAM,KAAG,IAMzC,CAAA"}
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../src/utils/instance.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAEnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AA4B5D;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAAO,MAAM,GAAG,IAAsB,CAAA;AAItE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,UAAW,CAAC,MAAM,OAAO,CAAC,GAAG,IAAI,KAAG,IAKtE,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAO,OAYlC,CAAA;AAED,eAAO,MAAM,eAAe,WAAY,YAAY,KAAG,IAItD,CAAA;AAED,eAAO,MAAM,eAAe,WAAY,YAAY,KAAG,IAC3B,CAAA;AAE5B;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAAS,MAAM,KAAG,OAAO,CAAC,IAAI,CAA8B,CAAA;AA+BpF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,WAAkB,YAAY,KAAG,OAAO,CAAC,MAAM,CAatE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,WAAY,YAAY,KAAG,MAO7D,CAAA;AAgBD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,kBACf,SAAS,MAAM,EAAE,aAAa,SAAS,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,KAClF,MAAM,GAAG,IAUX,CAAA"}

package/build/utils/instance.js

@@ -1,24 +1,143 @@
 import { createInstance } from 'i18next';
 import { initReactI18next } from 'react-i18next';
 import { useMemo } from 'react';
-import { DEFAULT_LNG, DEFAULT_NAMESPACE, SUPPORTED_LNGS } from '@owlmeans/i18n';
+import { DEFAULT_LNG, DEFAULT_NAMESPACE, SUPPORTED_LNGS, isI18nLanguageLoaded, loadI18nLanguage } from '@owlmeans/i18n';
 const LNG_STORAGE_KEY = 'owlmeans-lng';
 let i18nInstance = null;
+/** The language `prepareI18n` loaded; the instance starts in it when created afterwards. */
+let preparedLng;
+/** The language of the latest `setLanguage` call — an earlier call that finishes later yields to it. */
+let requestedLng;
+/**
+ * Whether an explicit language choice may be written to storage right now. Unset, storage is always
+ * allowed — an application with no notion of consent behaves exactly as before. A host that asks its
+ * visitors (`@owlmeans/web-panel/consent`'s `installConsentLanguage`) installs one that answers
+ * "has the visitor allowed functional storage?", so a language is not remembered on a device nobody
+ * asked about.
+ */
+let persistenceGuard = null;
+/** The latest explicit choice that storage refused; written the moment storage is allowed. */
+let refusedChoice = null;
+/** The latest language a person chose explicitly in this page's life, stored or not. */
+let explicitChoice = null;
+/**
+ * The language a person chose explicitly since this page loaded (`setLanguage`), or `null`. What a
+ * host asks before it applies a language that arrived some other way — a link — which must never
+ * override what the person just picked.
+ */
+export const getExplicitLanguage = () => explicitChoice;
+const persistenceAllowed = () => persistenceGuard == null || persistenceGuard();
+/**
+ * Install (or, with `null`, remove) the guard that decides whether a language choice may be
+ * remembered. Call it BEFORE `prepareI18n`: the initial language is resolved from storage, and a
+ * guard that says no makes a stored value count as absent.
+ */
+export const setLanguagePersistence = (guard) => {
+    persistenceGuard = guard;
+    // A new guard starts a new account of what this page's visitor has chosen and what storage refused.
+    refusedChoice = null;
+    explicitChoice = null;
+};
+/**
+ * Write the explicit choice storage refused earlier, now that it may be — call it when the guard's
+ * answer turns to yes (the visitor granted functional storage). `false` when there was nothing
+ * waiting, storage is still refused, or the write failed.
+ */
+export const persistLanguage = () => {
+    if (refusedChoice == null || !persistenceAllowed()) {
+        return false;
+    }
+    try {
+        localStorage.setItem(LNG_STORAGE_KEY, refusedChoice);
+        refusedChoice = null;
+        return true;
+    }
+    catch (_) {
+        return false;
+    }
+};
 export const useI18nInstance = (config) => {
     const instance = useMemo(() => createI18nInstance(config), []);
     return instance;
 };
 export const getI18nInstance = (config) => createI18nInstance(config);
-export const setLanguage = (lng) => {
-    if (i18nInstance == null)
+/**
+ * Load `lng`'s registered loaders, then persist it and switch the instance to it. Race-safe:
+ * when several calls overlap, the latest one wins whatever order their loads finish in.
+ * Rejects when the language's pack fails to load; nothing is persisted or switched then.
+ */
+export const setLanguage = (lng) => switchLanguage(lng, true);
+/**
+ * `setLanguage`'s body. `persist` is false only for the start-up switch to a language nobody chose
+ * (a browser-detected one): only an explicit choice is ever written to `owlmeans-lng`.
+ */
+const switchLanguage = async (lng, persist) => {
+    requestedLng = lng;
+    await loadI18nLanguage(lng);
+    if (requestedLng !== lng) {
         return;
+    }
+    if (persist) {
+        explicitChoice = lng;
+        if (persistenceAllowed()) {
+            refusedChoice = null;
+            try {
+                localStorage.setItem(LNG_STORAGE_KEY, lng);
+            }
+            catch (_) { /* noop in non-browser environments */ }
+        }
+        else {
+            // Not remembered — but not forgotten either: the visitor may allow it a moment later.
+            refusedChoice = lng;
+        }
+    }
+    if (i18nInstance == null) {
+        preparedLng = lng;
+        return;
+    }
+    await i18nInstance.changeLanguage(lng);
+};
+/**
+ * Await the app's fallback language and its initial one (`resolveInitialLanguage`) before the app
+ * renders, so the first paint is already in the right language instead of flashing the
+ * fallback and then switching. Call it BEFORE `render(...)`. Resolves to the language the
+ * instance will start in: the fallback when the initial language's pack fails to load — the
+ * persisted choice is kept then, so the next visit retries it. Rejects only when the fallback
+ * language's own pack fails.
+ */
+export const prepareI18n = async (config) => {
+    const fallback = resolveFallbackLanguage(config);
+    await loadI18nLanguage(fallback);
+    const lng = resolveInitialLanguage(config);
     try {
-        localStorage.setItem(LNG_STORAGE_KEY, lng);
+        await loadI18nLanguage(lng);
+        preparedLng = lng;
     }
-    catch (_) { /* noop in non-browser environments */ }
-    i18nInstance.changeLanguage(lng);
+    catch (error) {
+        console.error(`[i18n] failed to load pack for "${lng}"`, error);
+        preparedLng = fallback;
+    }
+    return preparedLng;
+};
+/**
+ * The language the app starts in: the one persisted under `owlmeans-lng` when it is still in
+ * `supportedLngs` (a person's explicit choice); else, on a first visit, the browser's own language
+ * (`navigator.languages` through `preferredLanguageOf` — a German browser opens in German); else
+ * `fallbackLng ?? defaultLng ?? DEFAULT_LNG`. The instance is initialized with this explicit `lng`,
+ * so a detector plugin installed afterwards (`instance.use(detector)`) is never consulted.
+ */
+export const resolveInitialLanguage = (config) => {
+    const supportedLngs = config.i18n?.supportedLngs ?? [...SUPPORTED_LNGS];
+    const persistedLng = getPersistedLanguage();
+    return persistedLng != null && supportedLngs.includes(persistedLng)
+        ? persistedLng
+        : preferredLanguageOf(supportedLngs, browserLanguages()) ?? resolveFallbackLanguage(config);
 };
+const resolveFallbackLanguage = (config) => config.i18n?.fallbackLng ?? config.i18n?.defaultLng ?? DEFAULT_LNG;
 const getPersistedLanguage = () => {
+    if (!persistenceAllowed()) {
+        return null;
+    }
     try {
         return localStorage.getItem(LNG_STORAGE_KEY);
     }
@@ -26,16 +145,46 @@ const getPersistedLanguage = () => {
         return null;
     }
 };
+/**
+ * The first of the browser's preferred languages the application supports — exact (`pt-BR`) or by
+ * its base (`de-DE` → `de`) — or `null` when none is. Pure, so a host (or a test) can pass the list.
+ */
+export const preferredLanguageOf = (supportedLngs, preferred) => {
+    const supported = new Map(supportedLngs.map(lng => [lng.toLowerCase(), lng]));
+    for (const candidate of preferred) {
+        const tag = candidate?.trim().toLowerCase() ?? '';
+        if (tag === '')
+            continue;
+        const match = supported.get(tag) ?? supported.get(tag.split(/[-_]/)[0]);
+        if (match != null)
+            return match;
+    }
+    return null;
+};
+/** The browser's preferred languages, in order; `[]` outside a browser. */
+const browserLanguages = () => {
+    try {
+        if (typeof navigator === 'undefined')
+            return [];
+        return navigator.languages != null && navigator.languages.length > 0
+            ? navigator.languages
+            : navigator.language != null ? [navigator.language] : [];
+    }
+    catch (_) {
+        return [];
+    }
+};
 const createI18nInstance = (config) => {
     if (i18nInstance != null) {
         return i18nInstance;
     }
-    const fallbackLng = config.i18n?.fallbackLng ?? config.i18n?.defaultLng ?? DEFAULT_LNG;
+    const fallbackLng = resolveFallbackLanguage(config);
     const supportedLngs = config.i18n?.supportedLngs ?? [...SUPPORTED_LNGS];
-    const persistedLng = getPersistedLanguage();
-    const lng = persistedLng != null && supportedLngs.includes(persistedLng)
-        ? persistedLng
-        : fallbackLng;
+    const wantedLng = preparedLng ?? resolveInitialLanguage(config);
+    // Safety net for a host that did not await `prepareI18n`: start in the fallback and switch once
+    // the wanted language's loaders finish — a brief fallback flash instead of a half-loaded language.
+    const loaded = isI18nLanguageLoaded(wantedLng);
+    const lng = loaded ? wantedLng : fallbackLng;
     const instance = createInstance({
         // No `compatibilityJSON` — i18next >= 26 accepts only the v4 JSON format
         // (Intl.PluralRules suffixes `_one`/`_other`, not the v3 `_plural`/`_0`/`_1`).
@@ -48,6 +197,13 @@ const createI18nInstance = (config) => {
         debug: config.debug?.all ?? config.debug?.i18n ?? false,
     });
     instance.use(initReactI18next).init();
-    return i18nInstance = instance;
+    i18nInstance = instance;
+    if (!loaded) {
+        // Not persisted: `wantedLng` may be a browser-detected language nobody chose.
+        switchLanguage(wantedLng, false).catch((error) => {
+            console.error(`[i18n] failed to load pack for "${wantedLng}"`, error);
+        });
+    }
+    return instance;
 };
 //# sourceMappingURL=instance.js.map

package/build/utils/instance.js.map

@@ -1 +1 @@
-{"version":3,"file":"instance.js","sourceRoot":"","sources":["../../src/utils/instance.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAE/B,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/E,MAAM,eAAe,GAAG,cAAc,CAAA;AAEtC,IAAI,YAAY,GAAgB,IAAI,CAAA;AAEpC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAoB,EAAQ,EAAE;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAA;IAE9D,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAoB,EAAQ,EAAE,CAC5D,kBAAkB,CAAC,MAAM,CAAC,CAAA;AAE5B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAW,EAAQ,EAAE;IAC/C,IAAI,YAAY,IAAI,IAAI;QAAE,OAAM;IAChC,IAAI,CAAC;QACH,YAAY,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,CAAA;IAC5C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,CAAC,sCAAsC,CAAC,CAAC;IACtD,YAAY,CAAC,cAAc,CAAC,GAAG,CAAC,CAAA;AAClC,CAAC,CAAA;AAED,MAAM,oBAAoB,GAAG,GAAkB,EAAE;IAC/C,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,CAAC,eAAe,CAAC,CAAA;IAC9C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED,MAAM,kBAAkB,GAAG,CAAC,MAAoB,EAAQ,EAAE;IACxD,IAAI,YAAY,IAAI,IAAI,EAAE,CAAC;QACzB,OAAO,YAAY,CAAA;IACrB,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,EAAE,WAAW,IAAI,MAAM,CAAC,IAAI,EAAE,UAAU,IAAI,WAAW,CAAA;IACtF,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,EAAE,aAAa,IAAI,CAAC,GAAG,cAAc,CAAC,CAAA;IACvE,MAAM,YAAY,GAAG,oBAAoB,EAAE,CAAA;IAC3C,MAAM,GAAG,GAAG,YAAY,IAAI,IAAI,IAAI,aAAa,CAAC,QAAQ,CAAC,YAAY,CAAC;QACtE,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,WAAW,CAAA;IAEf,MAAM,QAAQ,GAAG,cAAc,CAAC;QAC9B,yEAAyE;QACzE,+EAA+E;QAC/E,+EAA+E;QAC/E,oDAAoD;QACpD,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,IAAI,iBAAiB;QACtD,WAAW;QACX,GAAG;QACH,aAAa;QACb,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,IAAI,KAAK;KACxD,CAAC,CAAA;IAEF,QAAQ,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAA;IAErC,OAAO,YAAY,GAAG,QAAQ,CAAA;AAChC,CAAC,CAAA"}
+{"version":3,"file":"instance.js","sourceRoot":"","sources":["../../src/utils/instance.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEhD,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAE/B,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEvH,MAAM,eAAe,GAAG,cAAc,CAAA;AAEtC,IAAI,YAAY,GAAgB,IAAI,CAAA;AAEpC,4FAA4F;AAC5F,IAAI,WAA+B,CAAA;AAEnC,wGAAwG;AACxG,IAAI,YAAgC,CAAA;AAEpC;;;;;;GAMG;AACH,IAAI,gBAAgB,GAA2B,IAAI,CAAA;AAEnD,8FAA8F;AAC9F,IAAI,aAAa,GAAkB,IAAI,CAAA;AAEvC,wFAAwF;AACxF,IAAI,cAAc,GAAkB,IAAI,CAAA;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAkB,EAAE,CAAC,cAAc,CAAA;AAEtE,MAAM,kBAAkB,GAAG,GAAY,EAAE,CAAC,gBAAgB,IAAI,IAAI,IAAI,gBAAgB,EAAE,CAAA;AAExF;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,KAA6B,EAAQ,EAAE;IAC5E,gBAAgB,GAAG,KAAK,CAAA;IACxB,oGAAoG;IACpG,aAAa,GAAG,IAAI,CAAA;IACpB,cAAc,GAAG,IAAI,CAAA;AACvB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAY,EAAE;IAC3C,IAAI,aAAa,IAAI,IAAI,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;QACnD,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,CAAC;QACH,YAAY,CAAC,OAAO,CAAC,eAAe,EAAE,aAAa,CAAC,CAAA;QACpD,aAAa,GAAG,IAAI,CAAA;QAEpB,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAoB,EAAQ,EAAE;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAA;IAE9D,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAoB,EAAQ,EAAE,CAC5D,kBAAkB,CAAC,MAAM,CAAC,CAAA;AAE5B;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAW,EAAiB,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;AAEpF;;;GAGG;AACH,MAAM,cAAc,GAAG,KAAK,EAAE,GAAW,EAAE,OAAgB,EAAiB,EAAE;IAC5E,YAAY,GAAG,GAAG,CAAA;IAClB,MAAM,gBAAgB,CAAC,GAAG,CAAC,CAAA;IAC3B,IAAI,YAAY,KAAK,GAAG,EAAE,CAAC;QACzB,OAAM;IACR,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACZ,cAAc,GAAG,GAAG,CAAA;QACpB,IAAI,kBAAkB,EAAE,EAAE,CAAC;YACzB,aAAa,GAAG,IAAI,CAAA;YACpB,IAAI,CAAC;gBACH,YAAY,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,CAAA;YAC5C,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC,CAAC,sCAAsC,CAAC,CAAC;QACxD,CAAC;aAAM,CAAC;YACN,sFAAsF;YACtF,aAAa,GAAG,GAAG,CAAA;QACrB,CAAC;IACH,CAAC;IACD,IAAI,YAAY,IAAI,IAAI,EAAE,CAAC;QACzB,WAAW,GAAG,GAAG,CAAA;QACjB,OAAM;IACR,CAAC;IACD,MAAM,YAAY,CAAC,cAAc,CAAC,GAAG,CAAC,CAAA;AACxC,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,MAAoB,EAAmB,EAAE;IACzE,MAAM,QAAQ,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAA;IAChD,MAAM,gBAAgB,CAAC,QAAQ,CAAC,CAAA;IAChC,MAAM,GAAG,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAA;IAC1C,IAAI,CAAC;QACH,MAAM,gBAAgB,CAAC,GAAG,CAAC,CAAA;QAC3B,WAAW,GAAG,GAAG,CAAA;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,mCAAmC,GAAG,GAAG,EAAE,KAAK,CAAC,CAAA;QAC/D,WAAW,GAAG,QAAQ,CAAA;IACxB,CAAC;IAED,OAAO,WAAW,CAAA;AACpB,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,MAAoB,EAAU,EAAE;IACrE,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,EAAE,aAAa,IAAI,CAAC,GAAG,cAAc,CAAC,CAAA;IACvE,MAAM,YAAY,GAAG,oBAAoB,EAAE,CAAA;IAE3C,OAAO,YAAY,IAAI,IAAI,IAAI,aAAa,CAAC,QAAQ,CAAC,YAAY,CAAC;QACjE,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,mBAAmB,CAAC,aAAa,EAAE,gBAAgB,EAAE,CAAC,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAA;AAC/F,CAAC,CAAA;AAED,MAAM,uBAAuB,GAAG,CAAC,MAAoB,EAAU,EAAE,CAC/D,MAAM,CAAC,IAAI,EAAE,WAAW,IAAI,MAAM,CAAC,IAAI,EAAE,UAAU,IAAI,WAAW,CAAA;AAEpE,MAAM,oBAAoB,GAAG,GAAkB,EAAE;IAC/C,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,CAAC,eAAe,CAAC,CAAA;IAC9C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,aAAgC,EAAE,SAAiD,EACpE,EAAE;IACjB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAA;IAC7E,KAAK,MAAM,SAAS,IAAI,SAAS,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,CAAA;QACjD,IAAI,GAAG,KAAK,EAAE;YAAE,SAAQ;QACxB,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QACvE,IAAI,KAAK,IAAI,IAAI;YAAE,OAAO,KAAK,CAAA;IACjC,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED,2EAA2E;AAC3E,MAAM,gBAAgB,GAAG,GAAsB,EAAE;IAC/C,IAAI,CAAC;QACH,IAAI,OAAO,SAAS,KAAK,WAAW;YAAE,OAAO,EAAE,CAAA;QAC/C,OAAO,SAAS,CAAC,SAAS,IAAI,IAAI,IAAI,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;YAClE,CAAC,CAAC,SAAS,CAAC,SAAS;YACrB,CAAC,CAAC,SAAS,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAC5D,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC,CAAA;AAED,MAAM,kBAAkB,GAAG,CAAC,MAAoB,EAAQ,EAAE;IACxD,IAAI,YAAY,IAAI,IAAI,EAAE,CAAC;QACzB,OAAO,YAAY,CAAA;IACrB,CAAC;IAED,MAAM,WAAW,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAA;IACnD,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,EAAE,aAAa,IAAI,CAAC,GAAG,cAAc,CAAC,CAAA;IACvE,MAAM,SAAS,GAAG,WAAW,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAA;IAC/D,gGAAgG;IAChG,mGAAmG;IACnG,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAA;IAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAA;IAE5C,MAAM,QAAQ,GAAG,cAAc,CAAC;QAC9B,yEAAyE;QACzE,+EAA+E;QAC/E,+EAA+E;QAC/E,oDAAoD;QACpD,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,IAAI,iBAAiB;QACtD,WAAW;QACX,GAAG;QACH,aAAa;QACb,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,IAAI,KAAK;KACxD,CAAC,CAAA;IAEF,QAAQ,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAA;IAErC,YAAY,GAAG,QAAQ,CAAA;IAEvB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,8EAA8E;QAC9E,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxD,OAAO,CAAC,KAAK,CAAC,mCAAmC,SAAS,GAAG,EAAE,KAAK,CAAC,CAAA;QACvE,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/client-i18n",
-  "version": "0.1.18-rc.4",
+  "version": "0.1.18-rc.41",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -37,9 +37,9 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@owlmeans/client": "^0.1.18-rc.4",
-    "@owlmeans/client-context": "^0.1.18-rc.4",
-    "@owlmeans/i18n": "^0.1.18-rc.4",
+    "@owlmeans/client": "^0.1.18-rc.42",
+    "@owlmeans/client-context": "^0.1.18-rc.39",
+    "@owlmeans/i18n": "^0.1.18-rc.37",
     "i18next": "^26.2.0",
     "react-i18next": "^17.0.11"
   },

package/src/context.tsx

@@ -1,4 +1,4 @@
-import { memo, useCallback, useState } from 'react'
+import { memo, useCallback } from 'react'
 import type { FC } from 'react'
 import type { I18nContextProps } from './types.js'
 import { I18nextProvider, useTranslation } from 'react-i18next'
@@ -77,14 +77,22 @@ export const useI18nApp = (appName?: string, prefix?: string): TFunction => {
   return useI18nResource(resolvedName, resolvedName, prefix)
 }
 
-export const useLanguage = (): [string, (lng: string) => void] => {
+/**
+ * `[currentLng, setLng]`. The current language is read from the i18next instance itself, whose
+ * `languageChanged` event re-renders every subscriber, so all callers agree whoever switched it.
+ * The setter loads the language's pack first; a failed switch is logged and leaves the language
+ * unchanged.
+ */
+export const useLanguage = (): [string, (lng: string) => Promise<void>] => {
   const { i18n } = useTranslation()
-  const [lng, setLng] = useState(i18n.language)
 
-  const changeLng = useCallback((next: string) => {
-    setLanguage(next)
-    setLng(next)
+  const changeLng = useCallback(async (next: string) => {
+    try {
+      await setLanguage(next)
+    } catch (error) {
+      console.error('[i18n] language switch failed', error)
+    }
   }, [])
 
-  return [lng, changeLng]
+  return [i18n.language, changeLng]
 }

package/src/index.ts

@@ -1,3 +1,6 @@
 
 export * from './types.js'
 export { I18nContext, composePrefix, useI18n, useI18nLib, useI18nApp, useLanguage } from './context.js'
+export {
+  prepareI18n, resolveInitialLanguage, setLanguage, setLanguagePersistence, persistLanguage, getExplicitLanguage,
+} from './utils/instance.js'

package/src/utils/instance.ts

@@ -4,12 +4,73 @@ import { initReactI18next } from 'react-i18next'
 import type { i18n } from 'i18next'
 import { useMemo } from 'react'
 import type { ClientConfig } from '@owlmeans/client-context'
-import { DEFAULT_LNG, DEFAULT_NAMESPACE, SUPPORTED_LNGS } from '@owlmeans/i18n'
+import { DEFAULT_LNG, DEFAULT_NAMESPACE, SUPPORTED_LNGS, isI18nLanguageLoaded, loadI18nLanguage } from '@owlmeans/i18n'
 
 const LNG_STORAGE_KEY = 'owlmeans-lng'
 
 let i18nInstance: i18n | null = null
 
+/** The language `prepareI18n` loaded; the instance starts in it when created afterwards. */
+let preparedLng: string | undefined
+
+/** The language of the latest `setLanguage` call — an earlier call that finishes later yields to it. */
+let requestedLng: string | undefined
+
+/**
+ * Whether an explicit language choice may be written to storage right now. Unset, storage is always
+ * allowed — an application with no notion of consent behaves exactly as before. A host that asks its
+ * visitors (`@owlmeans/web-panel/consent`'s `installConsentLanguage`) installs one that answers
+ * "has the visitor allowed functional storage?", so a language is not remembered on a device nobody
+ * asked about.
+ */
+let persistenceGuard: (() => boolean) | null = null
+
+/** The latest explicit choice that storage refused; written the moment storage is allowed. */
+let refusedChoice: string | null = null
+
+/** The latest language a person chose explicitly in this page's life, stored or not. */
+let explicitChoice: string | null = null
+
+/**
+ * The language a person chose explicitly since this page loaded (`setLanguage`), or `null`. What a
+ * host asks before it applies a language that arrived some other way — a link — which must never
+ * override what the person just picked.
+ */
+export const getExplicitLanguage = (): string | null => explicitChoice
+
+const persistenceAllowed = (): boolean => persistenceGuard == null || persistenceGuard()
+
+/**
+ * Install (or, with `null`, remove) the guard that decides whether a language choice may be
+ * remembered. Call it BEFORE `prepareI18n`: the initial language is resolved from storage, and a
+ * guard that says no makes a stored value count as absent.
+ */
+export const setLanguagePersistence = (guard: (() => boolean) | null): void => {
+  persistenceGuard = guard
+  // A new guard starts a new account of what this page's visitor has chosen and what storage refused.
+  refusedChoice = null
+  explicitChoice = null
+}
+
+/**
+ * Write the explicit choice storage refused earlier, now that it may be — call it when the guard's
+ * answer turns to yes (the visitor granted functional storage). `false` when there was nothing
+ * waiting, storage is still refused, or the write failed.
+ */
+export const persistLanguage = (): boolean => {
+  if (refusedChoice == null || !persistenceAllowed()) {
+    return false
+  }
+  try {
+    localStorage.setItem(LNG_STORAGE_KEY, refusedChoice)
+    refusedChoice = null
+
+    return true
+  } catch (_) {
+    return false
+  }
+}
+
 export const useI18nInstance = (config: ClientConfig): i18n => {
   const instance = useMemo(() => createI18nInstance(config), [])
 
@@ -19,15 +80,88 @@ export const useI18nInstance = (config: ClientConfig): i18n => {
 export const getI18nInstance = (config: ClientConfig): i18n =>
   createI18nInstance(config)
 
-export const setLanguage = (lng: string): void => {
-  if (i18nInstance == null) return
+/**
+ * Load `lng`'s registered loaders, then persist it and switch the instance to it. Race-safe:
+ * when several calls overlap, the latest one wins whatever order their loads finish in.
+ * Rejects when the language's pack fails to load; nothing is persisted or switched then.
+ */
+export const setLanguage = (lng: string): Promise<void> => switchLanguage(lng, true)
+
+/**
+ * `setLanguage`'s body. `persist` is false only for the start-up switch to a language nobody chose
+ * (a browser-detected one): only an explicit choice is ever written to `owlmeans-lng`.
+ */
+const switchLanguage = async (lng: string, persist: boolean): Promise<void> => {
+  requestedLng = lng
+  await loadI18nLanguage(lng)
+  if (requestedLng !== lng) {
+    return
+  }
+  if (persist) {
+    explicitChoice = lng
+    if (persistenceAllowed()) {
+      refusedChoice = null
+      try {
+        localStorage.setItem(LNG_STORAGE_KEY, lng)
+      } catch (_) { /* noop in non-browser environments */ }
+    } else {
+      // Not remembered — but not forgotten either: the visitor may allow it a moment later.
+      refusedChoice = lng
+    }
+  }
+  if (i18nInstance == null) {
+    preparedLng = lng
+    return
+  }
+  await i18nInstance.changeLanguage(lng)
+}
+
+/**
+ * Await the app's fallback language and its initial one (`resolveInitialLanguage`) before the app
+ * renders, so the first paint is already in the right language instead of flashing the
+ * fallback and then switching. Call it BEFORE `render(...)`. Resolves to the language the
+ * instance will start in: the fallback when the initial language's pack fails to load — the
+ * persisted choice is kept then, so the next visit retries it. Rejects only when the fallback
+ * language's own pack fails.
+ */
+export const prepareI18n = async (config: ClientConfig): Promise<string> => {
+  const fallback = resolveFallbackLanguage(config)
+  await loadI18nLanguage(fallback)
+  const lng = resolveInitialLanguage(config)
   try {
-    localStorage.setItem(LNG_STORAGE_KEY, lng)
-  } catch (_) { /* noop in non-browser environments */ }
-  i18nInstance.changeLanguage(lng)
+    await loadI18nLanguage(lng)
+    preparedLng = lng
+  } catch (error) {
+    console.error(`[i18n] failed to load pack for "${lng}"`, error)
+    preparedLng = fallback
+  }
+
+  return preparedLng
 }
 
+/**
+ * The language the app starts in: the one persisted under `owlmeans-lng` when it is still in
+ * `supportedLngs` (a person's explicit choice); else, on a first visit, the browser's own language
+ * (`navigator.languages` through `preferredLanguageOf` — a German browser opens in German); else
+ * `fallbackLng ?? defaultLng ?? DEFAULT_LNG`. The instance is initialized with this explicit `lng`,
+ * so a detector plugin installed afterwards (`instance.use(detector)`) is never consulted.
+ */
+export const resolveInitialLanguage = (config: ClientConfig): string => {
+  const supportedLngs = config.i18n?.supportedLngs ?? [...SUPPORTED_LNGS]
+  const persistedLng = getPersistedLanguage()
+
+  return persistedLng != null && supportedLngs.includes(persistedLng)
+    ? persistedLng
+    : preferredLanguageOf(supportedLngs, browserLanguages()) ?? resolveFallbackLanguage(config)
+}
+
+const resolveFallbackLanguage = (config: ClientConfig): string =>
+  config.i18n?.fallbackLng ?? config.i18n?.defaultLng ?? DEFAULT_LNG
+
 const getPersistedLanguage = (): string | null => {
+  if (!persistenceAllowed()) {
+    return null
+  }
   try {
     return localStorage.getItem(LNG_STORAGE_KEY)
   } catch (_) {
@@ -35,17 +169,48 @@ const getPersistedLanguage = (): string | null => {
   }
 }
 
+/**
+ * The first of the browser's preferred languages the application supports — exact (`pt-BR`) or by
+ * its base (`de-DE` → `de`) — or `null` when none is. Pure, so a host (or a test) can pass the list.
+ */
+export const preferredLanguageOf = (
+  supportedLngs: readonly string[], preferred: readonly (string | null | undefined)[],
+): string | null => {
+  const supported = new Map(supportedLngs.map(lng => [lng.toLowerCase(), lng]))
+  for (const candidate of preferred) {
+    const tag = candidate?.trim().toLowerCase() ?? ''
+    if (tag === '') continue
+    const match = supported.get(tag) ?? supported.get(tag.split(/[-_]/)[0])
+    if (match != null) return match
+  }
+
+  return null
+}
+
+/** The browser's preferred languages, in order; `[]` outside a browser. */
+const browserLanguages = (): readonly string[] => {
+  try {
+    if (typeof navigator === 'undefined') return []
+    return navigator.languages != null && navigator.languages.length > 0
+      ? navigator.languages
+      : navigator.language != null ? [navigator.language] : []
+  } catch (_) {
+    return []
+  }
+}
+
 const createI18nInstance = (config: ClientConfig): i18n => {
   if (i18nInstance != null) {
     return i18nInstance
   }
 
-  const fallbackLng = config.i18n?.fallbackLng ?? config.i18n?.defaultLng ?? DEFAULT_LNG
+  const fallbackLng = resolveFallbackLanguage(config)
   const supportedLngs = config.i18n?.supportedLngs ?? [...SUPPORTED_LNGS]
-  const persistedLng = getPersistedLanguage()
-  const lng = persistedLng != null && supportedLngs.includes(persistedLng)
-    ? persistedLng
-    : fallbackLng
+  const wantedLng = preparedLng ?? resolveInitialLanguage(config)
+  // Safety net for a host that did not await `prepareI18n`: start in the fallback and switch once
+  // the wanted language's loaders finish — a brief fallback flash instead of a half-loaded language.
+  const loaded = isI18nLanguageLoaded(wantedLng)
+  const lng = loaded ? wantedLng : fallbackLng
 
   const instance = createInstance({
     // No `compatibilityJSON` — i18next >= 26 accepts only the v4 JSON format
@@ -61,5 +226,14 @@ const createI18nInstance = (config: ClientConfig): i18n => {
 
   instance.use(initReactI18next).init()
 
-  return i18nInstance = instance
+  i18nInstance = instance
+
+  if (!loaded) {
+    // Not persisted: `wantedLng` may be a browser-detected language nobody chose.
+    switchLanguage(wantedLng, false).catch((error: unknown) => {
+      console.error(`[i18n] failed to load pack for "${wantedLng}"`, error)
+    })
+  }
+
+  return instance
 }

package/tests/instance.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=instance.spec.d.ts.map

package/tests/instance.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance.spec.d.ts","sourceRoot":"","sources":["instance.spec.ts"],"names":[],"mappings":""}

package/tests/instance.spec.js

@@ -0,0 +1,23 @@
+import { describe, expect, test } from 'bun:test';
+import { preferredLanguageOf } from '../src/utils/instance.js';
+const SUPPORTED = ['en', 'pl', 'ru', 'be', 'uk', 'es', 'de', 'fr'];
+describe('preferredLanguageOf — the first-visit language', () => {
+    test('a regional tag resolves to its supported base language', () => {
+        expect(preferredLanguageOf(SUPPORTED, ['de-DE'])).toBe('de');
+        expect(preferredLanguageOf(SUPPORTED, ['fr-FR', 'en'])).toBe('fr');
+        expect(preferredLanguageOf(SUPPORTED, ['pl_PL'])).toBe('pl');
+    });
+    test('the browser order decides, and an unsupported language is skipped', () => {
+        expect(preferredLanguageOf(SUPPORTED, ['it-IT', 'de-CH', 'en-US'])).toBe('de');
+        expect(preferredLanguageOf(SUPPORTED, ['EN-us'])).toBe('en');
+    });
+    test('an exact supported tag wins over its base', () => {
+        expect(preferredLanguageOf(['pt', 'pt-BR'], ['pt-BR'])).toBe('pt-BR');
+    });
+    test('nothing supported, or nothing known — null (the caller falls back)', () => {
+        expect(preferredLanguageOf(SUPPORTED, ['it-IT', 'ja'])).toBeNull();
+        expect(preferredLanguageOf(SUPPORTED, [])).toBeNull();
+        expect(preferredLanguageOf(SUPPORTED, [null, undefined, ''])).toBeNull();
+    });
+});
+//# sourceMappingURL=instance.spec.js.map

package/tests/instance.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance.spec.js","sourceRoot":"","sources":["instance.spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAE9D,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;AAElE,QAAQ,CAAC,gDAAgD,EAAE,GAAG,EAAE;IAC9D,IAAI,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAClE,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC5D,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAClE,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC9D,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC7E,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC9E,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC9D,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACrD,MAAM,CAAC,mBAAmB,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACvE,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,oEAAoE,EAAE,GAAG,EAAE;QAC9E,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;QAClE,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;QACrD,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAA;IAC1E,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/tests/instance.spec.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from 'bun:test'
+import { afterEach, beforeEach } from 'bun:test'
+import {
+  persistLanguage, preferredLanguageOf, resolveInitialLanguage, setLanguage, setLanguagePersistence,
+} from '../src/utils/instance.js'
+
+const SUPPORTED = ['en', 'pl', 'ru', 'be', 'uk', 'es', 'de', 'fr']
+
+describe('preferredLanguageOf — the first-visit language', () => {
+  test('a regional tag resolves to its supported base language', () => {
+    expect(preferredLanguageOf(SUPPORTED, ['de-DE'])).toBe('de')
+    expect(preferredLanguageOf(SUPPORTED, ['fr-FR', 'en'])).toBe('fr')
+    expect(preferredLanguageOf(SUPPORTED, ['pl_PL'])).toBe('pl')
+  })
+
+  test('the browser order decides, and an unsupported language is skipped', () => {
+    expect(preferredLanguageOf(SUPPORTED, ['it-IT', 'de-CH', 'en-US'])).toBe('de')
+    expect(preferredLanguageOf(SUPPORTED, ['EN-us'])).toBe('en')
+  })
+
+  test('an exact supported tag wins over its base', () => {
+    expect(preferredLanguageOf(['pt', 'pt-BR'], ['pt-BR'])).toBe('pt-BR')
+  })
+
+  test('nothing supported, or nothing known — null (the caller falls back)', () => {
+    expect(preferredLanguageOf(SUPPORTED, ['it-IT', 'ja'])).toBeNull()
+    expect(preferredLanguageOf(SUPPORTED, [])).toBeNull()
+    expect(preferredLanguageOf(SUPPORTED, [null, undefined, ''])).toBeNull()
+  })
+})
+
+describe('language persistence guard — a choice is remembered only while storage is allowed', () => {
+  const store = new Map<string, string>()
+  const config = { i18n: { supportedLngs: SUPPORTED, fallbackLng: 'en' } } as never
+  let allowed = false
+
+  beforeEach(() => {
+    store.clear()
+    allowed = false
+    ;(globalThis as any).localStorage = {
+      getItem: (k: string) => store.get(k) ?? null,
+      setItem: (k: string, v: string) => { store.set(k, v) },
+      removeItem: (k: string) => { store.delete(k) },
+    }
+    setLanguagePersistence(() => allowed)
+  })
+  afterEach(() => { setLanguagePersistence(null) })
+
+  test('with the guard saying no, an explicit choice is not written', async () => {
+    await setLanguage('pl')
+
+    expect(store.has('owlmeans-lng')).toBe(false)
+  })
+
+  test('the refused choice is written the moment storage is allowed', async () => {
+    await setLanguage('pl')
+    expect(persistLanguage()).toBe(false)
+
+    allowed = true
+
+    expect(persistLanguage()).toBe(true)
+    expect(store.get('owlmeans-lng')).toBe('pl')
+    expect(persistLanguage()).toBe(false)
+  })
+
+  test('the latest refused choice is the one that is written', async () => {
+    await setLanguage('pl')
+    await setLanguage('de')
+    allowed = true
+    persistLanguage()
+
+    expect(store.get('owlmeans-lng')).toBe('de')
+  })
+
+  test('with the guard saying yes, a choice is written at once, as before', async () => {
+    allowed = true
+    await setLanguage('fr')
+
+    expect(store.get('owlmeans-lng')).toBe('fr')
+  })
+
+  test('a stored language counts as absent while the guard says no, and is used once it says yes', () => {
+    store.set('owlmeans-lng', 'de')
+
+    expect(resolveInitialLanguage(config)).not.toBe('de')
+
+    allowed = true
+    expect(resolveInitialLanguage(config)).toBe('de')
+  })
+
+  test('with no guard installed nothing changes: choices are written and read', async () => {
+    setLanguagePersistence(null)
+    await setLanguage('es')
+
+    expect(store.get('owlmeans-lng')).toBe('es')
+    expect(resolveInitialLanguage(config)).toBe('es')
+  })
+})

package/tsconfig.json

@@ -7,5 +7,5 @@
     "rootDir": "./src/",
     "outDir": "./build/"
   },
-  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
 }