langsys-js-typescript 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+## 0.6.5 - 2026-08-16
+
+### Added
+
+- **Debug warning when a locale tag is not valid BCP 47.** `canonicalizeLocale` falls back to best-effort casing rather than throwing, which is the right behavior — but the return value cannot signal that it happened: a best-effort string is indistinguishable from a successfully canonicalized one. So a typo'd config locale degrades to a silent failed catalog lookup, and the app renders base language, which is exactly what a legitimately-untranslated locale looks like. Nothing downstream can tell the difference, so the warning is emitted where the information still exists. Behavior and return values are unchanged; silent in production.
+
+  Found by applying a predictive form of a pattern this release series kept hitting, contributed by the Svelte binding: **look for any fallback whose output is drawn from the same value space as its success output.** That makes the class searchable by inspection rather than discoverable by tripping over it — null-as-zero, empty-string-as-absent, best-effort-locale-as-canonical.
+
+## 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/README.md

@@ -1,10 +1,17 @@
 # Langsys SDK — TypeScript
 
-Framework-agnostic TypeScript SDK for the [Langsys](https://Langsys.dev/) Translation Manager. Realtime, continuous translations with automatic token discovery — no framework required.
+[![npm](https://img.shields.io/npm/v/langsys-js-typescript.svg?style=flat)](https://www.npmjs.com/package/langsys-js-typescript)
+[![build](https://img.shields.io/github/actions/workflow/status/langsys/langsys-js-typescript/ci.yml?style=flat)](https://github.com/langsys/langsys-js-typescript/actions)
+[![last commit](https://img.shields.io/github/last-commit/langsys/langsys-js-typescript.svg?style=flat)](https://github.com/langsys/langsys-js-typescript/commits)
+[![commit activity](https://img.shields.io/github/commit-activity/m/langsys/langsys-js-typescript.svg?style=flat)](https://github.com/langsys/langsys-js-typescript/pulse)
+[![bundle size](https://img.shields.io/bundlejs/size/langsys-js-typescript?style=flat)](https://bundlejs.com/?q=langsys-js-typescript)
+[![types](https://img.shields.io/npm/types/langsys-js-typescript.svg?style=flat)](https://www.npmjs.com/package/langsys-js-typescript)
+[![downloads](https://img.shields.io/npm/dm/langsys-js-typescript.svg?style=flat)](https://www.npmjs.com/package/langsys-js-typescript)
+[![license](https://img.shields.io/npm/l/langsys-js-typescript.svg?style=flat)](./LICENSE)
 
-This is the base SDK. Framework-specific bindings (`langsys-js-svelte`, and similar packages for React / Vue / Solid that can be built on top of this) are thin wrappers that add idiomatic framework reactivity around the same core.
+Framework-agnostic TypeScript SDK for the [Langsys](https://Langsys.dev/) Translation Manager. Realtime, continuous translations with automatic token discovery — no framework required.
 
-[![NPM License](https://img.shields.io/npm/l/all-contributors.svg?style=flat)](./LICENSE)
+This is the base SDK. Framework-specific bindings (`langsys-js-svelte`, `langsys-js-react`, `langsys-js-vue`) are thin wrappers that add idiomatic framework reactivity around the same core.
 
 ## What's inside
 
@@ -14,7 +21,7 @@ This is the base SDK. Framework-specific bindings (`langsys-js-svelte`, and simi
 - `Translate` class — wraps a DOM element, walks text + translatable attributes, registers a content block with the Translation Manager, re-translates on locale change.
 - `Signal<T>` — tiny subscribe/set/update/get primitive. Compatible with Svelte's store contract by design, so the Svelte binding is nearly trivial.
 - `LangsysAppAPI` — direct HTTP access if you want to bypass everything else.
-- Zero runtime dependencies. Works in browsers, Node, any bundler.
+- One runtime dependency (`intl-messageformat`, for ICU plurals and gender selects). ~20 kB gzipped. Works in browsers, Node, any bundler.
 
 ## Install
 
@@ -161,11 +168,22 @@ handle.destroy();
 
 Attributes honored on contained elements:
 
-- `placeholder`, `alt`, `title`, `aria-label`, `aria-placeholder`
-- `value` on `<button>`, `<input type="submit">`, `<input type="button">`
+**Visible text**
+
+- `placeholder`, `alt`, `title`, `label`
+- `value` on `<button>`, `<input type="submit">`, `<input type="button">` — and *only* those; a text input's value is never rewritten
 - `<option>` text inside `<select>`
-- Several validation-message `data-*` attributes
-- `translate="no"` — elements marked this way (and their children) are skipped
+
+**Screen-reader text** — `aria-label`, `aria-placeholder`, `aria-description`, `aria-valuetext`, `aria-roledescription`
+
+> Leaving these untranslated has **no visible symptom**. Nothing on the page changes, so reviewing the rendered output cannot catch it — the failure is audible only to the users least able to work around it.
+
+**Validation messages** — `data-error`, `data-error-message`, `data-validation-message`, `data-invalid-message`, `data-required-message`, `data-pattern-message`
+
+**Opting out**
+
+- `translate="no"` (case-insensitive), or `data-notrans` — `langsys-php`'s author-facing alias, honored here so an SSR-rendered page opts out consistently in both SDKs. Presence means intent; an explicit `="false"` or `="0"` opts back in.
+- Elements marked this way, and their children, are skipped entirely.
 
 > **`Translate` tokenizes per text node — so inline markup splits a sentence.**
 >

package/dist/index.js

@@ -2,6 +2,37 @@
 
 var intlMessageformat = require('intl-messageformat');
 
+// src/logger.ts
+var STYLES = {
+  log: "display:inline-block;background:rgb(239,239,244);color:black;font-weight:bold;padding:3px 7px;border-radius:3px",
+  warn: "display:inline-block;background:gold;color:black;font-weight:bold;padding:3px 7px;border-radius:3px",
+  error: "display:inline-block;background:#e0005a;color:#fff;font-weight:bold;padding:3px 7px;border-radius:3px"
+};
+var supportsStyle = typeof window !== "undefined";
+function emit(level, label, args) {
+  if (supportsStyle) {
+    console[level](`%c${label}`, STYLES[level], ...args);
+  } else {
+    console[level](`[${label}]`, ...args);
+  }
+}
+var Logger = class {
+  constructor(debugEnabled = false) {
+    this.debugEnabled = debugEnabled;
+  }
+  log(...args) {
+    if (!this.debugEnabled) return;
+    emit("log", "Langsys Debug", args);
+  }
+  warn(...args) {
+    emit("warn", "Langsys Warning", args);
+  }
+  error(...args) {
+    emit("error", "Langsys Error", args);
+  }
+};
+var logger = new Logger(false);
+
 // src/locale.ts
 function canonicalizeLocale(locale) {
   if (!locale || typeof locale !== "string") return locale;
@@ -10,6 +41,9 @@ function canonicalizeLocale(locale) {
     const [canonical] = Intl.getCanonicalLocales(cleaned);
     return canonical ?? cleaned;
   } catch {
+    if (logger.debugEnabled) logger.warn(
+      `"${locale}" is not a valid BCP 47 locale tag. Falling back to best-effort casing, which will very likely miss the catalog and render base language with no other symptom.`
+    );
     return cleaned.split("-").map((part, i) => {
       if (i === 0) return part.toLowerCase();
       if (part.length === 4) return part[0].toUpperCase() + part.slice(1).toLowerCase();
@@ -53,37 +87,6 @@ function getValue(signal) {
   return signal.get();
 }
 
-// src/logger.ts
-var STYLES = {
-  log: "display:inline-block;background:rgb(239,239,244);color:black;font-weight:bold;padding:3px 7px;border-radius:3px",
-  warn: "display:inline-block;background:gold;color:black;font-weight:bold;padding:3px 7px;border-radius:3px",
-  error: "display:inline-block;background:#e0005a;color:#fff;font-weight:bold;padding:3px 7px;border-radius:3px"
-};
-var supportsStyle = typeof window !== "undefined";
-function emit(level, label, args) {
-  if (supportsStyle) {
-    console[level](`%c${label}`, STYLES[level], ...args);
-  } else {
-    console[level](`[${label}]`, ...args);
-  }
-}
-var Logger = class {
-  constructor(debugEnabled = false) {
-    this.debugEnabled = debugEnabled;
-  }
-  log(...args) {
-    if (!this.debugEnabled) return;
-    emit("log", "Langsys Debug", args);
-  }
-  warn(...args) {
-    emit("warn", "Langsys Warning", args);
-  }
-  error(...args) {
-    emit("error", "Langsys Error", args);
-  }
-};
-var logger = new Logger(false);
-
 // src/api.ts
 var LangsysAppAPIClass = class {
   constructor() {
@@ -289,14 +292,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();