translate-shield 0.1.0

package/dist/index.js

@@ -0,0 +1,505 @@
+import { i as isText, a as isElement, b as isTranslatorWrapper, e as engineOfWrapper } from './dom-crorgc8a.js';
+
+const NATIVE = /\[native code\]/;
+const isPatched = (candidate)=>typeof candidate === 'function' && !NATIVE.test(Function.prototype.toString.call(candidate));
+const setterOf = (target, property)=>Object.getOwnPropertyDescriptor(target, property)?.set;
+/**
+ * Names the DOM surfaces another shim has already replaced.
+ *
+ * Two shims on one page is not a crash, it is a silent draw. Ours writes the new
+ * value into the translator's wrapper; a restore-based shim puts the original
+ * node back and deletes that wrapper. Whichever runs second decides, and the
+ * loser degrades to doing nothing. Reporting it is the only way a developer
+ * finds out, because nothing throws.
+ */ const findConflicts = ()=>{
+    if (typeof Node === 'undefined') return [];
+    const surfaces = [
+        [
+            'Node.prototype.removeChild',
+            Node.prototype.removeChild
+        ],
+        [
+            'Node.prototype.insertBefore',
+            Node.prototype.insertBefore
+        ],
+        [
+            'Node.prototype.replaceChild',
+            Node.prototype.replaceChild
+        ],
+        [
+            'Node.prototype.nodeValue',
+            setterOf(Node.prototype, 'nodeValue')
+        ],
+        [
+            'Node.prototype.textContent',
+            setterOf(Node.prototype, 'textContent')
+        ],
+        [
+            'CharacterData.prototype.data',
+            setterOf(CharacterData.prototype, 'data')
+        ],
+        [
+            'Element.prototype.attachShadow',
+            Element.prototype.attachShadow
+        ]
+    ];
+    return surfaces.filter(([, value])=>isPatched(value)).map(([name])=>name);
+};
+
+const NUMBER_PATTERN = /\d+(?:[.,\s]\d+)*/g;
+const TRANSLATED_NUMBER_PATTERN = /\p{Nd}+(?:[.,\s]\p{Nd}+)*/gu;
+const DIGIT_ZEROS = [
+    0x0030,
+    0x0660,
+    0x06f0,
+    0x0966,
+    0x09e6,
+    0x0a66,
+    0x0ae6,
+    0x0b66,
+    0x0be6,
+    0x0c66,
+    0x0ce6,
+    0x0d66,
+    0x0e50,
+    0x0ed0,
+    0x0f20,
+    0x1040,
+    0x17e0,
+    0x1810,
+    0xff10
+];
+const numbersOf = (value)=>value.match(NUMBER_PATTERN) ?? [];
+const skeletonOf = (value)=>value.replace(NUMBER_PATTERN, '');
+const digitsOf = (value)=>value.replace(/\D/g, '');
+const zeroCodePointFor = (codePoint)=>{
+    for (const zero of DIGIT_ZEROS){
+        if (codePoint >= zero && codePoint <= zero + 9) return zero;
+    }
+    return null;
+};
+const asNumber = (value)=>{
+    const digits = digitsOf(value);
+    if (!digits) return null;
+    const fraction = value.match(/[.,](\d{1,2})$/)?.[1];
+    if (!fraction) return Number(digits);
+    const whole = digits.slice(0, digits.length - fraction.length);
+    return Number(`${whole || '0'}.${fraction}`);
+};
+/**
+ * True when swapping one value for another cannot change the grammatical number
+ * of the sentence. Russian "4 lampochki" (few) and "7 lampochek" (many) take
+ * different noun forms, so a digit swap there produces fluent-looking wrong text.
+ */ const ruleCache = new Map();
+const pluralRulesFor = (locale)=>{
+    const cached = ruleCache.get(locale);
+    if (cached !== undefined) return cached;
+    let rules = null;
+    try {
+        rules = new Intl.PluralRules(locale);
+    } catch  {
+        rules = null;
+    }
+    ruleCache.set(locale, rules);
+    return rules;
+};
+const keepsPluralCategory = (previous, next, locale)=>{
+    if (!locale) return false;
+    const rules = pluralRulesFor(locale);
+    if (!rules) return false;
+    return previous.every((value, index)=>{
+        const before = asNumber(value);
+        const after = asNumber(next[index] ?? '');
+        if (before === null || after === null) return false;
+        return rules.select(before) === rules.select(after);
+    });
+};
+/**
+ * Writes new digits into a number the translator already formatted, keeping that
+ * number's own separators and digit system, so "19,99" updated from "29.99"
+ * becomes "29,99" rather than "29.99".
+ */ const reskinNumber = (translatedNumber, sourceDigits)=>{
+    const characters = Array.from(translatedNumber);
+    const digitCount = characters.filter((character)=>zeroCodePointFor(character.codePointAt(0) ?? 0) !== null).length;
+    if (digitCount !== sourceDigits.length) return null;
+    let index = 0;
+    return characters.map((character)=>{
+        const zero = zeroCodePointFor(character.codePointAt(0) ?? 0);
+        if (zero === null) return character;
+        const digit = Number(sourceDigits[index] ?? '0');
+        index += 1;
+        return String.fromCodePoint(zero + digit);
+    }).join('');
+};
+/**
+ * Merges a new source value into an already translated string. The merge only
+ * happens when it cannot change meaning: the sentence around the numbers is
+ * identical, every number keeps its plural category in the target language, and
+ * the digits line up one for one. Otherwise the correct value is returned in the
+ * source language, because a visibly untranslated number beats a fluent-looking
+ * wrong one.
+ */ const mergeIntoTranslated = (previousSource, nextSource, translated, locale)=>{
+    if (!translated) return nextSource;
+    if (previousSource === nextSource) return translated;
+    if (skeletonOf(previousSource) !== skeletonOf(nextSource)) return nextSource;
+    const previousNumbers = numbersOf(previousSource);
+    const nextNumbers = numbersOf(nextSource);
+    if (previousNumbers.length !== nextNumbers.length) return nextSource;
+    if (!keepsPluralCategory(previousNumbers, nextNumbers, locale)) return nextSource;
+    const translatedNumbers = translated.match(TRANSLATED_NUMBER_PATTERN) ?? [];
+    if (translatedNumbers.length !== nextNumbers.length) return nextSource;
+    const replacements = translatedNumbers.map((translatedNumber, index)=>reskinNumber(translatedNumber, digitsOf(nextNumbers[index] ?? '')));
+    if (replacements.includes(null)) return nextSource;
+    let cursor = 0;
+    return translated.replace(TRANSLATED_NUMBER_PATTERN, (match)=>{
+        const replacement = replacements[cursor];
+        cursor += 1;
+        return replacement ?? match;
+    });
+};
+
+const INTERCEPTED_PROPERTIES = [
+    'nodeValue',
+    'data',
+    'textContent'
+];
+let links = new WeakMap();
+let wrappers = new WeakSet();
+let forwarders = null;
+let natives = null;
+const nativeDescriptorOf = (property)=>{
+    if (property === 'data') return Object.getOwnPropertyDescriptor(CharacterData.prototype, 'data');
+    return Object.getOwnPropertyDescriptor(Node.prototype, property);
+};
+/**
+ * Resolves the native accessors once, on first use rather than at module scope.
+ * Reading `Node.prototype` when the module loads throws `ReferenceError: Node is
+ * not defined` on the server, which would break any app importing this from
+ * shared code, so nothing here may run before a DOM exists.
+ */ const nativeAccessors = ()=>{
+    if (natives) return natives;
+    if (typeof Node === 'undefined') return null;
+    natives = {
+        nodeValue: nativeDescriptorOf('nodeValue'),
+        data: nativeDescriptorOf('data'),
+        textContent: nativeDescriptorOf('textContent')
+    };
+    return natives;
+};
+const readProperty = (node, property)=>{
+    const getter = nativeAccessors()?.[property]?.get;
+    if (!getter) return '';
+    return String(getter.call(node) ?? '');
+};
+const forwardWrite = (node, next)=>{
+    const link = links.get(node);
+    if (!link?.wrapper.isConnected) return;
+    const translated = readProperty(link.wrapper, 'textContent');
+    const merged = mergeIntoTranslated(link.sourceText, next, translated, document.documentElement.lang);
+    link.sourceText = next;
+    if (merged === translated) return;
+    nativeAccessors()?.textContent?.set?.call(link.wrapper, merged);
+};
+/**
+ * Builds the forwarding accessors once per property. They close over nothing
+ * per node, so a full-page translation linking thousands of text nodes reuses
+ * three descriptors instead of allocating nine objects for each one.
+ */ const forwardingDescriptors = ()=>{
+    if (forwarders) return forwarders;
+    const accessors = nativeAccessors();
+    if (!accessors) return null;
+    const build = (property)=>{
+        const native = accessors[property];
+        if (!native?.get || !native.set) return null;
+        const nativeGet = native.get;
+        const nativeSet = native.set;
+        return {
+            configurable: true,
+            enumerable: false,
+            get () {
+                return nativeGet.call(this);
+            },
+            set (value) {
+                nativeSet.call(this, value);
+                forwardWrite(this, String(value ?? ''));
+            }
+        };
+    };
+    const nodeValue = build('nodeValue');
+    const data = build('data');
+    const textContent = build('textContent');
+    if (!nodeValue || !data || !textContent) return null;
+    forwarders = {
+        nodeValue,
+        data,
+        textContent
+    };
+    return forwarders;
+};
+/**
+ * Links a TextNode the translator detached to the element that replaced it, so
+ * later framework writes reach the node the user actually sees.
+ */ const linkNodes = (detached, wrapper)=>{
+    wrappers.add(wrapper);
+    const existing = links.get(detached);
+    if (existing) {
+        existing.wrapper = wrapper;
+        return;
+    }
+    links.set(detached, {
+        wrapper,
+        sourceText: readProperty(detached, 'nodeValue')
+    });
+    const descriptors = forwardingDescriptors();
+    if (!descriptors) return;
+    INTERCEPTED_PROPERTIES.forEach((property)=>{
+        Object.defineProperty(detached, property, descriptors[property]);
+    });
+};
+const wrapperFor = (node)=>{
+    if (!isText(node)) return null;
+    const link = links.get(node);
+    if (!link?.wrapper.isConnected) return null;
+    return link.wrapper;
+};
+const isWrapper = (node)=>isElement(node) && wrappers.has(node);
+/**
+ * Drops every link, which turns each intercepted accessor into a pass-through:
+ * the getter still delegates to the native one and the setter forwards nowhere.
+ * The own properties stay defined, because deleting them would need a list of
+ * every node ever linked, and that list grows for the lifetime of a page that
+ * keeps translating.
+ */ const releaseInterceptors = ()=>{
+    links = new WeakMap();
+    wrappers = new WeakSet();
+    forwarders = null;
+};
+
+/**
+ * Makes the three DOM calls that take a child reference survive nodes a
+ * translator detached. Real children take the native path untouched; detached
+ * ones are redirected to the visible wrapper instead of throwing NotFoundError.
+ *
+ * `appendChild` is deliberately not patched. It takes no reference child, so it
+ * cannot raise the NotFoundError this repairs; wrapping it would cost every
+ * insertion on the page and buy nothing.
+ */ const patchDom = (report)=>{
+    const nativeRemoveChild = Node.prototype.removeChild;
+    const nativeInsertBefore = Node.prototype.insertBefore;
+    const nativeReplaceChild = Node.prototype.replaceChild;
+    Node.prototype.removeChild = function removeChild(child) {
+        if (child.parentNode === this) {
+            nativeRemoveChild.call(this, child);
+            return child;
+        }
+        const wrapper = wrapperFor(child);
+        if (wrapper && wrapper.parentNode === this) {
+            nativeRemoveChild.call(this, wrapper);
+            report({
+                method: 'removeChild',
+                redirected: true
+            });
+            return child;
+        }
+        report({
+            method: 'removeChild',
+            redirected: false
+        });
+        return child;
+    };
+    Node.prototype.insertBefore = function insertBefore(node, reference) {
+        if (!reference || reference.parentNode === this) {
+            nativeInsertBefore.call(this, node, reference);
+            return node;
+        }
+        const wrapper = wrapperFor(reference);
+        if (wrapper && wrapper.parentNode === this) {
+            nativeInsertBefore.call(this, node, wrapper);
+            report({
+                method: 'insertBefore',
+                redirected: true
+            });
+            return node;
+        }
+        nativeInsertBefore.call(this, node, null);
+        report({
+            method: 'insertBefore',
+            redirected: false
+        });
+        return node;
+    };
+    Node.prototype.replaceChild = function replaceChild(node, child) {
+        if (child.parentNode === this) {
+            nativeReplaceChild.call(this, node, child);
+            return child;
+        }
+        const wrapper = wrapperFor(child);
+        if (wrapper && wrapper.parentNode === this) {
+            nativeReplaceChild.call(this, node, wrapper);
+            report({
+                method: 'replaceChild',
+                redirected: true
+            });
+            return child;
+        }
+        report({
+            method: 'replaceChild',
+            redirected: false
+        });
+        return child;
+    };
+    return ()=>{
+        Node.prototype.removeChild = nativeRemoveChild;
+        Node.prototype.insertBefore = nativeInsertBefore;
+        Node.prototype.replaceChild = nativeReplaceChild;
+    };
+};
+
+const OBSERVE_OPTIONS = {
+    childList: true,
+    subtree: true
+};
+const pushInto = (bucket, key, value)=>{
+    const existing = bucket.get(key);
+    if (!existing) {
+        bucket.set(key, [
+            value
+        ]);
+        return;
+    }
+    existing.push(value);
+};
+/**
+ * Watches for the translator's TextNode-to-wrapper swap and links each pair.
+ * Pairing is positional per parent: within one observer batch the n-th injected
+ * wrapper belongs to the n-th detached TextNode of that parent.
+ *
+ * Open shadow roots are observed too. Chrome and Yandex translate through the
+ * boundary and detach the nodes inside it, and a `MutationObserver` on a host
+ * element never reports what happens in its shadow root. `attachShadow` is
+ * wrapped so roots opened after install are picked up as well: attaching a
+ * shadow root produces no mutation record, so there is nothing else to watch.
+ */ const startObserver = ({ root, wrapperTags, onTranslationDetected })=>{
+    let detected = false;
+    const observedRoots = new WeakSet();
+    const observer = new MutationObserver((records)=>{
+        const detachedTexts = new Map();
+        const injectedWrappers = new Map();
+        records.forEach((record)=>{
+            if (isWrapper(record.target)) return;
+            record.removedNodes.forEach((node)=>{
+                if (isText(node)) pushInto(detachedTexts, record.target, node);
+            });
+            record.addedNodes.forEach((node)=>{
+                if (isTranslatorWrapper(node, wrapperTags)) {
+                    pushInto(injectedWrappers, record.target, node);
+                    return;
+                }
+                if (isElement(node)) observeShadowRootsUnder(node);
+            });
+        });
+        if (injectedWrappers.size === 0) return;
+        injectedWrappers.forEach((elements, parent)=>{
+            const texts = detachedTexts.get(parent) ?? [];
+            elements.forEach((wrapper, index)=>{
+                const detachedText = texts[index];
+                if (!detachedText) return;
+                linkNodes(detachedText, wrapper);
+            });
+        });
+        if (detected) return;
+        detected = true;
+        const [firstBatch] = injectedWrappers.values();
+        const wrapper = firstBatch?.[0];
+        onTranslationDetected({
+            lang: document.documentElement.lang,
+            engine: wrapper ? engineOfWrapper(wrapper) : null,
+            wrapperTag: wrapper?.tagName ?? ''
+        });
+    });
+    function observeRoot(node) {
+        if (observedRoots.has(node)) return;
+        observedRoots.add(node);
+        observer.observe(node, OBSERVE_OPTIONS);
+    }
+    function observeShadowRootsUnder(scope) {
+        const hosts = isElement(scope) ? [
+            scope,
+            ...scope.querySelectorAll('*')
+        ] : scope.querySelectorAll('*');
+        hosts.forEach((host)=>{
+            if (!host.shadowRoot) return;
+            observeRoot(host.shadowRoot);
+            observeShadowRootsUnder(host.shadowRoot);
+        });
+    }
+    const nativeAttachShadow = Element.prototype.attachShadow;
+    Element.prototype.attachShadow = function attachShadow(init) {
+        const shadow = nativeAttachShadow.call(this, init);
+        if (init.mode === 'open' && root.contains(this)) observeRoot(shadow);
+        return shadow;
+    };
+    observeRoot(root);
+    observeShadowRootsUnder(root);
+    return ()=>{
+        Element.prototype.attachShadow = nativeAttachShadow;
+        observer.disconnect();
+    };
+};
+
+const inertHandle = {
+    stop: ()=>undefined,
+    isTranslated: ()=>false,
+    engine: ()=>null,
+    conflicts: ()=>[]
+};
+let activeHandle = null;
+/**
+ * Installs the shield: keeps the DOM operations React relies on from throwing
+ * once a translator has rewritten the page, and mirrors framework text updates
+ * into the elements the user actually sees.
+ */ const initTranslateShield = (options = {})=>{
+    if (typeof document === 'undefined') return inertHandle;
+    if (activeHandle) return activeHandle;
+    const { root = document.body || document.documentElement, wrapperTags = [], debug = false } = options;
+    if (!root) return inertHandle;
+    let translation = null;
+    const conflicts = findConflicts();
+    if (conflicts.length > 0) {
+        options.onConflict?.(conflicts);
+        console.warn(`[translate-shield] another shim already replaced ${conflicts.join(', ')}. Both will run, but only one repair strategy can win and the other silently does nothing. Install one.`);
+    }
+    const report = (error)=>{
+        options.onRecoveredError?.(error);
+        if (!debug) return;
+        console.warn('[translate-shield] recovered', error.method, {
+            redirected: error.redirected
+        });
+    };
+    const handleTranslationDetected = (info)=>{
+        translation = info;
+        options.onTranslationDetected?.(info);
+        if (!debug) return;
+        console.warn('[translate-shield] translation detected', info);
+    };
+    const restoreDom = patchDom(report);
+    const stopObserver = startObserver({
+        root,
+        wrapperTags,
+        onTranslationDetected: handleTranslationDetected
+    });
+    activeHandle = {
+        stop: ()=>{
+            stopObserver();
+            restoreDom();
+            releaseInterceptors();
+            activeHandle = null;
+        },
+        isTranslated: ()=>translation !== null,
+        engine: ()=>translation?.engine ?? null,
+        conflicts: ()=>conflicts
+    };
+    return activeHandle;
+};
+
+export { initTranslateShield, mergeIntoTranslated };

