@owlmeans/i18n 0.1.18-rc.2 → 0.1.18-rc.20

package/README.md

@@ -11,7 +11,7 @@ Multi-level translation resource registration for OwlMeans applications.
 ## Installation
 
 ```bash
-bun add @owlmeans/i18n
+bun add @owlmeans/i18n@^0.1.18-rc.19
 ```
 
 ## Usage
@@ -62,7 +62,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.24
 ```
 
 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/i18n",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.497Z",
+  "version": "0.1.18-rc.20",
+  "generatedAt": "2026-09-15T12:59:01.020Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/i18n
 
 **Layer:** Core (no runtime deps)
-**Install:** `"@owlmeans/i18n": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/i18n": "^0.1.18-rc.20"` in `dependencies`
 
 ## Purpose
 
@@ -21,11 +21,27 @@ Global registration store that packages write into at import time. React clients
 | `addI18nLib(lng, resource, data, opts?)` | Register library-owned strings (ns defaults to `'lib'`) |
 | `addI18nApp(lng, resource, data, opts?)` | Register app-owned strings (ns defaults to resource name) |
 | `initI18nResource(lng, resource, ns?)` | Drain a registered bundle for a language (called by client-i18n) |
-| `SUPPORTED_LNGS` | `['en','pl','ru','be','uk','es','de']` — the canonical language set |
+| `SUPPORTED_LNGS` / `SupportedLng` | `['en','pl','ru','be','uk','es','de']` — the canonical language set, and its union type |
 | `DEFAULT_LNG` | `'en'` |
 | `LIB_NAMESPACE` | `'lib'` |
+| `DEFAULT_NAMESPACE` | `'translation'` — i18next's own default namespace, used whenever a lookup names none and `I18nConfig.defaultNs` is unset |
 | `I18nTier` | `Library \| App` — enum used internally |
 | `I18nConfig` | `{ defaultLng?, defaultNs?, fallbackLng?, supportedLngs? }` |
+| `I18nResourceOptions` | `{ ns?, priority? }` — the `opts` every `add*` takes |
+| `MAX_PRIORITY` | `Number.MAX_SAFE_INTEGER` — the value substituted for an unset `priority`, which is what makes an unset one sort last |
+
+`opts` also accepts a bare string, which is read as `ns`: `addI18nLib('en', 'wallet', walletEn, 'did')`.
+
+## Subpath Exports
+
+- `./utils` — the store itself: `_OwlMeansI18nStorage` (`{ data }`, keyed ns → resource → language),
+  `ensureStructure(lng, resource, ns?)` which creates and returns one slot, and `tierCost`, the
+  `I18nTier` → number map the sort is written against.
+
+Reach for `./utils` only to work around the drain-once rule below: assigning
+`_OwlMeansI18nStorage.data = {}` empties every slot including its `lngInitialized` marks, so a
+suite can register and drain the same resource repeatedly. This package's own tests do exactly
+that between cases. Application and library code registers through `addI18nLib` / `addI18nApp`.
 
 ## Tiers
 
@@ -34,7 +50,30 @@ Global registration store that packages write into at import time. React clients
 | Library | `addI18nLib` | `'lib'` | Any `@owlmeans/*` package |
 | App | `addI18nApp` | resource name | Project-specific app / shared project package |
 
-App-tier strings deep-merge **over** Library-tier strings for the same keys at resolution time — this is the override mechanism.
+App-tier strings deep-merge **over** Library-tier strings at resolution time — but only for the
+same **(ns, resource, language)** slot, because that triple is the address the store is keyed on
+and the only thing `initI18nResource` drains. The default namespaces differ (`'lib'` for
+`addI18nLib`, the resource name for `addI18nApp`), so overriding a library bundle means saying so:
+
+```typescript
+import { addI18nApp, LIB_NAMESPACE } from '@owlmeans/i18n'
+
+addI18nApp('en', 'errors', myErrors, { ns: LIB_NAMESPACE })
+```
+
+Without `{ ns: LIB_NAMESPACE }` the app bundle lands in namespace `errors` while the library's sits
+in `lib`. Nothing errors, nothing merges, and the library strings keep rendering.
+
+Within one tier the order is `priority`, ascending, and every bundle is merged over the one before
+it — so the **last** applied wins. A registration that states no `priority` sorts last and
+therefore beats every one that states a number: `priority` lowers a bundle in the stack rather than
+raising it. Leave it unset unless one library must lose to another.
+
+**A bundle only reaches i18next if it was registered before the first draw for its language.**
+`initI18nResource` marks the (ns, resource, language) slot drained and answers `null` for every
+later call, so an `import '@owlmeans/<pkg>'` evaluated after a screen has rendered adds nothing a
+component can read. Register at module load — a side-effect import at the top of the entry file,
+which is what re-exporting `./i18n.js` from `src/index.ts` achieves.
 
 ## Per-package pattern
 

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

@@ -28,7 +28,7 @@ The **resource name** is a stable identifier for the registering package, e.g. `
 
 ## Compound prefix keys
 
-A key like `t('title')` resolves to `namespace : resource.prefix.key`. The prefix is composed by joining segments with `.` via `composePrefix` (never by hand-concatenating strings).
+A key like `t('title')` resolves to `namespace : resource.prefix.key`. The prefix is composed by joining segments with `.` via `composePrefix` — exported from `@owlmeans/client-i18n` (and re-exported by `@owlmeans/web-panel` and `@owlmeans/mui-panel`), never by hand-concatenating strings.
 
 Example chain:
 ```
