@vielzeug/codex 2.0.0 → 2.0.1

package/data/catalog.json

@@ -73,7 +73,7 @@
         "coins"
       ],
       "slug": "arsenal",
-      "version": "1.1.2"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -124,7 +124,7 @@
         "refine"
       ],
       "slug": "assay",
-      "version": "1.0.0"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -167,7 +167,7 @@
         "ward"
       ],
       "slug": "clockwork",
-      "version": "1.1.2"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -196,7 +196,7 @@
         "refine"
       ],
       "slug": "codex",
-      "version": "1.0.4"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -242,7 +242,7 @@
         "spell"
       ],
       "slug": "coins",
-      "version": "1.0.5"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -281,7 +281,7 @@
         "rune"
       ],
       "slug": "conduit",
-      "version": "1.0.4"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -327,7 +327,7 @@
         "spell"
       ],
       "slug": "courier",
-      "version": "1.1.5"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -417,7 +417,7 @@
         "herald"
       ],
       "slug": "familiar",
-      "version": "1.0.6"
+      "version": "1.0.7"
     },
     {
       "availableDocPages": [
@@ -481,7 +481,7 @@
         "courier"
       ],
       "slug": "flux",
-      "version": "1.0.8"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -527,7 +527,7 @@
         "courier"
       ],
       "slug": "forge",
-      "version": "1.4.0"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -674,7 +674,7 @@
         "vault"
       ],
       "slug": "ledger",
-      "version": "1.1.6"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -692,6 +692,7 @@
         "store"
       ],
       "exports": [
+        "createCatalogTranslator",
         "createTranslationStore",
         "createTranslator",
         "hydrateTranslationStore",
@@ -719,7 +720,7 @@
         "courier"
       ],
       "slug": "lingua",
-      "version": "1.1.4"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -784,7 +785,7 @@
         "dnd"
       ],
       "slug": "orbit",
-      "version": "1.1.3"
+      "version": "1.1.4"
     },
     {
       "availableDocPages": [
@@ -852,7 +853,7 @@
         "orbit"
       ],
       "slug": "ore",
-      "version": "1.3.0"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -908,7 +909,7 @@
         "orbit"
       ],
       "slug": "prism",
-      "version": "1.1.7"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -959,7 +960,7 @@
         "clockwork"
       ],
       "slug": "pulse",
-      "version": "1.0.8"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -1057,7 +1058,7 @@
         "keymap"
       ],
       "slug": "refine",
-      "version": "1.8.0"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -1108,7 +1109,7 @@
         "ledger"
       ],
       "slug": "ripple",
-      "version": "1.3.0"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -1259,7 +1260,7 @@
         "ripple"
       ],
       "slug": "scout",
-      "version": "1.1.7"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -1311,7 +1312,7 @@
         "refine"
       ],
       "slug": "scroll",
-      "version": "1.1.4"
+      "version": "1.1.5"
     },
     {
       "availableDocPages": [
@@ -1379,7 +1380,7 @@
         "wayfinder"
       ],
       "slug": "sourcerer",
-      "version": "1.1.0"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -1438,7 +1439,7 @@
         "vault"
       ],
       "slug": "spell",
-      "version": "1.2.2"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -1563,7 +1564,7 @@
         "ripple"
       ],
       "slug": "vault",
-      "version": "1.0.4"
+      "version": "2.0.0"
     },
     {
       "availableDocPages": [
@@ -1675,5 +1676,5 @@
       "version": "1.0.4"
     }
   ],
-  "version": "1.0.4"
+  "version": "2.0.0"
 }

package/data/llms-full.txt

@@ -1,6 +1,6 @@
 # Vielzeug — Full Documentation
 
-> Complete documentation for 31 packages. Version: 1.0.4
+> Complete documentation for 31 packages. Version: 2.0.0
 
 ---
 