package/dist/react.cjs

@@ -0,0 +1,78 @@
+'use client';
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+var dom = require('./dom-dauvp8pk.cjs');
+
+/**
+ * Marks a value the browser translator must leave alone.
+ *
+ * Prices, counters, order numbers and codes do not need translating, and every
+ * engine measured — Chrome, Edge, Firefox, Yandex and the Google bundle —
+ * honours both `translate="no"` and `.notranslate`. Because the translator never
+ * touches the node, the framework can keep updating it: no crash, no frozen
+ * value, and no risk of a merged number breaking the grammar of a sentence.
+ *
+ * Wrap the value, never the whole sentence, or the reader loses the translation.
+ */ const NoTranslate = ({ children, as: Tag = 'span', className })=>/*#__PURE__*/ jsxRuntime.jsx(Tag, {
+        translate: "no",
+        className: className ? `notranslate ${className}` : 'notranslate',
+        children: children
+    });
+
+/**
+ * Reports when a translator starts working on the document, without patching
+ * anything. Apps that only want to warn the user, or to switch a formatter, can
+ * use this on its own; the shield uses the heavier observer instead.
+ */ const observeTranslation = (onDetected)=>{
+    if (typeof document === 'undefined') return ()=>undefined;
+    const detectAndReport = ()=>{
+        const engine = dom.detectEngine(document);
+        if (!engine) return false;
+        onDetected({
+            lang: document.documentElement.lang,
+            engine,
+            wrapperTag: ''
+        });
+        return true;
+    };
+    if (detectAndReport()) return ()=>undefined;
+    const observer = new MutationObserver(()=>{
+        if (detectAndReport()) observer.disconnect();
+    });
+    observer.observe(document.documentElement, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: [
+            'lang',
+            ...dom.MARKER_ATTRIBUTES
+        ]
+    });
+    return ()=>observer.disconnect();
+};
+
+const IDLE = {
+    isTranslated: false,
+    engine: null,
+    lang: ''
+};
+/**
+ * Tells a component whether the page is being machine translated, and by which
+ * engine. Always reports the idle state on the server and on the first client
+ * render, so it cannot cause a hydration mismatch.
+ */ const useTranslationDetected = ()=>{
+    const [state, setState] = react.useState(IDLE);
+    react.useEffect(()=>observeTranslation((info)=>{
+            setState({
+                isTranslated: true,
+                engine: info.engine,
+                lang: info.lang
+            });
+        }), []);
+    return state;
+};
+
+exports.NoTranslate = NoTranslate;
+exports.useTranslationDetected = useTranslationDetected;