@@ -44,31 +44,59 @@ t('title')
 
 ## Context-based prefix switching
 
-Use `PanelContext` (from `@owlmeans/client-panel`) to inject `resource`, `ns`, or `prefix` into a React sub-tree. Child components that call `usePanelI18n()` or `useFormI18n()` automatically pick up the context value.
+Use `PanelContext` (from `@owlmeans/client-panel`) to inject `resource`, `ns` or `prefix` into a
+React sub-tree. Child components that call `usePanelI18n()` pick those three up, and a nested
+`PanelContext` inherits the outer one field by field.
 
 ```tsx
-// Override the active namespace/resource for a sub-tree
-<PanelContext resource="wl-manager" ns="lib" prefix="wl-dns">
-  <DnsForm />  {/* DnsForm calls usePanelI18n() — gets ns='lib', resource='wl-manager', prefix='wl-dns' */}
+// Read a library's own bundle from inside an app sub-tree
+<PanelContext resource="payment" ns="lib" prefix="plan">
+  <Text name="label.monthly" />  {/* usePanelI18n() → lib:payment.plan.label.monthly */}
 </PanelContext>
 ```
 
-Use `i18n` props on individual components to override just one level:
+`suppress` is **not** one of them. `TPanelContext` accepts it because it spreads `I18nBaseProps`,
+but `usePanelI18n` reads only `prefix`, `resource` and `ns`, so a `<PanelContext suppress>` changes
+nothing for any child. Suppression is per component, from that component's own `i18n` prop — which
+is what `Button` and `ActionCtrl` check before translating a label.
+
+**Form fields sit in a different context.** `useFormI18n` reads the form context that `FormContext`
+publishes from the enclosing `Form`'s own `i18n` and `name` props; it never touches `PanelContext`.
+So wrapping a form or a field in `<PanelContext …>` changes nothing for any field — redirect a
+field by naming the enclosing `Form` or by giving that `Form` an `i18n` prop.
+
+Use the `i18n` prop on an individual component to override just one level. It is declared by the
+components whose props extend `I18nProps` — `Block`, `Text`, `Link`, `Status`, `Button` and `Form`
+in both panel families:
 ```tsx
-<StatusLabel i18n={{ prefix: 'my-status' }} />
+<Status i18n={{ prefix: 'my-status' }} />
 ```
 
+Not every component carrying copy has it, and the two that lack it read different contexts.
+`TextInput` — props extend `FormFieldProps` (`name`, `def`) and add `label`, `placeholder`, `hint`,
+`type` and `disableAutocomplete` — resolves `<name>.label`, `<name>.placeholder` and `<name>.hint`
+through `useFormI18n` when the matching prop is `true`, and renders the prop's own string when it
+is given one; redirect it through the enclosing `Form`. `ButtonSelector` — `SelectorProps` is `name`,
+`current`, `options` and `onSelect` — renders one `Button` per option labelled `<name>.<option>`,
+and `Button` resolves through `usePanelI18n` with the app `buttons` and `lib:client-panel.buttons`
+fallbacks; a surrounding `PanelContext` is what redirects it.
+
 ## App-level override of library strings
 
-App-tier registrations deep-merge over Library-tier for the same `(ns, resource)`:
+App-tier registrations deep-merge over Library-tier for the same `(ns, resource)` — and the
+namespace has to be said out loud, because `addI18nApp` defaults it to the **resource** name while
+the library's bundle sits in `lib`:
 ```typescript
-import '@owlmeans/error'                    // Library tier: lib:errors.*
-import { addI18nApp } from '@owlmeans/i18n'
+import '@owlmeans/error'                              // Library tier: lib:errors.*
+import { addI18nApp, LIB_NAMESPACE } from '@owlmeans/i18n'
 import myErrors from './i18n/en.json'
 
-addI18nApp('en', 'errors', myErrors)        // App tier wins for matching keys
+addI18nApp('en', 'errors', myErrors, { ns: LIB_NAMESPACE })   // App tier wins for matching keys
 ```
 
+Drop `{ ns: LIB_NAMESPACE }` and the app bundle lands in namespace `errors` while `useI18nLib('errors')`
+reads `lib`. Nothing errors and the library strings keep rendering.
+
 ## Per-package checklist
 
 When adding translatable strings to any package:

package/build/advertise.d.ts

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

package/build/advertise.d.ts.map

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

package/build/advertise.js

@@ -0,0 +1,12 @@
+import { apiConfigPlugin } from '@owlmeans/api-config';
+apiConfigPlugin({
+    allow: {
+        i18n: {
+            defaultLng: true,
+            defaultNs: true,
+            fallbackLng: true,
+            supportedLngs: true,
+        },
+    },
+});
+//# sourceMappingURL=advertise.js.map

package/build/advertise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advertise.js","sourceRoot":"","sources":["../src/advertise.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAEtD,eAAe,CAAC;IACd,KAAK,EAAE;QACL,IAAI,EAAE;YACJ,UAAU,EAAE,IAAI;YAChB,SAAS,EAAE,IAAI;YACf,WAAW,EAAE,IAAI;YACjB,aAAa,EAAE,IAAI;SACpB;KACF;CACF,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/i18n",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18-rc.20",
   "license": "MIT",
   "type": "module",
   "scripts": {