langsys-js-typescript 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 0.5.0 - 2026-08-10
+
+### Changed (breaking, types only)
+
+- **`PhraseOptions.params` is now `Record<string, ParamPrimitive>`**, matching `TranslateOptions.params` and `t()`. It was `Record<string, unknown>`, which allowed values — objects, arrays, functions — that interpolation can only render as `[object Object]`. No runtime behavior changes; this is a compile-time narrowing that surfaces those calls as errors instead of silently rendering garbage. `Phrase.setParams()` now also accepts `undefined`, matching `Translate.setParams()`.
+
+  **Impact:** code typing its params as `Record<string, unknown>` and passing it straight through no longer compiles — including all three framework bindings as of this release. The fix is one line at each call site: declare the params as `Record<string, ParamPrimitive>` (exported from the package root). Runtime is unaffected, so a wrapper that skips the type change still *works*; it just fails `tsc`.
+
+### Added
+
+- **`Phrase` is documented in the README for the first time.** It's been exported since 0.1.0 but had no section, so the only documented tool for markup-bearing content was `Translate` — which splits at tag boundaries and is the wrong choice for a sentence. The new section covers the three reasons it exists (grammatical agreement, reordering, phrase-key stability), and the `Translate` section now shows the literal per-text-node split so the trade-off is visible at the point of decision.
+- Warning against building phrases with template literals (`` t(`Hello, ${name}!`) ``), which registers every runtime value as its own catalog phrase and pollutes the catalog shared across every Langsys SDK.
+- Params doc comments now name the `%name%` markup spelling alongside the canonical `{name}`, including Vue's `{{ name }}` case.
+
 ## 0.4.3 - 2026-07-08
 
 ### Fixed

package/README.md

@@ -72,6 +72,15 @@ Allowed value types: `string | number | Date | boolean`. Numbers and Dates forma
 
 > Translations containing ICU MessageFormat syntax — `{count, plural, one {# item} other {# items}}`, `{gender, select, …}`, `{n, number}`, `{d, date}` — are rendered with full CLDR plural rules for the active locale (Arabic's six categories, Russian's four, etc.). Plain `{name}` slots keep working unchanged.
 
