langsys-js-typescript 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 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,43 @@ 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.
+
 ## 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,6 +375,8 @@ 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()`. */
+    params?: Record<string, ParamPrimitive>;
 }
 /**
  * Wrap a DOM element and manage translation for its contents.
@@ -399,6 +401,8 @@ declare class Translate {
     private custom_id;
     private unsubscribeLocale;
     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;
     /** Stop reacting to locale changes. Safe to call multiple times. */
     destroy(): void;
     private translateUpdate;
@@ -406,6 +410,12 @@ declare class Translate {
     private handleContentBlock;
     private translate;
     private getTranslation;
+    /**
+     * Interpolate `{name}`-style params into a resolved text, matching `t()`:
+     * unknown keys fall through untouched, and the untranslated fallback is
+     * interpolated too. No-op when no params were supplied.
+     */
+    private applyParams;
     private translateAttributes;
     private translateAttribute;
 }
@@ -660,6 +670,22 @@ 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;
 /**
  * Substitute placeholders in a translated string with values from `params`.
  *
@@ -728,4 +754,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, 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

@@ -375,6 +375,8 @@ 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()`. */
+    params?: Record<string, ParamPrimitive>;
 }
 /**
  * Wrap a DOM element and manage translation for its contents.
@@ -399,6 +401,8 @@ declare class Translate {
     private custom_id;
     private unsubscribeLocale;
     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;
     /** Stop reacting to locale changes. Safe to call multiple times. */
     destroy(): void;
     private translateUpdate;
@@ -406,6 +410,12 @@ declare class Translate {
     private handleContentBlock;
     private translate;
     private getTranslation;
+    /**
+     * Interpolate `{name}`-style params into a resolved text, matching `t()`:
+     * unknown keys fall through untouched, and the untranslated fallback is
+     * interpolated too. No-op when no params were supplied.
+     */
+    private applyParams;
     private translateAttributes;
     private translateAttribute;
 }
@@ -660,6 +670,22 @@ 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;
 /**
  * Substitute placeholders in a translated string with values from `params`.
  *
@@ -728,4 +754,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, 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,9 @@ 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 interpolate(template, params, locale) {
   if (isICU(template)) {
     try {
@@ -1141,7 +1144,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 +1174,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 +1189,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));
     });
   }
 }
@@ -1253,6 +1256,14 @@ var Translate = class {
       if (locale && this.parseComplete) this.translateUpdate(locale);
     });
   }
+  /** Update interpolation params (e.g. a changed count) and re-render. Mirrors `Phrase.setParams`. */
+  setParams(params) {
+    this.options.params = params;
+    if (!this.parseComplete) return;
+    this.lastTranslatedLocale = "";
+    const locale = currentlyLoadedLocale.get();
+    if (locale) this.translateUpdate(locale);
+  }
   /** Stop reacting to locale changes. Safe to call multiple times. */
   destroy() {
     if (this.unsubscribeLocale) {
@@ -1265,7 +1276,7 @@ var Translate = class {
     if (this.lastTranslatedLocale === currentLocale) return;
     const { category = "" } = this.options;
     if (this.tokens.length === 1) {
-      this.element.innerText = LangsysApp.Translations.t(this.tokens[0], category);
+      this.element.innerText = this.applyParams(LangsysApp.Translations.t(this.tokens[0], category));
     } else {
       this.translate(Array.from(this.element.childNodes));
       this.lastTranslatedLocale = currentLocale;
@@ -1283,7 +1294,7 @@ var Translate = class {
     this.tokens = tokens;
     const { category = "" } = this.options;
     if (this.tokens.length === 1) {
-      this.element.innerText = LangsysApp.Translations.t(this.tokens[0], category);
+      this.element.innerText = this.applyParams(LangsysApp.Translations.t(this.tokens[0], category));
     } else {
       const contentBlock = {
         custom_id: "",
@@ -1319,7 +1330,7 @@ var Translate = class {
   }
   translate(nodes) {
     const currentLocale = currentlyLoadedLocale.get();
-    if (currentLocale === config.baseLocale && (this.lastTranslatedLocale === "" || this.lastTranslatedLocale === config.baseLocale)) {
+    if (currentLocale === config.baseLocale && (this.lastTranslatedLocale === "" || this.lastTranslatedLocale === config.baseLocale) && isEmpty(this.options.params)) {
       return;
     }
     nodes.forEach((node) => {
@@ -1336,15 +1347,16 @@ 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;
       const translation = this.getTranslation(contentToken);
       if (translation && contentToken && node.originalNodeValue) {
-        node.nodeValue = node.originalNodeValue.replace(contentToken, translation);
+        const resolved = this.applyParams(translation);
+        node.nodeValue = node.originalNodeValue.replace(contentToken, () => resolved);
       } else if (node.originalNodeValue) {
-        node.nodeValue = node.originalNodeValue;
+        node.nodeValue = this.applyParams(node.originalNodeValue);
       }
     });
   }
@@ -1353,6 +1365,16 @@ var Translate = class {
     const { category = "" } = this.options;
     return LangsysApp.Translations.lookupContent(category, this.custom_id, token);
   }
+  /**
+   * Interpolate `{name}`-style params into a resolved text, matching `t()`:
+   * unknown keys fall through untouched, and the untranslated fallback is
+   * interpolated too. No-op when no params were supplied.
+   */
+  applyParams(text) {
+    const { params } = this.options;
+    if (isEmpty(params)) return text;
+    return interpolate(text, params, currentlyLoadedLocale.get());
+  }
   translateAttributes(element) {
     const tagName = element.tagName.toLowerCase();
     if (!element.originalAttributes) element.originalAttributes = {};
@@ -1374,12 +1396,12 @@ 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) {
           const translation = this.getTranslation(originalText);
-          option.textContent = translation || optionEl.originalAttributes["textContent"];
+          option.textContent = this.applyParams(translation || optionEl.originalAttributes["textContent"]);
         }
       });
     }
@@ -1388,13 +1410,13 @@ 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;
     const translation = this.getTranslation(originalValue);
-    if (translation) element.setAttribute(attr, translation);
-    else element.setAttribute(attr, element.originalAttributes[attr]);
+    if (translation) element.setAttribute(attr, this.applyParams(translation));
+    else element.setAttribute(attr, this.applyParams(element.originalAttributes[attr]));
   }
 };
 
@@ -1407,7 +1429,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 = "";
@@ -1546,6 +1568,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;