langsys-js-typescript 0.4.0 → 0.4.2

package/dist/index.mjs

@@ -263,6 +263,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 {
@@ -1139,7 +1161,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__";
@@ -1169,7 +1191,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;
@@ -1184,24 +1206,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));
     });
   }
 }
@@ -1243,6 +1265,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 || "";
@@ -1254,6 +1278,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();
@@ -1287,6 +1312,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));
@@ -1342,7 +1368,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;
@@ -1360,6 +1386,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
@@ -1391,7 +1430,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) {
@@ -1405,7 +1444,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;
@@ -1424,7 +1463,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 = "";
@@ -1494,6 +1533,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 ?? {};
@@ -1507,7 +1548,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() {
@@ -1522,11 +1565,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;
@@ -1543,6 +1599,6 @@ var t = ((phrase, ...rest) => {
 });
 var tSignal = LangsysApp.Translations.tSignal;
 
-export { LangsysApp, LangsysAppAPI, Logger, PHRASE_MARKER_ATTR, Phrase, Translate, Translations, canonicalizeLocale, createSignal, currentlyLoadedLocale, encodeRichText, generateCustomId, getValue, interpolate, isContentBlockKnown, isEmpty, isICU, logger, markupTokenValues, md5, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };
+export { LangsysApp, LangsysAppAPI, Logger, PHRASE_MARKER_ATTR, Phrase, Translate, Translations, canonicalizeLocale, createSignal, currentlyLoadedLocale, encodeRichText, findUnusedParamKeys, generateCustomId, getValue, interpolate, isContentBlockKnown, isEmpty, isICU, logger, markupTokenValues, md5, normalizeMarkupPlaceholders, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map