@owlmeans/i18n 0.1.7 → 0.1.9

package/README.md

@@ -53,3 +53,20 @@ The global translation store. Read by platform-specific i18n adapters (e.g. `@ow
 ## Related Packages
 
 - [`@owlmeans/client-i18n`](../client-i18n) — React i18next adapter that reads from `i18nStorage`
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/instructions/i18n.instructions.md

@@ -0,0 +1,42 @@
+---
+description: "How to use @owlmeans/i18n — the core localization registry. Use when adding translatable strings to a library package or importing from this package."
+applyTo: "**/*.ts, **/*.tsx"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/i18n
+
+**Layer:** Core (no runtime deps)
+**Version:** `"@owlmeans/i18n": "^0.1.9"`
+
+## Key exports
+
+| Export | Description |
+|--------|-------------|
+| `addI18nLib(lng, resource, data, opts?)` | Register library strings (ns=`'lib'`) |
+| `addI18nApp(lng, resource, data, opts?)` | Register app strings (ns=resource name) |
+| `initI18nResource(lng, resource, ns?)` | Drain bundles for a language (internal use by client-i18n) |
+| `SUPPORTED_LNGS` | `['en','pl','ru','be','uk','es','de']` |
+| `I18nTier` | `Library \| App` |
+| `I18nConfig` | `{ defaultLng?, defaultNs?, fallbackLng?, supportedLngs? }` |
+
+## Per-package i18n registration pattern
+
+```typescript
+// src/i18n.ts
+import { addI18nLib } from '@owlmeans/i18n'
+import en from './i18n/en.json' with { type: 'json' }
+import pl from './i18n/pl.json' with { type: 'json' }
+// … ru, be, uk, es, de
+addI18nLib('en', 'my-package', en)
+addI18nLib('pl', 'my-package', pl)
+// … all 7 languages
+```
+
+Export from `src/index.ts`: `export * from './i18n.js'`
+
+## Invariants
+
+- **All 7 languages required**: never add a key to `en.json` without adding it to pl/ru/be/uk/es/de in the same commit.
+- Library packages use `addI18nLib`; apps use `addI18nApp`.
+- Custom namespace via `opts.ns` only when keys must live outside `'lib'` (e.g. DID's `{ ns: 'did' }`).

package/agent-meta/instructions/localization.instructions.md

@@ -0,0 +1,72 @@
+---
+description: "OwlMeans localization conventions — tiered namespace model, compound-prefix keys, 7-language requirement, override pattern. Apply whenever adding UI strings, JSON translation files, or i18n hooks to any package."
+applyTo: "**/*.ts, **/*.tsx, **/i18n/**"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# OwlMeans Localization Conventions
+
+## Canonical languages
+
+`SUPPORTED_LNGS` from `@owlmeans/i18n`:
+```
+en  pl  ru  be  uk  es  de
+```
+
+**Every new translation key must exist in all 7 language files in the same commit.**
+
+## Tiered namespace model
+
+| Package type | Register with | namespace | key path |
+|---|---|---|---|
+| `@owlmeans/*` library | `addI18nLib` | `'lib'` | `resource.prefix.key` |
+| App / shared project | `addI18nApp` | resource name | `resource.prefix.key` |
+
+App tier overrides Library tier for the same key.
+
+## Compound prefix keys
+
+```
+t('title') via useI18nLib('errors', 'form')
+→ namespace='lib', key='errors.form.title'
+→ resolves errors.json → form.title
+
+t('title') via useI18nApp(undefined, 'home-screen')
+→ namespace='my-app', key='my-app.home-screen.title'
+→ resolves my-app i18n data → home-screen.title
+```
+
+## Context-based prefix switching
+
+`PanelContext` (from `@owlmeans/client-panel`) injects `{ resource, ns, prefix }` into a React subtree. Children call `usePanelI18n()` / `useFormI18n()` which inherit the context.
+
+```tsx
+<PanelContext resource="wl-manager" ns="lib" prefix="wl-dns">
+  <DnsSection />
+</PanelContext>
+```
+
+## Hook selection guide
+
+| Where | Hook |
+|---|---|
+| `@owlmeans/*` library component | `useI18nLib('resource', 'prefix')` |
+| App / project component | `useI18nApp(undefined, 'prefix')` |
+| Inside panel/form context | `usePanelI18n('name')` / `useFormI18n()` |
+| ns ≠ resource (rare) | `useI18n('resource', 'ns', 'prefix')` |
+
+## Adding a new translatable string — checklist
+
+1. Add key to `en.json`
+2. Add the same key (with translation) to `pl.json`, `ru.json`, `be.json`, `uk.json`, `es.json`, `de.json`
+3. Use a hook in the component — never hardcode the string
+
+## Language switcher
+
+```tsx
+import { useLanguage } from '@owlmeans/client-i18n'
+import { SUPPORTED_LNGS } from '@owlmeans/i18n'
+
+const [lng, setLng] = useLanguage()
+// persisted to localStorage automatically
+```

package/agent-meta/manifest.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/i18n",
+  "version": "0.1.9",
+  "generatedAt": "2026-06-14T13:34:06.124Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "localization",
+      "category": "multi-package",
+      "file": "skills/localization/SKILL.md",
+      "canonicalPath": ".claude/skills/localization/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "name": "i18n",
+      "category": "package-specific",
+      "file": "skills/i18n/SKILL.md",
+      "canonicalPath": ".claude/skills/i18n/SKILL.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "localization",
+      "category": "multi-package",
+      "file": "instructions/localization.instructions.md",
+      "canonicalPath": ".github/instructions/localization.instructions.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "i18n",
+      "category": "package-specific",
+      "file": "instructions/i18n.instructions.md",
+      "canonicalPath": ".github/instructions/i18n.instructions.md"
+    }
+  ]
+}

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

@@ -0,0 +1,96 @@
+---
+name: i18n
+description: How to use @owlmeans/i18n — the core localization registry (no runtime deps). Auto-invoked when adding translatable strings to a library package, importing from this package, or working with the tier/priority system.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/i18n
+
+**Layer:** Core (no runtime deps)
+**Install:** `"@owlmeans/i18n": "^0.1.9"` in `dependencies`
+
+## Purpose
+
+Global registration store that packages write into at import time. React clients drain it lazily via `@owlmeans/client-i18n`. The store is addressed by **(ns, resource, language)**.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `addI18nLib(lng, resource, data, opts?)` | Register library-owned strings (ns defaults to `'lib'`) |
+| `addI18nApp(lng, resource, data, opts?)` | Register app-owned strings (ns defaults to resource name) |
+| `initI18nResource(lng, resource, ns?)` | Drain a registered bundle for a language (called by client-i18n) |
+| `SUPPORTED_LNGS` | `['en','pl','ru','be','uk','es','de']` — the canonical language set |
+| `DEFAULT_LNG` | `'en'` |
+| `LIB_NAMESPACE` | `'lib'` |
+| `I18nTier` | `Library \| App` — enum used internally |
+| `I18nConfig` | `{ defaultLng?, defaultNs?, fallbackLng?, supportedLngs? }` |
+
+## Tiers
+
+| Tier | Helper | Default ns | When to use |
+|------|--------|-----------|-------------|
+| 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.
+
+## Per-package pattern
+
+Every package that ships translatable strings exports a side-effect `i18n.ts`:
+
+```typescript
+// src/i18n.ts
+import { addI18nLib } from '@owlmeans/i18n'
+import en from './i18n/en.json' with { type: 'json' }
+import pl from './i18n/pl.json' with { type: 'json' }
+import ru from './i18n/ru.json' with { type: 'json' }
+import be from './i18n/be.json' with { type: 'json' }
+import uk from './i18n/uk.json' with { type: 'json' }
+import es from './i18n/es.json' with { type: 'json' }
+import de from './i18n/de.json' with { type: 'json' }
+
+addI18nLib('en', 'my-package', en)
+addI18nLib('pl', 'my-package', pl)
+addI18nLib('ru', 'my-package', ru)
+addI18nLib('be', 'my-package', be)
+addI18nLib('uk', 'my-package', uk)
+addI18nLib('es', 'my-package', es)
+addI18nLib('de', 'my-package', de)
+```
+
+Then re-export from `src/index.ts`:
+```typescript
+export * from './i18n.js'
+```
+
+## Key structure
+
+Keys are plain dot-paths inside a JSON file:
+```json
+{
+  "mySection": {
+    "title": "Title",
+    "description": "Description"
+  },
+  "form-field": "Invalid field"
+}
+```
+
+Consumers use `useI18nLib('my-package', 'mySection')` → `t('title')` → resolves `lib:my-package.mySection.title`.
+
+## Custom namespace (rare)
+
+Use the optional `opts.ns` when keys must live in a namespace other than `'lib'`:
+```typescript
+addI18nLib('en', 'wallet', walletEn, { ns: 'did' })
+```
+
+## Languages
+
+All packages **must** ship all 7 languages from `SUPPORTED_LNGS`. Adding a new key → add it to all 7 files in the same commit.
+
+## Depends On
+
+Nothing at runtime — pure types and helpers.

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

@@ -0,0 +1,108 @@
+---
+name: localization
+description: OwlMeans localization conventions — tiered namespace model, compound-prefix keys, 7-language requirement, override pattern, and language switcher. Auto-invoked when adding UI strings, translation keys, language files, or working with i18n in any package.
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# OwlMeans Localization Conventions
+
+## Canonical language set
+
+```typescript
+import { SUPPORTED_LNGS } from '@owlmeans/i18n'
+// ['en', 'pl', 'ru', 'be', 'uk', 'es', 'de']
+```
+
+**Rule: every new key must be present in all 7 language files in the same commit.** No English-only additions.
+
+## Addressing model (tiered shared namespace)
+
+Keys are addressed as: `(namespace, resource.prefix.key)`.
+
+| Who registers | Helper | namespace | key path |
+|---|---|---|---|
+| `@owlmeans/*` library package | `addI18nLib` | `'lib'` | `resource.prefix.key` |
+| App or shared project package | `addI18nApp` | resource name | `resource.prefix.key` |
+
+The **resource name** is a stable identifier for the registering package, e.g. `'errors'`, `'payment'`, `'viable-manager-web'`.
+
+## Compound prefix keys
+
+A key like `t('title')` resolves to `namespace : resource.prefix.key`. The prefix is composed by joining segments with `.` via `composePrefix` (never by hand-concatenating strings).
+
+Example chain:
+```
+addI18nApp('en', 'viable-manager-web', data)
+// data = { "home-screen": { "title": "Welcome" } }
+
+const t = useI18nApp(undefined, 'home-screen')
+// → namespace: 'viable-manager-web', keyPrefix: 'viable-manager-web.home-screen'
+
+t('title')
+// → 'viable-manager-web' : 'viable-manager-web.home-screen.title' → "Welcome"
+```
+
+## 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.
+
+```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' */}
+</PanelContext>
+```
+
+Use `i18n` props on individual components to override just one level:
+```tsx
+<StatusLabel i18n={{ prefix: 'my-status' }} />
+```
+
+## App-level override of library strings
+
+App-tier registrations deep-merge over Library-tier for the same `(ns, resource)`:
+```typescript
+import '@owlmeans/error'                    // Library tier: lib:errors.*
+import { addI18nApp } from '@owlmeans/i18n'
+import myErrors from './i18n/en.json'
+
+addI18nApp('en', 'errors', myErrors)        // App tier wins for matching keys
+```
+
+## Per-package checklist
+
+When adding translatable strings to any package:
+
+1. Create `src/i18n/en.json` (and pl, ru, be, uk, es, de in the same commit)
+2. Create `src/i18n.ts` registering all 7 languages (see `i18n` skill for the template)
+3. Re-export from `src/index.ts`: `export * from './i18n.js'`
+4. In components, use `useI18nLib` (library package) or `useI18nApp` (app package) — never hardcode UI strings
+
+## Language switcher
+
+Use `useLanguage()` from `@owlmeans/client-i18n`. The selection is persisted to `localStorage`.
+
+```tsx
+import { useLanguage } from '@owlmeans/client-i18n'
+import { SUPPORTED_LNGS } from '@owlmeans/i18n'
+
+function LanguageSwitcher() {
+  const [lng, setLng] = useLanguage()
+  return (
+    <select value={lng} onChange={e => setLng(e.target.value)}>
+      {SUPPORTED_LNGS.map(l => <option key={l} value={l}>{l.toUpperCase()}</option>)}
+    </select>
+  )
+}
+```
+
+## When to use which hook
+
+| Situation | Hook |
+|---|---|
+| React component in a `@owlmeans/*` library package | `useI18nLib('resource-name', 'prefix')` |
+| React component in an app or shared project package | `useI18nApp(undefined, 'prefix')` |
+| Inside `usePanelI18n` / `useFormI18n` territory (panel/form context) | `usePanelI18n('name')` / `useFormI18n()` |
+| Explicit ns ≠ resource (rare, e.g. DID namespace) | `useI18n('resource', 'ns', 'prefix')` |
+
+Never call `useI18n` directly from product code unless ns and resource genuinely differ.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/i18n",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "license": "MIT",
   "type": "module",
   "scripts": {