langsys-js-typescript 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 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

package/README.md

@@ -195,6 +195,16 @@ In compiled frameworks, bare `{key}` written in markup never reaches the SDK —
 
 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;
 }
 
@@ -686,6 +702,14 @@ declare function isICU(template: string): boolean;
  * 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`.
  *
@@ -754,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, normalizeMarkupPlaceholders, 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;
 }
 
@@ -686,6 +702,14 @@ declare function isICU(template: string): boolean;
  * 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`.
  *
@@ -754,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, normalizeMarkupPlaceholders, 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

@@ -268,6 +268,25 @@ 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 {
@@ -1248,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 || "";
@@ -1259,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();
@@ -1292,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));
@@ -1365,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
@@ -1499,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 ?? {};
@@ -1512,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() {
@@ -1527,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;
@@ -1559,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;