@@ -10969,7 +10969,8 @@ try {
 
 ## Features
 
-- `createTranslator()` compiles immutable multi-locale catalogs.
+- `createCatalogTranslator()` compiles one immutable fixed-locale catalog.
+- `createTranslator()` compiles immutable locale-keyed catalogs.
 - `createTranslationStore()` manages locale changes and declared catalogs.
 - `translate()` renders text and plural messages through explicit catalog nodes.
 - `translateDynamic()` makes runtime-key lookup explicit.
@@ -10996,6 +10997,7 @@ try {
 
 | Symbol | Purpose | Execution mode | Common gotcha |
 | --- | --- | --- | --- |
+| `createCatalogTranslator()` | Compile one immutable locale catalog | Sync | No fallback locales |
 | `createTranslator()` | Compile immutable locale catalogs | Sync | Locale is fixed for translator lifetime |
 | `createTranslationStore()` | Create mutable locale and catalog store | Sync | Load lazy locale explicitly |
 | `hydrateTranslationStore()` | Create store from serialized loaded catalogs | Sync | Serialized state never includes loaders |
@@ -11013,6 +11015,39 @@ try {
 
 ## Translation Factories
 
+### createCatalogTranslator
+
+```ts
+function createCatalogTranslator(
+  catalog: C,
+  options?: CatalogTranslatorOptions,
+): Translator;
+```
+
+Compiles one catalog and returns an immutable fixed-locale translator. Locale defaults to `en` and controls plural selection and diagnostics.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `catalog` | `C` | One catalog containing only messages and grouping objects |
+| `options` | `CatalogTranslatorOptions` | Locale and missing-message handlers; fallback is unavailable |
+
+**Returns:** `Translator`.
+
+**Example:**
+
+```ts
+import { createCatalogTranslator } from '@vielzeug/lingua';
+
+const translator = createCatalogTranslator(
+  { save: 'Enregistrer' },
+  { locale: 'fr' },
+);
+
+translator.translate('save');
+```
+
+---
+
 ### createTranslator
 
 ```ts
@@ -11207,6 +11242,7 @@ type PluralMessage = { readonly plural: Partial> };
 type CatalogNode = Catalog | PluralMessage | string;
 type Catalog = { readonly [key: string]: CatalogNode };
 type Catalogs = Record;
+type CatalogTranslatorOptions = Omit;
 type CatalogLoader = () => Promise;
 type CatalogSource = C | CatalogLoader;
 type CatalogSources = Record>;
@@ -11329,19 +11365,33 @@ const catalog = {
 };
 ```
 
-Use `{ values }` for text replacements. Pass `count` at top level for plural selection; Lingua injects it into selected template.
+Use `{ values }` for text replacements. Pass `count` at top level for plural selection; Lingua injects it into selected template. Absent replacements render as `{name}` by default. `segments()` preserves an own `undefined` or `null` value; omit property to receive `{name}`.
+
+Catalogs contain strings, grouping objects, and explicit `{ plural: ... }` messages only. Keep application data outside catalog, then translate display labels while constructing it.
+
+```ts
+import { createCatalogTranslator } from '@vielzeug/lingua';
+
+const messages = {
+  status: { blocked: 'Blocked', done: 'Done', inProgress: 'In progress' },
+};
+const statusDefinitions = [
+  { labelKey: 'status.inProgress', value: 'in-progress' },
+  { labelKey: 'status.blocked', value: 'blocked' },
+  { labelKey: 'status.done', value: 'done' },
+] as const;
+const translator = createCatalogTranslator(messages);
+const statusOptions = statusDefinitions.map(({ labelKey, value }) => ({ label: translator.translate(labelKey), value }));
+```
 
 ## Render Framework Content
 
 Use `segments()` when replacements are framework nodes, links, or other values that must not be stringified.
 
 ```ts
-import { createTranslator } from '@vielzeug/lingua';
+import { createCatalogTranslator } from '@vielzeug/lingua';
 
-const translator = createTranslator(
-  { en: { error: 'Try {retry} or {support}.' } },
-  { locale: 'en' },
-);
+const translator = createCatalogTranslator({ error: 'Try {retry} or {support}.' });
 
 const retry = { href: '/retry', label: 'retry' };
 const support = { href: '/support', label: 'support' };
@@ -11349,11 +11399,24 @@ const support = { href: '/support', label: 'support' };
 console.log(translator.segments('error', { values: { retry, support } }));
 ```
 
-Render returned array with framework fragment or list primitive.
+Render returned array with framework fragment or list primitive. Give UI values consumer-owned keys before passing them to `segments()`; Lingua preserves value identity and never clones or mutates them.
 
 ## Use Static Catalogs
 
-Use `createTranslator()` when catalog data and locale selection are fixed for translator lifetime.
+Use `createCatalogTranslator()` when one catalog and locale stay fixed for translator lifetime. It defaults locale to `en`; pass `locale` when plural rules or diagnostics need another locale. Lingua snapshots catalog messages during construction. Do not mutate source catalog objects afterward.
+
+```ts
+import { createCatalogTranslator } from '@vielzeug/lingua';
+
+const translator = createCatalogTranslator(
+  { save: 'Enregistrer' },
+  { locale: 'fr' },
+);
+
+console.log(translator.translate('save'));
+```
+
+Use `createTranslator()` when fixed translation requires locale-keyed catalogs and fallback resolution.
 
 ```ts
 import { createTranslator } from '@vielzeug/lingua';
@@ -11407,7 +11470,7 @@ Pass `{ signal }` when an `AbortController` owns subscription lifetime.
 
 ## SSR State
 
-Serialize only resolved catalogs on server, then hydrate client store from payload.
+Serialize resolved catalogs on server, then hydrate client store from same payload. `getSnapshot()` stays referentially stable until store revision changes, so use same hydrated store throughout initial client render.
 
 ```ts
 import { createTranslationStore, hydrateTranslationStore } from '@vielzeug/lingua';
@@ -11444,7 +11507,7 @@ console.log(validateCatalog(catalog, 'en'));
 
 ## Framework Integration
 
-Adapt `getSnapshot()` and `subscribe()` to framework state primitive.
+Pass stable `getSnapshot()` and `subscribe()` methods to framework state primitives. For SSR, create client store from same serialized state used by server before calling `useSyncExternalStore`.
 
 ```ts [React]
 import { useSyncExternalStore } from 'react';
@@ -11452,11 +11515,9 @@ import { useSyncExternalStore } from 'react';
 import type { TranslationStore } from '@vielzeug/lingua';
 
 export function useTranslator(i18n: TranslationStore) {
-  return useSyncExternalStore(
-    (notify) => i18n.subscribe(() => notify()),
-    () => i18n.getSnapshot().translator,
-    () => i18n.getSnapshot().translator,
-  );
+  const snapshot = useSyncExternalStore(i18n.subscribe, i18n.getSnapshot, i18n.getSnapshot);
+
+  return snapshot.translator;
 }
 ```
 
@@ -11510,13 +11571,13 @@ Use Courier loaders when locale catalogs come from HTTP rather than bundled modu
 
 ## Best Practices
 
-- Define plural messages with `{ plural: ... }`.
-- Keep every locale catalog complete for required keys.
+- Define plural messages with `{ plural: ... }` and no sibling metadata.
+- Keep arrays and application metadata outside catalogs.
+- Treat source catalog objects as immutable after construction.
 - Use `translateDynamic()` only for runtime-generated keys.
 - Load a lazy catalog before rendering it.
-- Render `segments()` values with framework-native fragment support.
+- Give UI values keys before passing them to `segments()`.
 - Keep loader functions out of SSR payloads.
-- Pass an `AbortSignal` to subscriptions owned by component or request.
 - Dispose temporary stores after requests, tests, and route lifetimes.
 
 ### Examples

package/data/llms.txt

@@ -1,6 +1,6 @@
 # Vielzeug
 
-> 31 focused TypeScript packages. Version: 1.0.4
+> 31 focused TypeScript packages. Version: 2.0.0
 
 Install any package independently: `pnpm add @vielzeug/<name>`
 

package/data/manifest.json

@@ -4,5 +4,5 @@
   "refine": "refine.json",
   "schemaVersion": 1,
   "search": "search.json",
-  "version": "1.0.4"
+  "version": "2.0.0"
 }