langsys-js-typescript 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,4 +1,27 @@
-## 0.6.0 - unreleased
+## 0.6.2 - 2026-08-16
+
+### Added
+
+- **`data-notrans` is now honored as an alias for `translate="no"`.** `langsys-php` accepts it as an author-facing opt-out, for hosts whose templating strips unknown bare attributes or where `translate` collides with another tool — and it survives into `translatePage()` output. On SSR handoff there is one DOM, so content an author marked "do not translate" was being extracted and registered by whichever SDK walked it. Presence is intent; an explicit `"false"`/`"0"` opts out of the opt-out, compared after trimming. `translate="no"` is now matched case-insensitively too, also mirroring PHP.
+- **`isTranslationExcluded(element)`** — exported alongside `isPhraseMarked`, for wrappers that tokenize through their own templating rather than delegating to the DOM class.
+
+### Fixed
+
+- **Phrase-marker values are trimmed before comparison**, so `data-langsys-phrase=" false "` opts out like `="false"` does. This matched `langsys-php` at the time it shipped; auditing the difference showed the gap was drift — their exclusion check gained a trim their phrase check never did — and they normalized on their side, so both SDKs now trim in both places. `isPhraseMarked` is also the method name in both SDKs now, so the correspondence is checkable at a glance.
+
+### Notes
+
+- Asking `langsys-php` whether to mirror `data-notrans` rather than implementing against their code surfaced a bug on their side: their truthiness test was inverted at both ends — bare `data-notrans` did nothing, while `data-notrans="false"` excluded. Had this been implemented from their source as it stood, it would have faithfully reproduced that. Their fix landed first; this mirrors the corrected semantics.
+
+## 0.6.1 - 2026-08-15
+
+### Fixed
+
+- **`data-langsys-phrase="false"` / `="0"` are now honored as opt-outs.** 0.6.0 taught the tokenizer to skip subtrees carrying `langsys-php`'s keep-together marker, but matched on attribute presence alone. PHP's `hasPhraseAttribute()` treats presence as intent *while letting an explicit off value opt out* — so we skipped subtrees the author had deliberately un-marked, leaving that content translated by neither SDK. Matching is now value-aware and case-insensitive, mirroring PHP exactly.
+
+  Found by reading `HtmlParser.php` rather than trusting a summary of it — the same second-hand-documentation error this class of bug keeps producing.
+
+## 0.6.0 - 2026-08-15
 
 ### Fixed
 

package/dist/index.d.mts

