@owlmeans/client-i18n 0.1.18-rc.13 → 0.1.18-rc.15

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.14
 ```
 
 ## 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.12
 ```
 
 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.13",
-  "generatedAt": "2026-09-01T16:49:00.429Z",
+  "version": "0.1.18-rc.15",
+  "generatedAt": "2026-09-04T22:43:25.445Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/client-i18n
 
 **Layer:** Client (React)
-**Install:** `"@owlmeans/client-i18n": "^0.1.18-rc.13"` in `dependencies`
+**Install:** `"@owlmeans/client-i18n": "^0.1.18-rc.15"` in `dependencies`
 
 ## Purpose
 
@@ -26,6 +26,32 @@ Wraps i18next + react-i18next, lazily loads registered bundles from `@owlmeans/i
 | `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)` | Persist and switch, without a component — what `useLanguage`'s setter calls |
+
+**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:
+
+```tsx
+import { useI18nInstance } from '@owlmeans/client-i18n/utils'
+import detector from 'i18next-browser-languagedetector'
+
+const instance = useI18nInstance(context.cfg)
+instance.use(detector)
+```
+
+`@owlmeans/web-panel`'s `render` already does exactly this, so an application on the panel family
+needs none of it.
 
 ## Setup (app root)
 
@@ -45,7 +71,10 @@ function App() {
 
 ## 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
+`fallbackLng` instead of resolving nothing. Every storage access is guarded, so a browser that
+refuses site data still renders.
 
 ```tsx
 function LangSwitch() {
@@ -96,16 +125,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 +157,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.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,GAAI,SAAS,MAAM,EAAE,QAAQ,MAAM,KAAG,MAK/D,CAAA;AAyCD;4FAC4F;AAC5F,eAAO,MAAM,OAAO,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,EAAE,SAAS,MAAM,KAAG,SAExE,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,SAAS,MAAM,KAAG,SAE7D,CAAA;AAED,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,EAAE,SAAS,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,eAAO,MAAM,WAAW,QAAO,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAU5D,CAAA"}

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,GAAI,QAAQ,YAAY,KAAG,IAItD,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,QAAQ,YAAY,KAAG,IAC3B,CAAA;AAE5B,eAAO,MAAM,WAAW,GAAI,KAAK,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;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/client-i18n",
-  "version": "0.1.18-rc.13",
+  "version": "0.1.18-rc.15",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -37,9 +37,9 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@owlmeans/client": "^0.1.18-rc.14",
-    "@owlmeans/client-context": "^0.1.18-rc.11",
-    "@owlmeans/i18n": "^0.1.18-rc.7",
+    "@owlmeans/client": "^0.1.18-rc.16",
+    "@owlmeans/client-context": "^0.1.18-rc.13",
+    "@owlmeans/i18n": "^0.1.18-rc.8",
     "i18next": "^26.2.0",
     "react-i18next": "^17.0.11"
   },