package/dist/react.d.cts

@@ -0,0 +1,37 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { TranslatorEngine } from './index.cjs';
+
+type NoTranslateTag = 'span' | 'div' | 'p' | 'td' | 'strong' | 'output' | 'bdi';
+interface NoTranslateProps {
+    children: ReactNode;
+    as?: NoTranslateTag;
+    className?: string;
+}
+/**
+ * Marks a value the browser translator must leave alone.
+ *
+ * Prices, counters, order numbers and codes do not need translating, and every
+ * engine measured — Chrome, Edge, Firefox, Yandex and the Google bundle —
+ * honours both `translate="no"` and `.notranslate`. Because the translator never
+ * touches the node, the framework can keep updating it: no crash, no frozen
+ * value, and no risk of a merged number breaking the grammar of a sentence.
+ *
+ * Wrap the value, never the whole sentence, or the reader loses the translation.
+ */
+declare const NoTranslate: ({ children, as: Tag, className }: NoTranslateProps) => react.JSX.Element;
+
+interface TranslationState {
+    isTranslated: boolean;
+    engine: TranslatorEngine | null;
+    lang: string;
+}
+/**
+ * Tells a component whether the page is being machine translated, and by which
+ * engine. Always reports the idle state on the server and on the first client
+ * render, so it cannot cause a hydration mismatch.
+ */
+declare const useTranslationDetected: () => TranslationState;
+
+export { NoTranslate, useTranslationDetected };
+export type { NoTranslateProps, TranslationState };