@@ -628,7 +628,38 @@ interface iContentBlock {
  * additive — `data-langsys-phrase` never appears in DOM our components emit.
  */
 declare const PHRASE_MARKER_ATTRS: readonly ["data-ls-phrase", "data-langsys-phrase"];
-/** True when an element is marked as a self-managed phrase by either SDK. */
+/**
+ * True when an element opts out of translation entirely — it and its subtree
+ * are skipped by the tokenizer.
+ *
+ * Mirrors `langsys-php`'s `HtmlParser::isTranslationExcluded()` exactly:
+ *  - `translate="no"` — the HTML standard attribute, matched case-insensitively.
+ *  - `data-notrans` — PHP's author-facing alias, for hosts whose templating
+ *    strips unknown bare attributes or where `translate` collides with another
+ *    tool. Presence is intent; an explicit `"false"`/`"0"` opts out of the
+ *    opt-out, compared after trimming.
+ *
+ * Honoring PHP's alias matters for the same reason as the phrase marker: on SSR
+ * handoff there is ONE DOM, and content an author marked "do not translate"
+ * must not be extracted and registered by whichever SDK happens to walk it.
+ *
+ * Both this and `isPhraseMarked` trim before comparing. They briefly differed
+ * — PHP's phrase check predated the trim its exclusion check gained — and the
+ * gap was resolved by asking rather than tidying: mirror exactly, flag the
+ * wart, let the owner decide. Divergence-by-tidying is the same failure class
+ * as divergence-by-oversight, just better intentioned.
+ */
+declare function isTranslationExcluded(element: Element): boolean;
+/**
+ * True when an element is marked as a self-managed phrase by either SDK.
+ *
+ * Presence alone means intent, like any boolean HTML attribute — but an
+ * explicit `="false"` or `="0"` opts OUT, compared after trimming. Mirrors
+ * `langsys-php`'s `isPhraseMarked()` exactly (same method name in both SDKs,
+ * so the correspondence is checkable at a glance). Without the opt-out we
+ * would skip a subtree the author had deliberately un-marked, and it would
+ * then be translated by neither SDK.
+ */
 declare function isPhraseMarked(element: Element): boolean;
 /**
  * Compute the deterministic content-block id from a `(category, tokens)` pair.
@@ -845,4 +876,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, PHRASE_MARKER_ATTRS, 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, findUnusedParamKeys, generateCustomId, generateLegacyCustomId, 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, isPhraseMarked, logger, markupTokenValues, md5, md5Legacy, normalizeMarkupPlaceholders, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };
+export { type EncodedRichText, type ExtractParamKeys, LangsysApp, LangsysAppAPI, type LocaleSource, Logger, PHRASE_MARKER_ATTR, PHRASE_MARKER_ATTRS, 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, findUnusedParamKeys, generateCustomId, generateLegacyCustomId, 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, isPhraseMarked, isTranslationExcluded, logger, markupTokenValues, md5, md5Legacy, normalizeMarkupPlaceholders, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };

package/dist/index.d.ts

@@ -628,7 +628,38 @@ interface iContentBlock {
  * additive — `data-langsys-phrase` never appears in DOM our components emit.
  */
 declare const PHRASE_MARKER_ATTRS: readonly ["data-ls-phrase", "data-langsys-phrase"];
-/** True when an element is marked as a self-managed phrase by either SDK. */
+/**
+ * True when an element opts out of translation entirely — it and its subtree
+ * are skipped by the tokenizer.
+ *
+ * Mirrors `langsys-php`'s `HtmlParser::isTranslationExcluded()` exactly:
+ *  - `translate="no"` — the HTML standard attribute, matched case-insensitively.
+ *  - `data-notrans` — PHP's author-facing alias, for hosts whose templating
+ *    strips unknown bare attributes or where `translate` collides with another
+ *    tool. Presence is intent; an explicit `"false"`/`"0"` opts out of the
+ *    opt-out, compared after trimming.
+ *
+ * Honoring PHP's alias matters for the same reason as the phrase marker: on SSR
+ * handoff there is ONE DOM, and content an author marked "do not translate"
+ * must not be extracted and registered by whichever SDK happens to walk it.
+ *
+ * Both this and `isPhraseMarked` trim before comparing. They briefly differed
+ * — PHP's phrase check predated the trim its exclusion check gained — and the
+ * gap was resolved by asking rather than tidying: mirror exactly, flag the
+ * wart, let the owner decide. Divergence-by-tidying is the same failure class
+ * as divergence-by-oversight, just better intentioned.
+ */
+declare function isTranslationExcluded(element: Element): boolean;
+/**
+ * True when an element is marked as a self-managed phrase by either SDK.
+ *
+ * Presence alone means intent, like any boolean HTML attribute — but an
+ * explicit `="false"` or `="0"` opts OUT, compared after trimming. Mirrors
+ * `langsys-php`'s `isPhraseMarked()` exactly (same method name in both SDKs,
+ * so the correspondence is checkable at a glance). Without the opt-out we
+ * would skip a subtree the author had deliberately un-marked, and it would
+ * then be translated by neither SDK.
+ */
 declare function isPhraseMarked(element: Element): boolean;
 /**
  * Compute the deterministic content-block id from a `(category, tokens)` pair.
@@ -845,4 +876,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, PHRASE_MARKER_ATTRS, 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, findUnusedParamKeys, generateCustomId, generateLegacyCustomId, 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, isPhraseMarked, logger, markupTokenValues, md5, md5Legacy, normalizeMarkupPlaceholders, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };
+export { type EncodedRichText, type ExtractParamKeys, LangsysApp, LangsysAppAPI, type LocaleSource, Logger, PHRASE_MARKER_ATTR, PHRASE_MARKER_ATTRS, 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, findUnusedParamKeys, generateCustomId, generateLegacyCustomId, 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, isPhraseMarked, isTranslationExcluded, logger, markupTokenValues, md5, md5Legacy, normalizeMarkupPlaceholders, persist, reconstitute, registerContentBlock, sTranslations, stripSentinels, t, tSignal, tokenizeElement };

package/dist/index.js

@@ -1086,8 +1086,18 @@ var TRANSLATABLE_ATTRIBUTES = [
   "data-pattern-message"
 ];
 var PHRASE_MARKER_ATTRS = ["data-ls-phrase", "data-langsys-phrase"];
+function isTranslationExcluded(element) {
+  if ((element.getAttribute("translate") ?? "").toLowerCase() === "no") return true;
+  if (!element.hasAttribute("data-notrans")) return false;
+  const value = (element.getAttribute("data-notrans") ?? "").trim().toLowerCase();
+  return value !== "false" && value !== "0";
+}
 function isPhraseMarked(element) {
-  return PHRASE_MARKER_ATTRS.some((attr) => element.hasAttribute(attr));
+  return PHRASE_MARKER_ATTRS.some((attr) => {
+    if (!element.hasAttribute(attr)) return false;
+    const value = (element.getAttribute(attr) ?? "").trim().toLowerCase();
+    return value !== "false" && value !== "0";
+  });
 }
 var VALUE_TRANSLATABLE_ELEMENTS = ["button"];
 var VALUE_TRANSLATABLE_INPUT_TYPES = ["submit", "button"];
@@ -1204,7 +1214,7 @@ function _walkForTokens(liveRoot, cloneNodes, tokens, indices) {
   cloneNodes.forEach((node, index) => {
     if (node.nodeType === Node.ELEMENT_NODE) {
       const el = node;
-      if (el.getAttribute("translate") === "no") return;
+      if (isTranslationExcluded(el)) return;
       if (isPhraseMarked(el)) return;
     }
     if (node.hasChildNodes()) {
@@ -1393,7 +1403,7 @@ var Translate = class {
     nodes.forEach((node) => {
       if (node?.nodeType === Node.ELEMENT_NODE) {
         const element = node;
-        if (element.getAttribute("translate") === "no") return;
+        if (isTranslationExcluded(element)) return;
         if (isPhraseMarked(element)) return;
         this.translateAttributes(node);
       }
@@ -1656,6 +1666,7 @@ exports.isContentBlockKnown = isContentBlockKnown;
 exports.isEmpty = isEmpty;
 exports.isICU = isICU;
 exports.isPhraseMarked = isPhraseMarked;
+exports.isTranslationExcluded = isTranslationExcluded;
 exports.logger = logger;
 exports.markupTokenValues = markupTokenValues;
 exports.md5 = md5;