@owlmeans/client-i18n 0.1.18-rc.39 → 0.1.18-rc.40

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@^0.1.18-rc.39
+bun add @owlmeans/client-i18n@^0.1.18-rc.40
 ```
 
 ## 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@^0.1.18-rc.38
+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.39",
-  "generatedAt": "2026-09-23T19:57:40.687Z",
+  "version": "0.1.18-rc.40",
+  "generatedAt": "2026-09-24T14:00:35.045Z",
   "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.39"` in `dependencies`
+**Install:** `"@owlmeans/client-i18n": "^0.1.18-rc.40"` 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,7 +22,8 @@ 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 }` |
@@ -36,19 +37,26 @@ The instance itself, for a host that has to configure i18next before the tree re
 |---|---|
 | `useI18nInstance(config)` | The i18next instance for this application, memoised for the mount |
 | `getI18nInstance(config)` | The same instance outside React |
-| `setLanguage(lng)` | Persist and switch, without a component — what `useLanguage`'s setter calls |
+| `setLanguage(lng)` | Async: load `lng`'s pack (`loadI18nLanguage`), then persist and switch — what `useLanguage`'s setter calls |
+| `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 six live in `src/utils/instance.ts`; the package root re-exports `prepareI18n`,
+`resolveInitialLanguage` and `setLanguage`.
+
 **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: 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; only an explicit choice 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)
 
@@ -66,6 +74,25 @@ 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 — but
@@ -76,6 +103,17 @@ the browser's language, then `fallbackLng`, instead of resolving nothing. Every
 `tests/instance.spec.ts` pins `preferredLanguageOf` (base matching, browser order, exact tag first,
 `null` when nothing matches).
 
+`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() {
   const [lng, setLng] = useLanguage()

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 } 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,EAAE,WAAW,EAAE,sBAAsB,EAAE,WAAW,EAAE,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 } 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,EAAE,WAAW,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA"}

package/build/utils/instance.d.ts

@@ -2,7 +2,29 @@ import type { i18n } from 'i18next';
 import type { ClientConfig } from '@owlmeans/client-context';
 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.

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;AAUD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,kBACf,SAAS,MAAM,EAAE,aAAa,SAAS,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,KAClF,MAAM,GAAG,IAUX,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;AAa5D,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;AAwBpF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,WAAkB,YAAY,KAAG,OAAO,CAAC,MAAM,CAatE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,WAAY,YAAY,KAAG,MAO7D,CAAA;AAaD;;;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,23 +1,83 @@
 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;
 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) {
+        try {
+            localStorage.setItem(LNG_STORAGE_KEY, lng);
+        }
+        catch (_) { /* noop in non-browser environments */ }
+    }
+    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 = () => {
     try {
         return localStorage.getItem(LNG_STORAGE_KEY);
@@ -59,15 +119,13 @@ 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();
-    // A person's explicit choice first; on a first visit the browser's own language — the instance is
-    // initialized right here with an explicit `lng`, so a detector plugin installed afterwards
-    // (`instance.use(detector)`) is never consulted and cannot do this.
-    const lng = persistedLng != null && supportedLngs.includes(persistedLng)
-        ? persistedLng
-        : preferredLanguageOf(supportedLngs, browserLanguages()) ?? 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`).
@@ -80,6 +138,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":"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"}
+{"version":3,"file":"instance.js","sourceRoot":"","sources":["../../src/utils/instance.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/client-i18n",
-  "version": "0.1.18-rc.39",
+  "version": "0.1.18-rc.40",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -37,9 +37,9 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@owlmeans/client": "^0.1.18-rc.40",
-    "@owlmeans/client-context": "^0.1.18-rc.38",
-    "@owlmeans/i18n": "^0.1.18-rc.36",
+    "@owlmeans/client": "^0.1.18-rc.41",
+    "@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,4 @@
 
 export * from './types.js'
 export { I18nContext, composePrefix, useI18n, useI18nLib, useI18nApp, useLanguage } from './context.js'
+export { prepareI18n, resolveInitialLanguage, setLanguage } from './utils/instance.js'

package/src/utils/instance.ts

@@ -4,12 +4,18 @@ 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
+
 export const useI18nInstance = (config: ClientConfig): i18n => {
   const instance = useMemo(() => createI18nInstance(config), [])
 
@@ -19,14 +25,77 @@ 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) {
+    try {
+      localStorage.setItem(LNG_STORAGE_KEY, lng)
+    } catch (_) { /* noop in non-browser environments */ }
+  }
+  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 => {
   try {
     return localStorage.getItem(LNG_STORAGE_KEY)
@@ -70,15 +139,13 @@ const createI18nInstance = (config: ClientConfig): i18n => {
     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()
-  // A person's explicit choice first; on a first visit the browser's own language — the instance is
-  // initialized right here with an explicit `lng`, so a detector plugin installed afterwards
-  // (`instance.use(detector)`) is never consulted and cannot do this.
-  const lng = persistedLng != null && supportedLngs.includes(persistedLng)
-    ? persistedLng
-    : preferredLanguageOf(supportedLngs, browserLanguages()) ?? 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
@@ -94,5 +161,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
 }