langsys-js-typescript 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 0.4.2 - 2026-07-08
+
+### Added
+
+- **Debug-mode diagnostic for the `{key}`-in-markup mistake.** Writing `{name}` instead of `%name%` inside `<Translate>`/`<Phrase>` content fails silently — the framework compiler substitutes it before the SDK sees the text, so the base locale still renders correctly and only translated locales break. The SDK can't observe the original braces, but the fingerprint is unmistakable: `params` supplied with no matching placeholder in the captured content. When `debug` is on, that now emits a warning naming the offending key and the exact fix. The check re-runs only when the params key-SET changes, so a ticking counter doesn't spam the console, and it's silent in production.
+- **`findUnusedParamKeys(texts, params)`** — the underlying detector, exported for wrappers that want the same check around their own rendering. Treats both `{key}` and ICU `{key, plural, …}` as used.
+
+## 0.4.1 - 2026-07-08
+
+### Added
+
+- **`%key%` — markup-safe placeholder spelling for DOM content.** Bare `{key}` written inside `<Translate>`/`<Phrase>` markup is consumed by framework compilers before the SDK ever sees it (Svelte compiles it to an expression; JSX evaluates it). Markup now also accepts `%key%`, which survives compilation as literal text. It's additive — plain `{key}` in vanilla HTML keeps working — and `%key%` is normalized to canonical `{key}` at every capture boundary (content-block tokenizer, `Translate` snapshots, `Phrase` encoding), so the Translation Manager, the wire payloads, and translators only ever see the `{key}` form. Keys are restricted to identifiers (`[A-Za-z_][A-Za-z0-9_]*`), so literal `%` in prose ("20% off", "50% to 60%") can never false-match. `t()` phrases are JS strings with no compiler collision and stay `{key}`-only.
+- **`normalizeMarkupPlaceholders(text)`** — the normalizer, exported for framework wrappers that render content-block tokens through their own templating.
+
+## 0.4.0 - 2026-07-08
+
+Params interpolation for the `Translate` DOM class — content blocks can now carry runtime values the same way `t()` phrases do.
+
+### Added
+
+- **`TranslateOptions.params`** (`Record<string, ParamPrimitive>`) — single-brace `{key}` placeholders, same syntax and semantics as `t()`: unknown keys fall through untouched so missing data stays visible, and Number/Date values are formatted per the active locale's CLDR rules. Interpolation applies everywhere resolved text lands in the DOM — content-block text nodes, translatable attributes, `<select>` option text, and the single-text-run path. Untranslated fallbacks interpolate too, and the base locale gets a render pass when params are present, so placeholders never leak into the UI.
+- **`Translate.setParams(params)`** — swap params after mount (e.g. a changed count) and re-render, mirroring `Phrase.setParams`. The framework bindings expose this as a reactive `params` prop on their `<Translate>` components: `langsys-js-svelte` ≥ 3.3.0, `langsys-js-react` ≥ 0.4.0.
+
+### Fixed
+
+- Content-block text replacement no longer treats `$`-patterns (`$&`, `` $` ``, `$1`…) in translations or interpolated values as `String.replace` directives — they now render literally.
+
 ## 0.3.0 - 2026-07-03
 
 Full CLDR compliance, matching the backend's CLDR migration. Everything rides on the platform's native `Intl` APIs — no new dependencies, no bundled locale data.

package/README.md

@@ -158,6 +158,53 @@ Attributes honored on contained elements:
 - Several validation-message `data-*` attributes
 - `translate="no"` — elements marked this way (and their children) are skipped
 
+### 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:
+
+```html
+<div id="stats">
+    <h2>Hello {name}</h2>
+    <p>You have {count} new messages.</p>
+</div>
+```
+
+```ts
+const stats = document.querySelector<HTMLElement>('#stats')!;
+const handle = new Translate(stats, {
+    category: 'Dashboard',
+    params: { name: 'Sarah', count: 5 },
+});
+
+// Update reactively — e.g. when the count changes:
+handle.setParams({ name: 'Sarah', count: 6 });
+```
+
+The placeholders are part of the registered phrase, so translators see `{name}` and `{count}` and keep them in the translation.
+
+#### `%key%` — the markup-safe spelling
+
+In compiled frameworks, bare `{key}` written in markup never reaches the SDK — Svelte compiles it to an expression and JSX evaluates it. Content passed through `<Translate>`/`<Phrase>` therefore also accepts `%key%`, which survives compilation as literal text:
+
+```svelte
+<Translate category="Dashboard" params={{ name, count }}>
+    <h2>Hello %name%</h2>
+    <p>You have %count% new messages.</p>
+</Translate>
+```
+
+Both spellings are equivalent: `%key%` is normalized to canonical `{key}` at tokenization, so the Translation Manager, the wire, and translators only ever see `{key}`, and existing `{key}` content in vanilla HTML keeps working unchanged. Keys must be identifiers (`[A-Za-z_][A-Za-z0-9_]*`), so literal `%` signs in prose ("20% off") are never touched. `t()` phrases are plain JS strings with no compiler in the way — they stay `{key}`-only.
+
+Writing `{key}` in markup fails *silently* — the base locale still looks right, so the mistake surfaces only once someone switches language. With `debug: true`, the SDK catches it for you: if you pass `params` whose keys have no matching placeholder in the captured content, it warns and names the fix.
+
+```
+Langsys Warning  <Translate> received params with no matching placeholder in its
+content: %count%. If you wrote {count} in markup, the framework compiler
+(Svelte/JSX) substituted it before Langsys saw the text — write %count% 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.
+
 ## 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

@@ -400,6 +400,8 @@ declare class Translate {
     private lastTranslatedLocale;
     private custom_id;
     private unsubscribeLocale;
+    /** Sorted params key-set already checked, so value-only updates don't re-warn. */
+    private checkedParamKeys;
     constructor(element: HTMLElement, options?: TranslateOptions);
     /** Update interpolation params (e.g. a changed count) and re-render. Mirrors `Phrase.setParams`. */
     setParams(params: Record<string, ParamPrimitive> | undefined): void;
@@ -410,6 +412,12 @@ declare class Translate {
     private handleContentBlock;
     private translate;
     private getTranslation;
+    /**
+     * Debug-time check that every supplied param has a placeholder to land in.
+     * Re-runs only when the key SET changes — a changing `count` value must not
+     * re-warn on every render.
+     */
+    private checkParams;
     /**
      * Interpolate `{name}`-style params into a resolved text, matching `t()`:
      * unknown keys fall through untouched, and the untranslated fallback is
@@ -448,12 +456,20 @@ declare class Phrase {
     private slots;
     private unsubscribers;
     private ready;
+    /** Sorted params key-set already checked, so value-only updates don't re-warn. */
+    private checkedParamKeys;
     constructor(host: HTMLElement, options?: PhraseOptions);
     /** Update interpolation params (e.g. a changed count) and re-render. */
     setParams(params: Record<string, unknown>): void;
     /** Stop reacting to locale/translation changes. Safe to call multiple times. */
     destroy(): void;
     private _init;
+    /**
+     * Debug-time check that every supplied param has a placeholder to land in.
+     * Re-runs only when the key SET changes — a changing `n` value must not
+     * re-warn on every render.
+     */
+    private _checkParams;
     private _render;
 }
 
@@ -670,6 +686,30 @@ declare function md5(inputString: string): string;
  * to decide whether to render a plural-slot editor vs. a single text field.
  */
 declare function isICU(template: string): boolean;
+/**
+ * Normalize `%name%` markup placeholders to canonical `{name}`.
+ *
+ * Framework compilers consume bare `{name}` written in markup before the DOM
+ * walker ever sees it (Svelte compiles it to an expression; JSX evaluates it),
+ * so DOM content accepts `%name%` as a collision-free authoring escape.
+ * Normalization runs at every markup capture boundary (content-block
+ * tokenizer, `Translate` original-value snapshots, `Phrase` encoding), so the
+ * catalog, the wire, and translators only ever see the canonical `{name}`
+ * form — and plain `{name}` keeps working for vanilla-HTML authors.
+ *
+ * Keys must be identifiers (`[A-Za-z_][A-Za-z0-9_]*`), so literal `%` in
+ * prose ("20% off", "50% to 60%") can't match. `t()` phrases are JS strings
+ * with no compiler collision and stay `{name}`-only.
+ */
+declare function normalizeMarkupPlaceholders(text: string): string;
+/**
+ * Params keys that have NO matching placeholder in `texts`.
+ *
+ * Texts are expected in canonical form (post-`normalizeMarkupPlaceholders`),
+ * so a key counts as used when it appears as `{key}` or as the argument of an
+ * ICU slot (`{key, plural, …}`). Surrounding whitespace is tolerated.
+ */
+declare function findUnusedParamKeys(texts: string[], params: Record<string, unknown> | undefined): string[];
 /**
  * Substitute placeholders in a translated string with values from `params`.
  *
@@ -738,4 +778,4 @@ interface iProject {
 declare const t: TFunction;
 declare const tSignal: Signal<TFunction>;
 
-export { type EncodedRichText, type ExtractParamKeys, LangsysApp, LangsysAppAPI, type LocaleSource, Logger, PHRASE_MARKER_ATTR, type ParamPrimitive, type ParamsFor, Phrase, type PhraseOptions, type RichSlot, type Signal, type Subscriber, type TArgs, type TFunction, Translate, type TranslateOptions, type TranslationParams, Translations, type Unsubscriber, type Updater, canonicalizeLocale, createSignal, currentlyLoadedLocale, encodeRichText, generateCustomId, getValue, type iCategories, type iContentBlock, type iCountry, type iCountryDialCode, type iCountryList, type iCurrency, type iCurrencyList, type iLangsysConfig, type iLangsysInitConfig, type ResponseObject as iLangsysResponse, type iLanguageName, type iLocaleData, type iLocaleDefault, type iLocaleFlat, type iProject, type iTranslations, interpolate, isContentBlockKnown, isEmpty, isICU, logger, markupTokenValues, md5, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };
+export { type EncodedRichText, type ExtractParamKeys, LangsysApp, LangsysAppAPI, type LocaleSource, Logger, PHRASE_MARKER_ATTR, type ParamPrimitive, type ParamsFor, Phrase, type PhraseOptions, type RichSlot, type Signal, type Subscriber, type TArgs, type TFunction, Translate, type TranslateOptions, type TranslationParams, Translations, type Unsubscriber, type Updater, canonicalizeLocale, createSignal, currentlyLoadedLocale, encodeRichText, findUnusedParamKeys, generateCustomId, getValue, type iCategories, type iContentBlock, type iCountry, type iCountryDialCode, type iCountryList, type iCurrency, type iCurrencyList, type iLangsysConfig, type iLangsysInitConfig, type ResponseObject as iLangsysResponse, type iLanguageName, type iLocaleData, type iLocaleDefault, type iLocaleFlat, type iProject, type iTranslations, interpolate, isContentBlockKnown, isEmpty, isICU, logger, markupTokenValues, md5, normalizeMarkupPlaceholders, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };

package/dist/index.d.ts

@@ -400,6 +400,8 @@ declare class Translate {
     private lastTranslatedLocale;
     private custom_id;
     private unsubscribeLocale;
+    /** Sorted params key-set already checked, so value-only updates don't re-warn. */
+    private checkedParamKeys;
     constructor(element: HTMLElement, options?: TranslateOptions);
     /** Update interpolation params (e.g. a changed count) and re-render. Mirrors `Phrase.setParams`. */
     setParams(params: Record<string, ParamPrimitive> | undefined): void;
@@ -410,6 +412,12 @@ declare class Translate {
     private handleContentBlock;
     private translate;
     private getTranslation;
+    /**
+     * Debug-time check that every supplied param has a placeholder to land in.
+     * Re-runs only when the key SET changes — a changing `count` value must not
+     * re-warn on every render.
+     */
+    private checkParams;
     /**
      * Interpolate `{name}`-style params into a resolved text, matching `t()`:
      * unknown keys fall through untouched, and the untranslated fallback is
@@ -448,12 +456,20 @@ declare class Phrase {
     private slots;
     private unsubscribers;
     private ready;
+    /** Sorted params key-set already checked, so value-only updates don't re-warn. */
+    private checkedParamKeys;
     constructor(host: HTMLElement, options?: PhraseOptions);
     /** Update interpolation params (e.g. a changed count) and re-render. */
     setParams(params: Record<string, unknown>): void;
     /** Stop reacting to locale/translation changes. Safe to call multiple times. */
     destroy(): void;
     private _init;
+    /**
+     * Debug-time check that every supplied param has a placeholder to land in.
+     * Re-runs only when the key SET changes — a changing `n` value must not
+     * re-warn on every render.
+     */
+    private _checkParams;
     private _render;
 }
 
@@ -670,6 +686,30 @@ declare function md5(inputString: string): string;
  * to decide whether to render a plural-slot editor vs. a single text field.
  */
 declare function isICU(template: string): boolean;
+/**
+ * Normalize `%name%` markup placeholders to canonical `{name}`.
+ *
+ * Framework compilers consume bare `{name}` written in markup before the DOM
+ * walker ever sees it (Svelte compiles it to an expression; JSX evaluates it),
+ * so DOM content accepts `%name%` as a collision-free authoring escape.
+ * Normalization runs at every markup capture boundary (content-block
+ * tokenizer, `Translate` original-value snapshots, `Phrase` encoding), so the
+ * catalog, the wire, and translators only ever see the canonical `{name}`
+ * form — and plain `{name}` keeps working for vanilla-HTML authors.
+ *
+ * Keys must be identifiers (`[A-Za-z_][A-Za-z0-9_]*`), so literal `%` in
+ * prose ("20% off", "50% to 60%") can't match. `t()` phrases are JS strings
+ * with no compiler collision and stay `{name}`-only.
+ */
+declare function normalizeMarkupPlaceholders(text: string): string;
+/**
+ * Params keys that have NO matching placeholder in `texts`.
+ *
+ * Texts are expected in canonical form (post-`normalizeMarkupPlaceholders`),
+ * so a key counts as used when it appears as `{key}` or as the argument of an
+ * ICU slot (`{key, plural, …}`). Surrounding whitespace is tolerated.
+ */
+declare function findUnusedParamKeys(texts: string[], params: Record<string, unknown> | undefined): string[];
 /**
  * Substitute placeholders in a translated string with values from `params`.
  *
@@ -738,4 +778,4 @@ interface iProject {
 declare const t: TFunction;
 declare const tSignal: Signal<TFunction>;
 
-export { type EncodedRichText, type ExtractParamKeys, LangsysApp, LangsysAppAPI, type LocaleSource, Logger, PHRASE_MARKER_ATTR, type ParamPrimitive, type ParamsFor, Phrase, type PhraseOptions, type RichSlot, type Signal, type Subscriber, type TArgs, type TFunction, Translate, type TranslateOptions, type TranslationParams, Translations, type Unsubscriber, type Updater, canonicalizeLocale, createSignal, currentlyLoadedLocale, encodeRichText, generateCustomId, getValue, type iCategories, type iContentBlock, type iCountry, type iCountryDialCode, type iCountryList, type iCurrency, type iCurrencyList, type iLangsysConfig, type iLangsysInitConfig, type ResponseObject as iLangsysResponse, type iLanguageName, type iLocaleData, type iLocaleDefault, type iLocaleFlat, type iProject, type iTranslations, interpolate, isContentBlockKnown, isEmpty, isICU, logger, markupTokenValues, md5, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };
+export { type EncodedRichText, type ExtractParamKeys, LangsysApp, LangsysAppAPI, type LocaleSource, Logger, PHRASE_MARKER_ATTR, type ParamPrimitive, type ParamsFor, Phrase, type PhraseOptions, type RichSlot, type Signal, type Subscriber, type TArgs, type TFunction, Translate, type TranslateOptions, type TranslationParams, Translations, type Unsubscriber, type Updater, canonicalizeLocale, createSignal, currentlyLoadedLocale, encodeRichText, findUnusedParamKeys, generateCustomId, getValue, type iCategories, type iContentBlock, type iCountry, type iCountryDialCode, type iCountryList, type iCurrency, type iCurrencyList, type iLangsysConfig, type iLangsysInitConfig, type ResponseObject as iLangsysResponse, type iLanguageName, type iLocaleData, type iLocaleDefault, type iLocaleFlat, type iProject, type iTranslations, interpolate, isContentBlockKnown, isEmpty, isICU, logger, markupTokenValues, md5, normalizeMarkupPlaceholders, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };

package/dist/index.js

@@ -265,6 +265,28 @@ function isICU(template) {
   return ICU_PATTERN.test(template);
 }
 var ICU_PATTERN = /\{[^{}]+,\s*(plural|select|selectordinal|number|date|time)\s*[,}]/;
+function normalizeMarkupPlaceholders(text) {
+  return text.replace(/%([A-Za-z_][A-Za-z0-9_]*)%/g, "{$1}");
+}
+function escapeForRegExp(key) {
+  return key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function findUnusedParamKeys(texts, params) {
+  if (!params) return [];
+  const keys = Object.keys(params);
+  if (!keys.length || !texts.length) return keys;
+  const haystack = texts.join("\0");
+  return keys.filter((key) => !new RegExp(`\\{\\s*${escapeForRegExp(key)}\\s*[,}]`).test(haystack));
+}
+function warnUnmatchedParams(source, texts, params, context) {
+  if (!logger.debugEnabled) return;
+  const unused = findUnusedParamKeys(texts, params);
+  if (!unused.length) return;
+  const keyList = unused.map((key) => `%${key}%`).join(", ");
+  logger.warn(
+    `${source} received params with no matching placeholder in its content: ${keyList}. If you wrote {${unused[0]}} in markup, the framework compiler (Svelte/JSX) substituted it before Langsys saw the text \u2014 write %${unused[0]}% instead.` + (context ? ` [${context}]` : "")
+  );
+}
 function interpolate(template, params, locale) {
   if (isICU(template)) {
     try {
@@ -1141,7 +1163,7 @@ function tokenizeElement(element) {
   const tokens = [];
   const clone = element.cloneNode(true);
   _walkForTokens(element, Array.from(clone.childNodes), tokens, []);
-  return { tokens, content: clone.outerHTML };
+  return { tokens, content: normalizeMarkupPlaceholders(clone.outerHTML) };
 }
 function _writeKnownContentBlockToCache(category, customId) {
   const lookupCat = category || "__uncategorized__";
@@ -1171,7 +1193,7 @@ function _walkForTokens(liveRoot, cloneNodes, tokens, indices) {
     }
     const contentToken = node.nodeValue?.replace(/\s+/g, " ").trim();
     if (node.nodeType === Node.TEXT_NODE && contentToken) {
-      tokens.push(contentToken);
+      tokens.push(normalizeMarkupPlaceholders(contentToken));
       return;
     }
     if (!node.hasChildNodes()) return;
@@ -1186,24 +1208,24 @@ function _tokenizeAttributes(element, tokens) {
   }
   for (const attr of TRANSLATABLE_ATTRIBUTES) {
     const value = element.getAttribute(attr)?.trim();
-    if (value) tokens.push(value);
+    if (value) tokens.push(normalizeMarkupPlaceholders(value));
   }
   if (VALUE_TRANSLATABLE_ELEMENTS.includes(tagName)) {
     const value = element.getAttribute("value")?.trim();
-    if (value) tokens.push(value);
+    if (value) tokens.push(normalizeMarkupPlaceholders(value));
   }
   if (tagName === "input") {
     const inputType = element.getAttribute("type")?.toLowerCase();
     if (inputType && VALUE_TRANSLATABLE_INPUT_TYPES.includes(inputType)) {
       const value = element.getAttribute("value")?.trim();
-      if (value) tokens.push(value);
+      if (value) tokens.push(normalizeMarkupPlaceholders(value));
     }
   }
   if (tagName === "select") {
     const options = element.querySelectorAll("option");
     options.forEach((option) => {
       const optionText = option.textContent?.trim();
-      if (optionText) tokens.push(optionText);
+      if (optionText) tokens.push(normalizeMarkupPlaceholders(optionText));
     });
   }
 }
@@ -1245,6 +1267,8 @@ var Translate = class {
     this.isTokenizing = false;
     this.lastTranslatedLocale = "";
     this.unsubscribeLocale = null;
+    /** Sorted params key-set already checked, so value-only updates don't re-warn. */
+    this.checkedParamKeys = null;
     this.element = element;
     this.options = { ...options };
     this.custom_id = options.custom_id || "";
@@ -1256,6 +1280,7 @@ var Translate = class {
   /** Update interpolation params (e.g. a changed count) and re-render. Mirrors `Phrase.setParams`. */
   setParams(params) {
     this.options.params = params;
+    this.checkParams();
     if (!this.parseComplete) return;
     this.lastTranslatedLocale = "";
     const locale = currentlyLoadedLocale.get();
@@ -1289,6 +1314,7 @@ var Translate = class {
     this.isTokenizing = true;
     const { tokens, content } = tokenizeElement(this.element);
     this.tokens = tokens;
+    this.checkParams();
     const { category = "" } = this.options;
     if (this.tokens.length === 1) {
       this.element.innerText = this.applyParams(LangsysApp.Translations.t(this.tokens[0], category));
@@ -1344,7 +1370,7 @@ var Translate = class {
       }
       if (isEmpty(node.nodeValue?.trim())) return;
       if (isEmpty(node.originalNodeValue)) {
-        node.originalNodeValue = node.nodeValue;
+        node.originalNodeValue = normalizeMarkupPlaceholders(node.nodeValue);
       }
       const contentToken = node.originalNodeValue?.replace(/\s+/g, " ").trim();
       if (!contentToken) return;
@@ -1362,6 +1388,19 @@ var Translate = class {
     const { category = "" } = this.options;
     return LangsysApp.Translations.lookupContent(category, this.custom_id, token);
   }
+  /**
+   * Debug-time check that every supplied param has a placeholder to land in.
+   * Re-runs only when the key SET changes — a changing `count` value must not
+   * re-warn on every render.
+   */
+  checkParams() {
+    if (!this.tokens.length) return;
+    const { params, category = "" } = this.options;
+    const signature = params ? Object.keys(params).sort().join(",") : "";
+    if (signature === this.checkedParamKeys) return;
+    this.checkedParamKeys = signature;
+    warnUnmatchedParams("<Translate>", this.tokens, params, category || void 0);
+  }
   /**
    * Interpolate `{name}`-style params into a resolved text, matching `t()`:
    * unknown keys fall through untouched, and the untranslated fallback is
@@ -1393,7 +1432,7 @@ var Translate = class {
         const optionEl = option;
         if (!optionEl.originalAttributes) optionEl.originalAttributes = {};
         if (optionEl.originalAttributes["textContent"] === void 0) {
-          optionEl.originalAttributes["textContent"] = option.textContent || "";
+          optionEl.originalAttributes["textContent"] = normalizeMarkupPlaceholders(option.textContent || "");
         }
         const originalText = optionEl.originalAttributes["textContent"].trim();
         if (originalText) {
@@ -1407,7 +1446,7 @@ var Translate = class {
     const currentValue = element.getAttribute(attr);
     if (!currentValue) return;
     if (element.originalAttributes[attr] === void 0) {
-      element.originalAttributes[attr] = currentValue;
+      element.originalAttributes[attr] = normalizeMarkupPlaceholders(currentValue);
     }
     const originalValue = element.originalAttributes[attr].trim();
     if (!originalValue) return;
@@ -1426,7 +1465,7 @@ var SENT_SCAN = /\uE000(\d+)\uE001|\uE002(\d+)\uE003/g;
 function encodeRichText(root) {
   const slots = [];
   const phrase = _encodeNodes(Array.from(root.childNodes), slots);
-  return { phrase: phrase.replace(/\s+/g, " ").trim(), slots };
+  return { phrase: normalizeMarkupPlaceholders(phrase.replace(/\s+/g, " ").trim()), slots };
 }
 function _encodeNodes(nodes, slots) {
   let out = "";
@@ -1496,6 +1535,8 @@ var Phrase = class {
     this.slots = [];
     this.unsubscribers = [];
     this.ready = false;
+    /** Sorted params key-set already checked, so value-only updates don't re-warn. */
+    this.checkedParamKeys = null;
     this.host = host;
     this.category = options.category ?? "";
     this.params = options.params ?? {};
@@ -1509,7 +1550,9 @@ var Phrase = class {
   /** Update interpolation params (e.g. a changed count) and re-render. */
   setParams(params) {
     this.params = params ?? {};
-    if (this.ready) this._render();
+    this._checkParams();
+    if (!this.ready) return;
+    this._render();
   }
   /** Stop reacting to locale/translation changes. Safe to call multiple times. */
   destroy() {
@@ -1524,11 +1567,24 @@ var Phrase = class {
     const { phrase, slots } = encodeRichText(this.host);
     this.phrase = phrase;
     this.slots = slots;
+    this._checkParams();
     await LangsysApp.Translations.ready();
     LangsysApp.Translations.t(this.phrase, this.category);
     this.ready = true;
     this._render();
   }
+  /**
+   * Debug-time check that every supplied param has a placeholder to land in.
+   * Re-runs only when the key SET changes — a changing `n` value must not
+   * re-warn on every render.
+   */
+  _checkParams() {
+    if (!this.phrase) return;
+    const signature = Object.keys(this.params).sort().join(",");
+    if (signature === this.checkedParamKeys) return;
+    this.checkedParamKeys = signature;
+    warnUnmatchedParams("<Phrase>", [this.phrase], this.params, this.category || void 0);
+  }
   _render() {
     if (!this.phrase) return;
     const raw = LangsysApp.Translations.lookup(this.phrase, this.category) ?? this.phrase;
@@ -1556,6 +1612,7 @@ exports.canonicalizeLocale = canonicalizeLocale;
 exports.createSignal = createSignal;
 exports.currentlyLoadedLocale = currentlyLoadedLocale;
 exports.encodeRichText = encodeRichText;
+exports.findUnusedParamKeys = findUnusedParamKeys;
 exports.generateCustomId = generateCustomId;
 exports.getValue = getValue;
 exports.interpolate = interpolate;
@@ -1565,6 +1622,7 @@ exports.isICU = isICU;
 exports.logger = logger;
 exports.markupTokenValues = markupTokenValues;
 exports.md5 = md5;
+exports.normalizeMarkupPlaceholders = normalizeMarkupPlaceholders;
 exports.persist = persist;
 exports.reconstitute = reconstitute;
 exports.registerContentBlock = registerContentBlock;