package/dist/react.d.ts

@@ -0,0 +1,37 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { TranslatorEngine } from './index.js';
+
+type NoTranslateTag = 'span' | 'div' | 'p' | 'td' | 'strong' | 'output' | 'bdi';
+interface NoTranslateProps {
+    children: ReactNode;
+    as?: NoTranslateTag;
+    className?: string;
+}
+/**
+ * Marks a value the browser translator must leave alone.
+ *
+ * Prices, counters, order numbers and codes do not need translating, and every
+ * engine measured — Chrome, Edge, Firefox, Yandex and the Google bundle —
+ * honours both `translate="no"` and `.notranslate`. Because the translator never
+ * touches the node, the framework can keep updating it: no crash, no frozen
+ * value, and no risk of a merged number breaking the grammar of a sentence.
+ *
+ * Wrap the value, never the whole sentence, or the reader loses the translation.
+ */
+declare const NoTranslate: ({ children, as: Tag, className }: NoTranslateProps) => react.JSX.Element;
+
+interface TranslationState {
+    isTranslated: boolean;
+    engine: TranslatorEngine | null;
+    lang: string;
+}
+/**
+ * Tells a component whether the page is being machine translated, and by which
+ * engine. Always reports the idle state on the server and on the first client
+ * render, so it cannot cause a hydration mismatch.
+ */
+declare const useTranslationDetected: () => TranslationState;
+
+export { NoTranslate, useTranslationDetected };
+export type { NoTranslateProps, TranslationState };