langsys-js-react 0.6.6 → 0.7.0

package/README.md

@@ -33,7 +33,7 @@ If you need the SDK outside React (a Node script, a non-React web app), import f
 npm install langsys-js-react
 ```
 
-`langsys-js-typescript` is installed automatically as a transitive dependency. `react` is a peer dependency you already have.
+`langsys-js-typescript` (`^0.7.3`) is installed automatically as a dependency. `react` is a peer dependency you already have.
 
 ## Creating a Langsys project
 
@@ -67,7 +67,6 @@ export function LangsysGate({ children }: { children: ReactNode }) {
             UserLocaleStore: localeStore,
             baseLocale: 'en-US',
             debug: false,
-            ssrTokenStrategy: 'client',
         }).then((res) => {
             if (res.status) setReady(true);
             else setError(res.errors?.join(', ') ?? 'Init failed');
@@ -82,15 +81,29 @@ export function LangsysGate({ children }: { children: ReactNode }) {
 
 `UserLocaleStore` is a `Signal<string>` — switch it with `setLocale(...)` (from the same `useLocaleStore` call) or `localeStore.set('fr-FR')`, and the SDK reacts. If you'd rather keep the locale store at module scope, `const localeStore = createLocaleStore('en-US')` works too.
 
-Locale identifiers are canonicalized to BCP 47 by the base SDK (v0.3.0+): lowercase input like `'en-us'` still works, but `useCurrentLocale()` and `detectPreferredLocale()` always return the canonical form (`'en-US'`) — compare against that, or normalize your own values with the re-exported `canonicalizeLocale()`.
+Locale identifiers are canonicalized by the base SDK: `'en-US'`, `'EN-US'` and `'en-us'` all normalize to **lowercase** `'en-us'`. `useCurrentLocale()` and `detectPreferredLocale()` return that lowercase form, so compare against `'en-us'` — a test for `'en-US'` never matches. Normalize your own values with the re-exported `canonicalizeLocale()` rather than casing by hand.
+
+### Running without credentials
+
+`init()` without a project id, an API key or a locale store does not throw: it resolves `{ status: false, errors }` and leaves the client unconfigured, so a preview build or a test run without secrets still renders. `t()` shows the source text with its params filled, `<Translate>` and `<Phrase>` show their content as written, and nothing is requested or registered: a registration resolves skipped with the `RegistrationReason` `'not-configured'`. An explicit write, such as `LangsysAppAPI.createTranslatableItems`, throws `LangsysConfigurationError`. `LangsysApp.isConfigured()` reports the state.
+
+To fail loudly instead, pass `requireCredentials: true`. While the client is unconfigured:
+
+- `t()` throws `LangsysConfigurationError`, so a component that calls it throws during render, and the error reaches your nearest error boundary.
+- `<Translate>` and `<Phrase>` still show their content as written. Their registration rejects with the same error, including a block that mounted before `init()` answered, left unhandled so it appears as an unhandled rejection in the console, and fails a test runner that treats those as errors. A block holding a value the build transform did not name registers nothing, so it only reads and stays silent.
+- On a server, the request's `t()` throws and a block's registration never rejects.
+
+`LangsysConfigurationError` is exported from `langsys-js-react` and from `langsys-js-react/server`.
 
 ### SSR token strategy
 
-`ssrTokenStrategy` (default `'client'`) controls when missing tokens are sent during server rendering:
+`ssrTokenStrategy` (default `'client'`) decides what a request scope's `close()` does with the phrases and blocks its [server render](#server-side-rendering-nextjs-remix) missed. The scope reads it from `LangsysApp.init()` in the rendering process, so it applies only where the server calls `init()` too. A client-only app like the one above has no server render, and a server that never calls `init()` sends nothing from the server.
 
-- `'client'` — tokens collected on the server are flushed from the client after hydration. Best for performance.
-- `'server'` — tokens are sent immediately during SSR. Best for reliability and immediate registration.
-- `'auto'` — small batches (≤5) sent from server, larger queued for client.
+- `'client'` (default) — the server sends nothing. The browser registers the misses after hydration when its session may write, and otherwise reports the page for discovery.
+- `'server'` — `close()` sends the misses from the server, from your server's IP rather than a browser's.
+- `'auto'` — `close()` sends a list of fewer than five from the server and leaves a longer one to the browser.
+
+The server sends only when its own key may write; otherwise its misses go to the browser as under `'client'`. With a `writeGrant` configured the server sends nothing under any strategy, because a grant makes write capability per user, and the SDK warns that the strategy is degraded to `'client'`. [README-SSR.md](./README-SSR.md#what-a-server-render-translates-and-discovers) lists what a server render translates and what it discovers.
 
 ## Using translations
 
@@ -141,9 +154,39 @@ t('You have {count} new messages', 'Notifications', { count: 3, extra: 'x' });
 // ❌ Object literal may only specify known properties, and 'extra' does not exist
 ```
 
-Allowed value types: `string | number | Date | boolean`. Since base SDK 0.3.0, values are locale-formatted: numbers go through `Intl.NumberFormat` (`1234.5` → `1.234,5` in `de-DE`) and `Date` values through `Intl.DateTimeFormat` with the medium date style (previously ISO 8601). Pass a string to opt out of formatting. Formatting always uses the catalog locale (falling back to `en`), never the host's default locale, so server and client render identically.
+Allowed value types: `string | number | Date | boolean`. Values are locale-formatted: numbers go through `Intl.NumberFormat` (`1234.5` → `1.234,5` in `de-DE`) and `Date` values through `Intl.DateTimeFormat` with the medium date style. Pass a string to opt out of formatting. Formatting always uses the catalog locale (falling back to `en`), never the host's default locale, so server and client render identically. The same holds inside a translation's plural or gender form.
+
+#### Plurals and gender: write the sentence flat
+
+**Never write ICU.** Write the sentence as it reads, with the count or the name as a `{placeholder}`, and pass the value as a param. Langsys makes each language's plural and gender forms, the base language included:
 