+> **⚠️ Always pass values through `params` — never build the phrase yourself.**
+>
+> ```ts
+> t(`Hello, ${name}!`, 'Greetings');              // ❌ never do this
+> t('Hello, {name}!', 'Greetings', { name });     // ✓
+> ```
+>
+> The template literal resolves *before* `t()` runs, so with a write key the SDK registers `"Hello, Sarah!"` as a brand-new phrase — and every distinct runtime value mints another one ("Hello, Priya!", "Hello, Ahmed!"). Your Translation Manager fills with untranslatable one-offs, and since projects share one catalog across SDKs, it pollutes what every other binding reads too. The SDK cannot detect this: an interpolated string is indistinguishable from an authored one. The `params` form registers the phrase once, with the placeholder intact for translators.
+
 #### Categorization disambiguates context
 
 ```ts
@@ -158,6 +167,14 @@ Attributes honored on contained elements:
 - Several validation-message `data-*` attributes
 - `translate="no"` — elements marked this way (and their children) are skipped
 
+> **`Translate` tokenizes per text node — so inline markup splits a sentence.**
+>
+> ```html
+> <p>My content <strong>is the best</strong> when internationalized.</p>
+> ```
+>
+> registers **three** phrases: `"My content"`, `"is the best"`, `"when internationalized."` That's correct for a block of independent runs, and it's what `Translate` is for. But a translator sees three fragments with no context, and neither reordering nor grammatical agreement can cross a fragment boundary — fatal for a sentence whose word order or noun forms change with the language. When inline markup sits *inside a sentence*, reach for [`Phrase`](#the-phrase-class) instead.
+
 ### Interpolation params
 
 `Translate` accepts the same single-brace `{key}` placeholders as `t()`. Pass `params` and every translated text node and attribute is interpolated after lookup — unknown keys stay visible as-is, and `Number`/`Date` values are formatted per the active locale's CLDR rules:
@@ -206,6 +223,31 @@ instead.
 
 The check runs whenever the params key-set changes, so a ticking `count` won't spam the console, and it's silent in production.
 
+## The `Phrase` class
+
+`Phrase` wraps an element whose contents are **one** translatable sentence *even though it contains inline markup*. Where `Translate` splits at tag boundaries, `Phrase` keeps the run whole.
+
+```ts
+import { Phrase } from 'langsys-js-typescript';
+
+const el = document.querySelector<HTMLElement>('#reviews')!;
+new Phrase(el, { category: 'ProductCard', params: { n: reviewCount } });
+```
+
+```html
+<span id="reviews">Based on %n% <strong>reviews</strong></span>
+```
+
+That registers as a single phrase — `Based on {n} {m0o}reviews{m0c}` — rather than `"Based on {n}"` and `"reviews"`. Three things depend on it:
+
+1. **Grammatical agreement.** The count and the noun it inflects must live in one phrase, or no ICU plural rule can select the right noun form. Russian has four plural categories, Arabic six, Polish four — split them apart and the output is confidently wrong, not merely awkward.
+2. **Reordering.** The markup tokens are ordinary ICU placeholders, so a translator or model *places* them around the translated word: `{m0o}White{m0c} House` → `Casa {m0o}Blanca{m0c}`. Impossible once split at the tag boundary.
+3. **Phrase-key stability.** Your real elements never reach the translator — they're replaced by neutral tokens and reconstituted at render. Framework scoped-CSS classes (`svelte-a1b2c3`) change every build; if they rode along in the phrase, the key would drift and silently re-translate everything.
+
+Use it standalone, or nested inside a `Translate` block to protect specific runs — the block tokenizer skips any subtree carrying `data-ls-phrase` (exported as `PHRASE_MARKER_ATTR`), letting the `Phrase` own it. `setParams()` re-renders on a changed count, same as `Translate`.
+
+If a translation drops or unbalances a markup token, rendering degrades to plain text with the markers stripped — the meaning survives even when the markup doesn't.
+
 ## Server-Side Rendering
 
 Pre-fetch translations on the server and seed them through `initialTranslations` to skip the duplicate client fetch on hydration:

package/dist/index.d.mts

@@ -375,7 +375,13 @@ interface TranslateOptions {
     custom_id?: string;
     /** Optional human-readable label shown in the Translation Manager. */
     label?: string;
-    /** Interpolation params — `{name}`, `{count}`, etc. Same single-brace syntax as `t()`. */
+    /**
+     * Interpolation params — `{name}`, `{count}`, etc. Same single-brace syntax
+     * as `t()`, and what you write in plain DOM. In a framework component's
+     * markup write `%name%` / `%count%` instead: Svelte and JSX consume
+     * `{name}` at compile time (Vue consumes `{{ name }}`), and `%name%` is
+     * normalized back to `{name}` at capture.
+     */
     params?: Record<string, ParamPrimitive>;
 }
 /**
@@ -433,8 +439,15 @@ declare const PHRASE_MARKER_ATTR = "data-ls-phrase";
 interface PhraseOptions {
     /** Category the phrase registers under (disambiguation for translators). */
     category?: string;
-    /** Interpolation params — `{n}` for pluralization, `{name}`, etc. */
-    params?: Record<string, unknown>;
+    /**
+     * Interpolation params — `{n}` for pluralization, `{name}`, etc.
+     *
+     * Those are the canonical spellings, and what you write in plain DOM. In a
+     * framework component's markup write `%n%` / `%name%` instead: Svelte and
+     * JSX consume `{n}` at compile time (Vue consumes `{{ n }}`), and `%n%` is
+     * normalized back to `{n}` at capture.
+     */
+    params?: Record<string, ParamPrimitive>;
 }
 /**
  * DOM handler for a markup-bearing "rich" phrase (`<Phrase>`).
@@ -460,7 +473,7 @@ declare class Phrase {
     private checkedParamKeys;
     constructor(host: HTMLElement, options?: PhraseOptions);
     /** Update interpolation params (e.g. a changed count) and re-render. */
-    setParams(params: Record<string, unknown>): void;
+    setParams(params: Record<string, ParamPrimitive> | undefined): void;
     /** Stop reacting to locale/translation changes. Safe to call multiple times. */
     destroy(): void;
     private _init;

package/dist/index.d.ts

@@ -375,7 +375,13 @@ interface TranslateOptions {
     custom_id?: string;
     /** Optional human-readable label shown in the Translation Manager. */
     label?: string;
-    /** Interpolation params — `{name}`, `{count}`, etc. Same single-brace syntax as `t()`. */
+    /**
+     * Interpolation params — `{name}`, `{count}`, etc. Same single-brace syntax
+     * as `t()`, and what you write in plain DOM. In a framework component's
+     * markup write `%name%` / `%count%` instead: Svelte and JSX consume
+     * `{name}` at compile time (Vue consumes `{{ name }}`), and `%name%` is
+     * normalized back to `{name}` at capture.
+     */
     params?: Record<string, ParamPrimitive>;
 }
 /**
@@ -433,8 +439,15 @@ declare const PHRASE_MARKER_ATTR = "data-ls-phrase";
 interface PhraseOptions {
     /** Category the phrase registers under (disambiguation for translators). */
     category?: string;
-    /** Interpolation params — `{n}` for pluralization, `{name}`, etc. */
-    params?: Record<string, unknown>;
+    /**
+     * Interpolation params — `{n}` for pluralization, `{name}`, etc.
+     *
+     * Those are the canonical spellings, and what you write in plain DOM. In a
+     * framework component's markup write `%n%` / `%name%` instead: Svelte and
+     * JSX consume `{n}` at compile time (Vue consumes `{{ n }}`), and `%n%` is
+     * normalized back to `{n}` at capture.
+     */
+    params?: Record<string, ParamPrimitive>;
 }
 /**
  * DOM handler for a markup-bearing "rich" phrase (`<Phrase>`).
@@ -460,7 +473,7 @@ declare class Phrase {
     private checkedParamKeys;
     constructor(host: HTMLElement, options?: PhraseOptions);
     /** Update interpolation params (e.g. a changed count) and re-render. */
-    setParams(params: Record<string, unknown>): void;
+    setParams(params: Record<string, ParamPrimitive> | undefined): void;
     /** Stop reacting to locale/translation changes. Safe to call multiple times. */
     destroy(): void;
     private _init;