langsys-js-typescript 0.6.4 → 0.6.5

package/CHANGELOG.md

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

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() {