-> Future versions will swap the simple `{name}` runtime for full ICU MessageFormat — adding plural / select — without changing the public signature. Style-less ICU arguments (`{n, number}`, `{d, date}`, `{t, time}`) already format as of base SDK 0.3.0. Today's `t('{count} items', 'Cart', { count })` will evolve to `t('{count, plural, one {# item} other {# items}}', 'Cart', { count })`.
+```tsx
+t('You have {count} new messages', 'Inbox', { count });                                   // ✅
+t('{count, plural, one {# new message} other {# new messages}}', 'Inbox', { count });      // ❌ ICU written by hand
+```
+
+Langsys makes the forms once it has checked the phrase: a translation run checks its own phrases, and an hourly check covers any phrase a run missed. Until then the base language shows the sentence as written. The catalog holds the forms as ICU MessageFormat. Every request carries `X-Langsys-Capabilities: icu`, and `t()` renders the form the count selects with the CLDR plural rules of the loaded catalog's locale (Russian's four categories, Arabic's six). A plural or select renders its `other` branch when its argument isn't passed. Your code passes the same params in every language. A count and the noun it inflects belong in one phrase, or no plural form can reach the noun.
+
+A sentence that says something different at zero is its own phrase, chosen in code, and so is a sentence that differs in the source language itself:
+
+```tsx
+count === 0 ? t('Your inbox is empty.', 'Inbox') : t('You have {count} new messages', 'Inbox', { count });
+```
+
+In a language with grammatical gender, Langsys can turn a plain `{name}` into `{name_gender, select, …}` in the translation. Pass `name_gender` (`'female'`, `'male'` or `'other'`) beside `name` when you know it. `t()` types it as an optional param for every placeholder, `<Phrase params>` and `<Translate params>` take it as it is, and without it the neutral `other` form renders:
+
+```tsx
+t('{name} has been invited', 'Team', { name: 'Ana', name_gender: 'female' });
+```
+
+A plain `{n}` formats a number or a date, and nothing else needs writing. That holds inside a translation that carries a plural or gender form too: the count, written `#` or `{count}`, and every other number format for the loaded catalog's locale. A value passed as a string is written as given, so pass a time of day, or a number in a format of your own, as a string formatted with the loaded locale:
+
+```tsx
+const locale = useCurrentLocale() || 'en';   // '' until the first catalog loads, and Intl throws on ''
+const total = new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }).format(amount);
+const at = new Intl.DateTimeFormat(locale, { timeStyle: 'short' }).format(date);
+t('{count} items, {total}, ready at {at}', 'Orders', { count, total, at });
+```
 
 #### Categorization disambiguates context
 
@@ -158,6 +201,41 @@ Without categorization, "Home" would only have one translation — which can't w
 
 A good rule for category names: the module or feature the phrase lives in (`Account`, `Errors`, `Checkout`, `UI`).
 
+#### Moving content to another category
+
+The category is part of what identifies a phrase or block, so changing it registers the content as new, and it would be translated, and charged for, again. Name the category it was in before, and its translations follow it instead:
+
+```tsx
+import { inCategory, Phrase, Translate } from 'langsys-js-react';
+
+t('Buy now', inCategory('Checkout', { previousCategory: 'Header' }));
+
+<Phrase category="Checkout" previousCategory="Header">Buy <b>now</b></Phrase>
+
+<Translate category="Checkout" previousCategory="Header">
+    <p>Free shipping on every order.</p>
+</Translate>
+```
+
+`t()`'s second argument is a category when it's a string and params when it's an object, so a move goes in the category position, wrapped by `inCategory()`. Use `previousCategory: ''` if the content had no category before.
+
+- **It moves every use.** Langsys keeps one item per text and category, so a move retires the old item for every call that registers that text in that category. Move them all in one release.
+- **Nothing to clean up on a schedule.** The previous category is sent once, on the registration the new code triggers. Once the catalog has the content under its new category, the option does nothing and you can delete it whenever convenient.
+- **No flash on the first deploy.** Until the catalog has the new category, the previous category's translation renders, and the host says where the text came from, `data-ls-previous-contentblock` when it was filled from the old category's block and `data-ls-previous-category` when it was filled from the old category's phrase, so hydration renders the same text.
+- **A block with its own `custom_id` moves in place.** Its id names it whatever its category, so the API moves the block itself, and an older release still registering it under the old category moves it back. Move every use in one release.
+- **On a server entry** (`langsys-js-react/server`), import `inCategory` from there: it is the same function the main entry exports, and `langsys-js-typescript` is a dependency of this package, so importing it directly breaks under pnpm and Yarn PnP.
+- **A nested unit that names no category moves with its block.** A `<Phrase>` or `<Translate>` inside a `<Translate>` (or `<Phrase>`) that holds a component takes the block's `category` and its `previousCategory`, since it is part of the same content. Leave `category` off to inherit; `category=""` names no category and takes neither. A nested unit that names its own `category` takes neither, and moves only if it names its own `previousCategory`. One that names no category but a `previousCategory` of its own takes the block's category and its own previous one. A unit that is not inside a block names what its props say. Markup does the same: a host nested in a block takes the block's category and previous category unless it carries its own `data-ls-category`, and `data-ls-previous-category` beside it names its own previous category, the way the core stamps a host rendered from the previous category.
+
+```tsx
+<Translate category="Checkout" previousCategory="Header">
+    <p>Welcome, <UserName /></p>
+    <Phrase>Free shipping</Phrase>                          {/* Checkout, moved from Header */}
+    <Phrase category="Cart">Your cart</Phrase>               {/* Cart, no move */}
+    <Phrase category="Cart" previousCategory="Basket">Your cart</Phrase> {/* Cart, moved from Basket */}
+</Translate>
+```
+- **Needs base SDK `langsys-js-typescript@^0.7.3`**, which carries the move.
+
 ### `<Translate>` — HTML content blocks
 
 For larger blocks of HTML where the structure should be preserved for the translator:
@@ -182,11 +260,13 @@ The component:
     - **Screen-reader text:** `aria-label`, `aria-placeholder`, `aria-description`, `aria-valuetext`, `aria-roledescription` — worth knowing these are covered, since untranslated ARIA strings are invisible on the page and only surface to someone using a screen reader
     - **Validation messages:** `data-error`, `data-error-message`, `data-validation-message`, `data-invalid-message`, `data-required-message`, `data-pattern-message`
 - Translates the `value` attribute **only where it is a label rather than data**: on `<button>`, and on `<input type="submit">` / `<input type="button">`. Every other input type is left alone, so a text field's value is never rewritten. This is a separate mechanism from the attribute list above — `value` is deliberately *not* in the SDK's `TRANSLATABLE_ATTRIBUTES`; it's gated by `VALUE_TRANSLATABLE_ELEMENTS` / `VALUE_TRANSLATABLE_INPUT_TYPES`.
-- Captures semantic CSS so translators see the styled appearance in the Translation Manager.
+- Registers a snapshot of the block's markup, so translators see its structure in the Translation Manager.
 - Registers the whole thing as a **content block** that translators handle as one unit while still translating the individual phrases inside.
 - Auto re-translates on locale change.
 
-`<Translate>` mounts the SDK's DOM walker on its host element and lets it mutate the rendered output in place, so **keep its children static** — prose, marketing copy, CMS-rendered articles, forms with placeholders. For dynamic per-string values that React owns, use `useT()`.
+`<Translate>` renders its content through the core: the translated text comes back as data, and the component renders it as React elements — your own elements, with their handlers, refs and keys, in the places the translation puts them. It renders the same on a server and in the browser, so a server-rendered page arrives translated and hydrates without a mismatch, and a locale change re-renders it. Keep its children to markup and text — prose, marketing copy, forms with placeholders. For dynamic per-string values that React owns, use `useT()`.
+
+A block whose children hold a component, `lazy`, `Suspense` or `dangerouslySetInnerHTML` cannot be rendered that way, because its content isn't known until React renders it. Such a block renders its children as they are, and the SDK translates it in the browser after it mounts; its `custom_id`, when you give one, is on the element from the first render. The SDK registers such a block once its content has stopped changing for 500 ms, so a `Suspense` fallback that resolves within that time is never registered as the block. A fallback still showing then is registered, because it is what the page shows; if it resolves later, the SDK says so in a debug notice naming both block ids. On a server the SDK warns once that it served such a block in the source language. Until it mounts, such a block shows its children as the build transform left them, `%name%` placeholders included, so keep components out of a block that interpolates values when its server HTML matters: put the component outside the `<Translate>`, or the values in a `<Phrase>` of their own.
 
 ```tsx
 {/* CMS content goes through Translate as-is */}
@@ -195,7 +275,15 @@ The component:
 </Translate>
 ```
 
-`<Translate>` also accepts `params` for placeholder interpolation. Write placeholders as **`%key%`** directly in the markup — applied to the resolved text of content-block nodes, translatable attributes, `<option>` text, and single-token content (untranslated fallbacks included). Number/Date values get CLDR locale formatting. Change `params` after mount and the block re-renders:
+Values in `<Translate>` and `<Phrase>` markup are placeholders. With the build transform enabled (one line of configuration, see [Variables in translated text](#variables-in-translated-text)), write them as you would any JSX:
+
+```tsx
+<Translate category="Cart">You have {items.length} items in your cart.</Translate>
+```
+
+The transform turns `{items.length}` into the placeholder `{items_count}` and passes the value as its param, so the sentence registers once — `You have {items_count} items in your cart.` — for every user and every count, and a translator can give it plural forms.
+
+Without the transform, write the placeholder yourself as **`%key%`** and pass the value in `params`:
 
 ```tsx
 <Translate category="Cart" params={{ count: itemCount }}>
@@ -203,11 +291,11 @@ The component:
 </Translate>
 ```
 
-> **Use `%key%` in `<Translate>`/`<Phrase>` markup, not bare `{key}`.** In JSX a literal `{count}` is a JavaScript expression that React evaluates *before* the SDK's DOM walker sees the text — the braces vanish and interpolation silently breaks (it still looks fine in the base locale, which hides it). `%count%` passes through JSX as plain text; the SDK normalizes it to canonical `{count}` at capture, so **translators and the catalog only ever see `{count}`**, and both spellings hash to the same content-block id. Keys are identifier-shaped (`%[A-Za-z_][A-Za-z0-9_]*%`), so a stray `%` in prose ("50% off") is left untouched. An unknown `%key%` with no matching param renders as `{key}` — matching `t()`'s behavior for unknown keys. (`t()` and the hooks keep `{key}`: JS strings reach the SDK literally, so there's no collision.)
+`%key%` passes through JSX as plain text and the SDK reads it as `{key}`; keys are identifier-shaped (`%[A-Za-z_][A-Za-z0-9_]*%`), so a stray `%` in prose ("50% off") is left alone. `params` apply to text, translatable attributes, `<option>` text and single-token content; numbers and dates get the locale's formatting, inside a plural or gender form too, and changing `params` re-renders the block.
 
-> Since base SDK 0.4.2, running with `debug: true` catches this mistake for you: if you pass `params` whose keys match no placeholder in the captured content, the SDK warns and names the fix (`… received params with no matching placeholder … write %count% instead`). It's silent in production, treats ICU slots as legitimate, and only re-warns when the set of param keys changes.
+Without the transform, a bare `{count}` is evaluated by React before the SDK sees the text. Where it sits inside other text — `You have {count} items` — the component can tell a value was there but not what to call it, so it registers nothing for that block, renders any translation the catalog already holds, and says so once as a debug notice. In a `<Phrase>`, a value inside a part that is not translated, or inside notation such as `<math>`, doesn't count: the phrase's key leaves that part out, so the phrase still registers. Where the value is the only text of its element (`<b>{name}</b>`), it cannot be told from literal text, and the block registers the text it renders. The transform leaves a conditional (`{signedIn ? name : 'guest'}`) as written, so one inside other text registers nothing either. Raw HTML is content, not a variable: a block whose only dynamic part is `dangerouslySetInnerHTML` (a CMS field, say) registers that HTML's text; one that also interpolates a value registers nothing.
 
-`<Translate>` props: `category?`, `custom_id?`, `label?`, `params?`, `tag?` (defaults to `translate`), `className?`, `children`.
+`<Translate>` props: `category?`, `previousCategory?` (see [Moving content to another category](#moving-content-to-another-category)), `custom_id?`, `label?`, `params?`, `tag?` (defaults to `translate`), `className?`, `children`.
 
 ### `<Phrase>` — markup-bearing phrases (pluralization)
 
@@ -225,7 +313,7 @@ The inline elements never reach the translator — they're replaced with neutral
 
 > Note: write placeholders as `%n%` in `<Phrase>` markup (see the `<Translate>` note above) — a bare `{n}` in JSX is an expression and never reaches the SDK.
 
-`<Phrase>` props: `category?`, `params?`, `tag?` (defaults to `span`), `className?`, `children`.
+`<Phrase>` props: `category?`, `previousCategory?`, `params?`, `tag?` (defaults to `span`), `className?`, `children`.
 
 ### `<DontTranslate>` — never-translated regions
 
@@ -237,10 +325,59 @@ import { DontTranslate } from 'langsys-js-react';
 Built with <DontTranslate>Kangen®</DontTranslate> on <DontTranslate>langsys.dev</DontTranslate>
 ```
 
-Renders the host with `translate="no"`, which the base SDK's tokenizer and renderer already honor — the content is never tokenized, registered, or replaced.
+Renders the host with `translate="no"`, which the base SDK's tokenizer and renderer already honor — the content is never tokenized, registered, or replaced. Inside `<Translate>` and `<Phrase>` it is that host element, so the block around it renders on the server like any other markup. A value written inside it is shown as it is; see [Variables in translated text](#variables-in-translated-text) for how the build transform keeps it out of what Langsys stores.
 
 `<DontTranslate>` props: `tag?` (defaults to `span`), `className?`, `children`.
 
+## Variables in translated text
+
+A sentence that shows a value — a name, a count, a date — is one phrase however many values it is shown with. The build transform makes that automatic: inside `<Translate>`, `<Phrase>` and `t()` calls it turns each interpolated value into a named placeholder and passes the value as its param.
+
+```tsx
+<Translate>Hello {user.firstName}, welcome back</Translate>
+// registers "Hello {first_name}, welcome back"
+
+<Phrase>Signed in as <b>{user.name}</b></Phrase>
+// registers "Signed in as {m0o}{name}{m0c}"
+
+t(`You have ${inbox.count} new messages`)
+// registers "You have {inbox_count} new messages"
+```
+
+Enable it with one line, for your build tool:
+
+```ts
+// vite.config.ts
+import langsys from 'langsys-js-react/vite';
+export default defineConfig({ plugins: [langsys(), react()] });
+```
+
+```js
+// next.config.mjs — Turbopack and webpack; Next's own compiler stays on
+import { withLangsys } from 'langsys-js-react/next';
+export default withLangsys({ /* your config */ });
+```
+
+```json
+// babel.config.json — any other Babel setup
+{ "plugins": ["langsys-js-react/babel"] }
+```
+
+It only touches files that import `langsys-js-react`, and reads them with TypeScript's or the standard decorators and, in a `.js` file, Flow; a file it still can't read is left as written, with a build warning, for your compiler to report, and only `<Translate>` and `<Phrase>` imported from it and the `t` a `useT()` call returns; another function named `t` in the same file is left alone. In a `t()` call, the values join the params where `t()` reads them, whichever form you wrote (`t(text, params)` or `t(text, category, params)`); a second argument the build can't see into, such as a variable, is read when the call runs, as `t()` reads it. `+` joins as JavaScript joins it (`'Page ' + (page + 1)` is one value), a name you wrote (`%name%` anywhere in a block, a key in a params object you wrote out, or `{name}` in a `t()` text whose params come from a variable or a spread) is never given to another value, and an argument whose own text has no space (`t(`errors.${code}`)`, `t(`status_${status}`)`) is a key built in the call and is left as it is, so legacy-key mode looks it up. String, number and plain template literals stay text, a fragment's content joins the text around it, and each run of text reaches React as one string, with JSX's whitespace rules applied as written, whether the plugin runs in your Babel config or ahead of another compiler. JSX, conditionals and components inside a block are left as they are, and so is any expression holding JSX (`{items.map((i) => <li key={i}>{i}</li>)}`), which renders elements rather than a value's text. `{children}` that is all the text between two elements is content: a wrapper like `<Translate tag="h1">{children}</Translate>` translates what it is given. Beside text, as in `Read {children}`, or inside a part that is not translated, it is a value like any other. When the page renders, a value that is text, a number, a boolean or a date is the placeholder's param; a boolean stays a boolean, so a select in the translation can branch on it, as it can in `t()`. A bigint is passed as its digits, and `null` or `undefined` renders nothing, as React would render it. On React 19 a promise or a context is read as React reads one, a context left in the content too. Anything else, such as an element, a list or a function, is rendered in its place exactly as React renders it (`Click {icon} to go`).
+
+In a `<Translate>`, the attributes the SDK translates (`alt`, `title`, `placeholder`, `aria-label`, `label` and the rest of its list, and the `value` of a button or a submit button) are part of the block, so a value in one is a placeholder too: `<img alt={`Photo of ${user.name}`} />` registers `Photo of {name}`. A value that appears only inside attributes' text is written as JavaScript writes it into a string. A value that is the whole attribute (`alt={product.name}`), or that also appears in the text, fills its placeholder as a value in the text does: `null` or `undefined` fills it with nothing (`alt=""`), a number or a date is formatted for the locale, and a list or an object is written as React writes an attribute, or, inside an attribute's text, as JavaScript writes it into a string. On an element whose `translate`, `data-notrans` or input `type` is an expression, only the page knows whether the attribute is translated, so the value is left as written and that block registers nothing. A `<Phrase>` doesn't translate its elements' attributes, so they are left as written there. A value right after a `%` and a word (`%s{x}`) is written as `{x}`, the form the SDK stores, since `%s%x%` would read as the placeholder `%s%`.
+
+A value inside a part that is not translated — `<DontTranslate>`, an element with `translate="no"` or `data-notrans`, or code such as `<template>` and `<noscript>` — is shown exactly as written, so the transform leaves it where it is and marks it as a value (`<span data-ls-param="email">`) instead of replacing it. A `translate` or `data-notrans` whose value is an expression is only known when the page renders. In a `<Translate>` a value under it is marked too; a marked value reads as its placeholder wherever it ends up. In a `<Phrase>` it is a placeholder like any other, filled whether the element turns out translated or not. A `<Phrase>` holding a marker you wrote yourself (`<span data-ls-param="count">{count}</span>`) has its other values marked too, so it reads correctly before a translation exists; a value in its translated text that stands where no marker can (in a translated `<svg>`, `<option>`, `<title>` or `<textarea>`) is left as written, and that phrase registers nothing. A name a marker of yours carries is never given to another value. Langsys never stores a marked value: a block's stored content holds the placeholder `{email}` in its place, and a `<Phrase>` keys the whole part as one empty piece of markup (`Signed in as {m0o}{m0c} today`), whatever it holds. Under such an expression, a value that turns out to be translated is filled from its param, formatted like any other. Some parts can't take the marker: inside `<math>`, and inside an `<svg>` that is not translated, a `<span>` draws nothing, and `<textarea>`, `<title>` and `<option>` hold text only. A value in such a part is left as written. A `<Translate>` holding one registers nothing, since its stored content would hold the value. A `<Phrase>` keys that part as one empty piece of markup and registers as usual. In translated text inside an `<svg>`, a value is a placeholder like anywhere else. `<script>`, `<style>` and `<plaintext>` hold raw text, so a value there is left as written, and a `<Translate>` holding one registers nothing. An opt-out set through a spread (`<span {...props}>`) is invisible to the build: write `translate` or `data-notrans` on the element itself.
+
+```tsx
+<Translate>
+    <p>Signed in as <DontTranslate>{user.email}</DontTranslate></p>
+</Translate>
+// registers the tokens "Signed in as"; the page shows the address
+```
+
+**Names** are the same in every Langsys SDK, derived from the expression in snake_case: `user.firstName` → `first_name`, `items.length` → `items_count`, `price.value` → `price`, `formatDate(order.date)` → `date`. Two values that would share a name are told apart by the segment before it (`a.name`, `b.name` → `a_name`, `b_name`), and the same named expression written twice is one placeholder. An expression no name can be derived from — `a + b`, a ternary, a call with several arguments — is named `value`, `value_2`, …, one placeholder each time it appears, even when the same expression repeats, and the build warns about it; give it a name yourself with `%name%` and `params`, which always wins.
+
 ## Hooks & reactive primitives
 
 | Export | Type | Notes |
@@ -252,13 +389,166 @@ Renders the host with `translate="no"`, which the base SDK's tokenizer and rende
 | `useSignal(signal)` | `<T>(s: Signal<T>) => T` | Low-level: subscribe a component to any base-SDK signal. |
 | `createLocaleStore(initial?)` | `(s?: string) => Signal<string>` | Make a user-locale store outside React (module scope). |
 | `t` / `currentlyLoadedLocale` / `sTranslations` | `Signal<…>` | Raw signals for direct subscription outside React. In components, prefer the hooks. |
-| `canonicalizeLocale(locale)` | `(s: string) => string` | Normalize a locale identifier to canonical BCP 47 (`'en-us'` → `'en-US'`) — the same normalization the SDK applies internally. |
+| `canonicalizeLocale(locale)` | `(s: string) => string` | Normalize a locale identifier to the lowercase wire form (`'en-US'` → `'en-us'`) — the same normalization the SDK applies internally. |
+| `useNotifyNavigation(location)` | `(location: unknown) => void` | Tells the SDK the route changed whenever `location` changes. See [Route changes](#route-changes). |
+| `useRenderServerMessage()` | `() => (entry, category?) => string` | Renders server message entries, re-rendering when the locale changes. See [Server messages](#server-messages). |
+| `useWriteEnabled()` | `() => boolean \| undefined` | Whether this session may register content, as decided by the server. See [Write gating](#write-gating) — the `undefined` state is meaningful. |
+
+## Route changes
+
+Call `useNotifyNavigation` once, anywhere under your router, with the router's current location:
+
+```tsx
+import { useNotifyNavigation } from 'langsys-js-react';
+
+// React Router
+function NavigationNotifier() {
+    useNotifyNavigation(useLocation().key);
+    return null;
+}
+
+// Next.js App Router
+function NavigationNotifier() {
+    useNotifyNavigation(usePathname() + '?' + useSearchParams());
+    return null;
+}
+```
+
+Content that stays mounted across a route change — a header, a sidebar, a persistent layout — is not re-rendered by React when only the route changes, so without this the SDK never learns that its phrases now appear on the new page, and discovery never credits that page with them. The hook tells the SDK the route changed; every mounted translated node then looks itself up again at the new URL. Everything else — what is reported, when, and how often — is decided by the SDK.
+
+If your router exposes its own after-navigation callback, calling `notifyNavigation()` there is equivalent.
+
+## Server messages
+
+A Langsys server SDK leaves your framework's own error response exactly as it is and attaches a list of entries beside it — for Laravel, under `langsys_errors` next to the usual `errors` map in the 422 body. Each entry carries `template`, the source sentence with `{markers}`; `params`, the values that fill them; and `message`, the same sentence already filled. It also passes through what the framework reports about the failure, unchanged: `field`, in the framework's own path format, and `code`, the framework's own identifier for the failure (Laravel's `Min`, Pydantic's `string_too_short`) — use it for your logic, never to choose text.
+
+`resolveServerMessages(body, { key })` reads the entries from where the server attached them; `useRenderServerMessage()` renders them in the current locale:
+
+```tsx
+import { resolveServerMessages, useRenderServerMessage } from 'langsys-js-react';
+
+function FormErrors({ body }: { body: unknown }) {
+    const render = useRenderServerMessage();
+    return (
+        <ul>
+            {resolveServerMessages(body, { key: 'langsys_errors' }).map((entry, i) => (
+                <li key={i}>{render(entry)}</li>
+            ))}
+        </ul>
+    );
+}
+```
+
+Pass the same `key` the server SDK is configured with — a dotted path such as `meta.langsys` works too — or a `resolver` that maps the body to entries yourself. One of the two is required: the body is never searched by shape. If the server renames the pieces, pass `pieces`, e.g. `{ template: 'sentence', message: 'text' }`. An entry needs a `template` or a `message`.
+
+An entry renders as the translation of its `template`, filled from `params`, when the catalog has one, and as its `message` otherwise — so a message nobody has translated yet still reads correctly. An entry with no `template` shows its `message`, and `message` is never used as a lookup key. Templates are looked up under one category, `Errors` unless `messagesCategory` is set in `init`, and it has to match the category the server registers them under. An app that renames that category sets `messagesPreviousCategory` to the old name, on the server and in `init` alike: a template with no translation under the new category then renders the old category's translation, and its `message` only when neither has one. The rendering function changes identity whenever the catalog or locale does, so it can be passed to memoised children.
+
+### Inertia
+
+After a failed form, the server SDK flashes the entries and shares them with the page it redirects to as a prop under the same key (`langsys_errors` in the Laravel package, unless configured otherwise). Resolve them from the page's props:
+
+```tsx
+import { usePage } from '@inertiajs/react';
+
+function CardsNew() {
+    const render = useRenderServerMessage();
+    return resolveServerMessages(usePage().props, { key: 'langsys_errors' }).map((entry, i) => (
+        <p key={i}>{render(entry)}</p>
+    ));
+}
+```
+
+A page that follows no failure has no such prop, and renders nothing.
+
+## Migrating from key-based i18n
+
+An app moving from i18next or vue-i18n can keep calling `t()` with its existing keys. Give `init` the source-language files it already has:
+
+```tsx
+import en from './locales/en.json';
+
+LangsysApp.init({
+    projectid,
+    key,
+    UserLocaleStore: store,
+    legacyKeys: [{ name: 'en.json', format: 'i18next', data: en }],
+});
+
+const t = useT();
+t('checkout.title', undefined, { name: 'Ada' }); // "Checkout for Ada" — registered as "Checkout for {name}" under "checkout"
+```
+
+`t()` then resolves its argument as a key first. A key the files hold becomes its value, converted to Langsys placeholders and ICU plurals, and that value — never the key — is the phrase Langsys registers and translates; the key's first segment is its category unless the call passes one. An argument the files do not hold is literal source text. Formats are `i18next`, `vue-i18n` and `plain` (the default); any other makes `init` throw a `LegacyFormatError` naming the file. Leave `legacyKeys` unset and `t()` does no key lookup at all. `LangsysApp.Translations.setLegacyKeys(files | null)` turns the mode on or off later.
+
+## Catalog snapshots
+
+A snapshot is a project's catalog exported to a file, so a first paint or an offline session renders translations with no API call. Load it before the first render:
+
+```tsx
+import snapshot from './langsys-snapshot.json';
+
+LangsysApp.loadSnapshot(snapshot, 'es-es'); // synchronous; false if it holds no catalog for the locale
+createRoot(el).render(<App />);             // the first render already has its translations
+```
+
+The snapshot is a cache, not the catalog of record: `init()` still fetches the catalog, which replaces it and supplies any phrase it lacked, and with no network anything it lacks shows its source text. Never edit a snapshot by hand — export it again. An edited file, a different format, an unsupported version or a missing member is refused with a `SnapshotError` whose `reason` says which.
+
+## Write gating
+
+A write-capable key shipped in public JavaScript is extractable, so **public keys are read-only**. The server decides per session whether that session may register newly-discovered phrases, and the SDK follows that decision — you never compute it client-side, because the same key can be write-enabled from one IP and read-only from another.
+
+When a session is read-only, nothing is lost: the SDK reports the *page URL only* (never phrase content) so Langsys can visit that page from an allow-listed address and register what it finds.
+
+### `useWriteEnabled()`
+
+```tsx
+const writeEnabled = useWriteEnabled(); // boolean | undefined
+```
+
+Three distinct states — **don't collapse them to a boolean**:
+
+| Value | Meaning |
+|---|---|
+| `undefined` | Authorization hasn't landed yet. Not the same as read-only. Also the value throughout SSR, since this is decided in the browser. |
+| `false` | Read-only session. The SDK may report the page URL instead, subject to the key's auto-discovery permission. |
+| `true` | This session registers content directly. |
+
+Defaulting `undefined` to `false` will render a read-only state during every first paint and, under SSR, cause a hydration mismatch.
+
+This package deliberately does **not** re-export the raw `writeEnabled` signal. It is `undefined` for the whole of a server render, so reading it directly during render defeats the guard `useWriteEnabled()` provides. If you genuinely need it outside React's render cycle, import it from `langsys-js-typescript` directly — the capability is available, it just isn't blessed under this binding's name.
+
+### Write grants — for login-walled apps
+
+Content behind a login can't be reached by an external visit, so pass a short-lived JWT your backend mints at login. The server then treats the session as write-enabled.
+
+```tsx
+LangsysApp.init({
+    projectid,
+    key,
+    UserLocaleStore: store,
+    // Prefer the function form: grants are short-lived (~5 min) and the SDK
+    // resolves it fresh before each request, so your auth layer decides when to
+    // mint. A static string expires while the app is still mounted.
+    writeGrant: () => auth.getLangsysGrant(),
+});
+```
+
+If the token only exists *after* `init()` — the usual case — supply it when the user logs in:
+
+```tsx
+import { setWriteGrant } from 'langsys-js-react';
+
+await setWriteGrant(token);   // re-authorizes; resolves once the server has answered
+await setWriteGrant(undefined); // clear on logout — session returns to read-only
+```
+
+`setWriteGrant()` re-authorizes rather than merely storing the token, so `useWriteEnabled()` reflects the new decision once it resolves. Misses occurring *after* the grant lands register directly; earlier ones were already reported through the URL-reporting path.
 
 ## Server-Side Rendering (Next.js, Remix)
 
-The SDK is SSR-compatible. The main pattern is to pre-fetch translations server-side and seed them through `initialTranslations` / `initialTranslationsLocale` so the client doesn't refetch on hydration. `useT` and friends are built on `useSyncExternalStore` with a server snapshot, so they hydrate without a flash of untranslated content when seeded.
+Each server request renders inside a **request scope** of its own, with its own locale, catalog and misses, so concurrent visitors never see each other's language. `renderInRequestScope` from `langsys-js-react/server` opens one around a render. Once the server process has called `LangsysApp.init()`, `useT()`, `<Translate>` and `<Phrase>` render the request's locale on the server, so the served HTML is translated, apart from the blocks [README-SSR](./README-SSR.md#what-a-server-render-translates-and-discovers) lists as translated in the browser. The scope's seed, handed to the browser before hydration (`LangsysApp.seedCatalog`, or `<LangsysProvider seed>` in the Next App Router), makes the first client render match it.
 
-📖 **See [README-SSR.md](./README-SSR.md)** for a complete Next.js (App Router & Pages Router) walkthrough.
+📖 **See [README-SSR.md](./README-SSR.md)** for the walkthrough, including the Next.js App Router.
 
 ## Utilities
 
@@ -289,20 +579,46 @@ const supportedLocales = (await LangsysApp.getLocalesFlat()).map((l) => l.code);
 const locale = LangsysApp.detectPreferredLocale(request.headers.get('Accept-Language'), supportedLocales);
 ```
 
-The matcher tries exact match first (e.g. `en-US`), then language-only (`en` matches `en-GB`), and is script-aware via CLDR likely-subtags (base SDK 0.3.0+): `zh-TW` matches `zh-Hant` and never falls back to `zh-Hans`. Results are always canonical BCP 47; it returns `false` if no match.
+The matcher tries exact match first (e.g. `en-US`), then language-only (`en` matches `en-GB`), and is script-aware via CLDR likely-subtags (base SDK 0.3.0+): `zh-TW` matches `zh-Hant` and never falls back to `zh-Hans`. Results are returned in the SDK's canonical form, which is **lowercase** (`en-us`, `zh-hant`) — see the note under [Initialization](#initialization); it returns `false` if no match.
+
+### Asking your own API for the user's language
+
+`localeHeaders()` returns the request header for the locale the user chose, so your app's calls to its own API answer in that language:
+
+```ts
+import { localeHeaders } from 'langsys-js-react';
+
+fetch('/api/orders', { headers: { ...localeHeaders() } }); // Accept-Language: es-es
+```
 
 ### Waiting for translations to load
 
-When changing locale mid-session, you may want to re-run dependent code after the new translations arrive:
+When changing locale mid-session, you may want to re-run dependent code once the fetch ends:
 
 ```tsx
 useEffect(() => {
     LangsysApp.translationsLoadingPromise.then(() => {
-        // re-render content / regenerate UI here
+        // re-run dependent code here
     });
 }, [locale]);
 ```
 
+`translationsLoadingPromise` settles when the catalog fetch **ends**, whether it succeeded or failed. It never rejects.
+
+- **On success**, the new catalog is in place when it settles, so `t()` already returns the new locale's text. `useCurrentLocale()` follows about 100 ms later, so read it from a later render, not inside `.then()`.
+- **On failure**, the page renders the source text, or the catalog stored for that locale from an earlier load. `useCurrentLocale()` keeps naming the last locale that loaded (`''` before any has) and never reaches the requested one, so a component that waits only for `useCurrentLocale() === requested` waits forever.
+
+Treat a settled promise **and** `useCurrentLocale() === requested` as the only sign that the switch worked:
+
+```tsx
+// loaded  ->  settled && currentLocale === locale
+// not yet ->  anything else
+```
+
+A mismatch is not a failure test: right after a successful fetch settles, the locale has not been written yet. Nothing public tells a failed fetch apart from one that succeeded a moment ago, so if you need an error state, use your own timeout. The SDK logs a failed fetch to the console as an error.
+
+After a failure, the SDK does not fetch that locale again for a backoff window (3 s, doubling with each consecutive failure up to 5 minutes); switching back to it inside the window renders what the failure did. `LangsysApp.refresh()` fetches at once; await the promise it returns, since it does not replace `translationsLoadingPromise`. Setting the locale store to the value it already holds does nothing.
+
 ## License
 
 MIT © Langsys

package/dist/app-zQKL7-vo.d.mts

@@ -0,0 +1,61 @@
+import { LangsysApp as LangsysApp$1, iLangsysInitConfig as iLangsysInitConfig$1, Signal, iLangsysResponse } from 'langsys-js-typescript';
+
+/**
+ * The entry point and its locale store, in a module that imports no React, so the main entry and
+ * `langsys-js-react/server` export the same `LangsysApp` and `createLocaleStore`. A server
+ * process, a Next Server Component included, initializes the SDK through the server entry
+ * without loading React's hooks.
+ */
+
+/**
+ * React-flavored init config. Identical to the base SDK's config except
+ * `UserLocaleStore` is typed as a `Signal<string>` — create one with
+ * `createLocaleStore()` (or get one from the `useLocaleStore` hook). The base
+ * SDK only reads and subscribes to it.
+ */
+interface iLangsysInitConfig extends Omit<iLangsysInitConfig$1, 'UserLocaleStore'> {
+    UserLocaleStore: Signal<string>;
+}
+/**
+ * React SDK entry point — the core singleton itself, re-exported **by
+ * reference**, with `init` typed to take the React-flavoured config.
+ *
+ * There is no wrapper and no list of delegated methods, so every public member
+ * of the core is reachable here the moment it exists, and identity is
+ * preserved: `LangsysApp` here **is** the core's `LangsysApp`. This binding
+ * overrides no behaviour, so the only thing it needs to express is a type.
+ *
+ * Destructuring behaves exactly as on the core. `const { t } = LangsysApp` is
+ * safe — `t` is a getter returning a closure. Prototype methods are not:
+ * `const { refresh } = LangsysApp` detaches the receiver and the call throws.
+ * Call methods on `LangsysApp` itself.
+ *
+ * The type narrows `init` to require a `Signal<string>` for `UserLocaleStore`.
+ * The core accepts the broader `LocaleSource`, which `Signal<string>`
+ * satisfies. Because the type is `Omit<typeof _LangsysApp, 'init'> & {…}` —
+ * keyof-mapped — it does not expose the core's private members: calling one is
+ * a compile error.
+ *
+ * Pinned by `src/surface.test.ts`.
+ */
+declare const LangsysApp: Omit<typeof LangsysApp$1, 'init'> & {
+    init(config: iLangsysInitConfig): Promise<iLangsysResponse>;
+};
+/**
+ * Create a reactive `Signal<string>` to hold the user's selected locale — the
+ * React analog of Svelte's `writable('en-US')`.
+ *
+ * Pass the result as `UserLocaleStore` to `LangsysApp.init`, read it reactively
+ * with `useSignal(store)` (or use the all-in-one `useLocaleStore` hook), and
+ * switch locale with `store.set('fr-FR')`. The base SDK only ever reads and
+ * subscribes to it — it never writes.
+ *
+ * Locale identifiers are canonicalized to BCP 47 by the base SDK (v0.3.0+), so
+ * `'en-us'` still works on input — but `currentlyLoadedLocale` always emits the
+ * canonical form (`'en-us'` — lowercase, per WIRE-3), so compare against the
+ * lowercase form. Verified against the core, not assumed: `canonicalizeLocale`
+ * lowercases both subtags, so a consumer testing `=== 'en-US'` never matches.
+ */
+declare function createLocaleStore(initial?: string): Signal<string>;
+
+export { LangsysApp as L, createLocaleStore as c, type iLangsysInitConfig as i };

package/dist/app-zQKL7-vo.d.ts

@@ -0,0 +1,61 @@
+import { LangsysApp as LangsysApp$1, iLangsysInitConfig as iLangsysInitConfig$1, Signal, iLangsysResponse } from 'langsys-js-typescript';
+
+/**
+ * The entry point and its locale store, in a module that imports no React, so the main entry and
+ * `langsys-js-react/server` export the same `LangsysApp` and `createLocaleStore`. A server
+ * process, a Next Server Component included, initializes the SDK through the server entry
+ * without loading React's hooks.
+ */
+
+/**
+ * React-flavored init config. Identical to the base SDK's config except
+ * `UserLocaleStore` is typed as a `Signal<string>` — create one with
+ * `createLocaleStore()` (or get one from the `useLocaleStore` hook). The base
+ * SDK only reads and subscribes to it.
+ */
+interface iLangsysInitConfig extends Omit<iLangsysInitConfig$1, 'UserLocaleStore'> {
+    UserLocaleStore: Signal<string>;
+}
+/**
+ * React SDK entry point — the core singleton itself, re-exported **by
+ * reference**, with `init` typed to take the React-flavoured config.
+ *
+ * There is no wrapper and no list of delegated methods, so every public member
+ * of the core is reachable here the moment it exists, and identity is
+ * preserved: `LangsysApp` here **is** the core's `LangsysApp`. This binding
+ * overrides no behaviour, so the only thing it needs to express is a type.
+ *
+ * Destructuring behaves exactly as on the core. `const { t } = LangsysApp` is
+ * safe — `t` is a getter returning a closure. Prototype methods are not:
+ * `const { refresh } = LangsysApp` detaches the receiver and the call throws.
+ * Call methods on `LangsysApp` itself.
+ *
+ * The type narrows `init` to require a `Signal<string>` for `UserLocaleStore`.
+ * The core accepts the broader `LocaleSource`, which `Signal<string>`
+ * satisfies. Because the type is `Omit<typeof _LangsysApp, 'init'> & {…}` —
+ * keyof-mapped — it does not expose the core's private members: calling one is
+ * a compile error.
+ *
+ * Pinned by `src/surface.test.ts`.
+ */
+declare const LangsysApp: Omit<typeof LangsysApp$1, 'init'> & {
+    init(config: iLangsysInitConfig): Promise<iLangsysResponse>;
+};
+/**
+ * Create a reactive `Signal<string>` to hold the user's selected locale — the
+ * React analog of Svelte's `writable('en-US')`.
+ *
+ * Pass the result as `UserLocaleStore` to `LangsysApp.init`, read it reactively
+ * with `useSignal(store)` (or use the all-in-one `useLocaleStore` hook), and
+ * switch locale with `store.set('fr-FR')`. The base SDK only ever reads and
+ * subscribes to it — it never writes.
+ *
+ * Locale identifiers are canonicalized to BCP 47 by the base SDK (v0.3.0+), so
+ * `'en-us'` still works on input — but `currentlyLoadedLocale` always emits the
+ * canonical form (`'en-us'` — lowercase, per WIRE-3), so compare against the
+ * lowercase form. Verified against the core, not assumed: `canonicalizeLocale`
+ * lowercases both subtags, so a consumer testing `=== 'en-US'` never matches.
+ */
+declare function createLocaleStore(initial?: string): Signal<string>;
+
+export { LangsysApp as L, createLocaleStore as c, type iLangsysInitConfig as i };