langsys-js-typescript 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 0.6.4 - 2026-08-16
+
+### Fixed
+
+- **A missing ICU argument no longer dumps the message source to the page.** `intl-messageformat` throws when an argument is absent, and the fallback ran the simple interpolator — whose pattern deliberately cannot match an ICU slot, so the entire construct passed through untouched. A phrase promoted to `{name_gender, select, …}` rendered as literal ICU source in front of users.
+
+  This is reachable with no caller mistake: langsys-ai's ICU promoter *introduces* a select argument the source phrase never had — a plain `{name}` becomes `{name_gender, select, …}` in gendered target locales. The application cannot supply `name_gender`; it doesn't exist in the phrase the developer wrote, and nothing tells them the target grew one. Every app translating into a gendered locale hits it.
+
+  Recovery, agreed with `langsys-php` so a shared catalog cannot render two different sentences for one input:
+
+  | slot | missing-argument behavior | outcome |
+  |---|---|---|
+  | `select` | take the `other` branch | a correct sentence — `other` is what an unknown gender should render |
+  | `plural` | take `other`, render `#` as `{argName}` | sentence survives with a visible gap; nothing can be inferred for a count |
+  | `{name}`, `{n, number}`, dates | render as `{argName}` | matches the simple path's rule that unknown keys stay visible |
+
+  The asymmetry is deliberate: `select` is genuinely recoverable, `plural` is only made less bad. Arguments that ARE supplied are untouched and recursed into, so a missing argument nested inside a satisfied branch still recovers. `plural`/`select` without an `other` branch is malformed ICU and is left alone, falling through to the simple path as before.
+
+  **A `null` argument counts as missing**, matching `langsys-php`. It doesn't throw — `intl-messageformat` coerces null to `0` — so `{count, plural, …}` rendered `0 items`. That is worse than it looks: a genuine `0` also renders `0 items`, so a bug and valid data became indistinguishable, in the output, in a screenshot, and in a bug report. A real `0` still renders `0 items`; only null and absent produce `{count} items`.
+
+  Found by `langsys-php` from a report against their SDK; both implementations had it, by different mechanisms. Verified against their shipped v1.3.1 behavior, including a nested case where an *unsatisfied* branch's missing argument correctly costs nothing (`{g, select, f {Ella} other {{n, plural …}}}` with `g='f'` renders `Ella`).
+
 ## 0.6.3 - 2026-08-16
 
 ### Fixed

package/dist/index.js

@@ -289,14 +289,76 @@ function warnUnmatchedParams(source, texts, params, context) {
 }
 function interpolate(template, params, locale) {
   if (isICU(template)) {
-    try {
-      return new intlMessageformat.IntlMessageFormat(template, locale || "en").format(params);
-    } catch {
-      return simpleInterpolate(template, params, locale);
+    const resolved = locale || "en";
+    const hasNullParam = !!params && Object.values(params).some((value) => value === null);
+    if (!hasNullParam) {
+      try {
+        return new intlMessageformat.IntlMessageFormat(template, resolved).format(params);
+      } catch {
+      }
+    }
+    {
+      try {
+        const ast = new intlMessageformat.IntlMessageFormat(template, resolved).ast;
+        if (!Array.isArray(ast)) return simpleInterpolate(template, params, locale);
+        const recovered = _recoverMissingArgs(JSON.parse(JSON.stringify(ast)), params);
+        return new intlMessageformat.IntlMessageFormat(recovered, resolved).format(params);
+      } catch {
+        return simpleInterpolate(template, params, locale);
+      }
     }
   }
   return simpleInterpolate(template, params, locale);
 }
+var ICU_LITERAL = 0;
+var ICU_ARGUMENT = 1;
+var ICU_NUMBER = 2;
+var ICU_DATE = 3;
+var ICU_TIME = 4;
+var ICU_SELECT = 5;
+var ICU_PLURAL = 6;
+var ICU_POUND = 7;
+var ICU_TAG = 8;
+function _recoverMissingArgs(nodes, params) {
+  const out = [];
+  for (const node of nodes) {
+    const name = node.value;
+    const value = name !== void 0 && name in params ? params[name] : void 0;
+    const supplied = value !== void 0 && value !== null;
+    if (node.type === ICU_TAG) {
+      out.push({ ...node, children: _recoverMissingArgs(node.children ?? [], params) });
+      continue;
+    }
+    if (node.type === ICU_SELECT || node.type === ICU_PLURAL) {
+      if (supplied) {
+        const options = {};
+        for (const [key, branch2] of Object.entries(node.options ?? {})) {
+          options[key] = { value: _recoverMissingArgs(branch2.value, params) };
+        }
+        out.push({ ...node, options });
+        continue;
+      }
+      const other = node.options?.other;
+      if (!other) {
+        out.push(node);
+        continue;
+      }
+      const branch = _recoverMissingArgs(other.value, params);
+      out.push(
+        ...branch.map(
+          (child) => child.type === ICU_POUND ? { type: ICU_LITERAL, value: `{${name}}` } : child
+        )
+      );
+      continue;
+    }
+    if (!supplied && (node.type === ICU_ARGUMENT || node.type === ICU_NUMBER || node.type === ICU_DATE || node.type === ICU_TIME)) {
+      out.push({ type: ICU_LITERAL, value: `{${name}}` });
+      continue;
+    }
+    out.push(node);
+  }
+  return out;
+}
 function simpleInterpolate(template, params, locale) {
   return template.replace(/\{([^{},]+)\}/g, (match, rawKey) => {
     const key = rawKey.trim();