translate-shield 0.1.0

package/dist/react.js

@@ -0,0 +1,75 @@
+'use client';
+import { jsx } from 'react/jsx-runtime';
+import { useState, useEffect } from 'react';
+import { M as MARKER_ATTRIBUTES, d as detectEngine } from './dom-crorgc8a.js';
+
+/**
+ * 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__*/ 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 = 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',
+            ...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] = useState(IDLE);
+    useEffect(()=>observeTranslation((info)=>{
+            setState({
+                isTranslated: true,
+                engine: info.engine,
+                lang: info.lang
+            });
+        }), []);
+    return state;
+};
+
+export { NoTranslate, useTranslationDetected };

package/dist/types-fjbg60f8.d.ts

@@ -0,0 +1,28 @@
+type PatchedSurface = 'Node.prototype.removeChild' | 'Node.prototype.insertBefore' | 'Node.prototype.replaceChild' | 'Node.prototype.nodeValue' | 'Node.prototype.textContent' | 'CharacterData.prototype.data' | 'Element.prototype.attachShadow';
+
+type TranslatorEngine = 'google' | 'yandex' | 'edge' | 'firefox';
+interface TranslationInfo {
+    lang: string;
+    engine: TranslatorEngine | null;
+    wrapperTag: string;
+}
+interface RecoveredError {
+    method: 'removeChild' | 'insertBefore' | 'replaceChild';
+    redirected: boolean;
+}
+interface ShieldOptions {
+    root?: Element;
+    wrapperTags?: ReadonlyArray<string>;
+    onTranslationDetected?: (info: TranslationInfo) => void;
+    onRecoveredError?: (error: RecoveredError) => void;
+    onConflict?: (surfaces: PatchedSurface[]) => void;
+    debug?: boolean;
+}
+interface ShieldHandle {
+    stop: () => void;
+    isTranslated: () => boolean;
+    engine: () => TranslatorEngine | null;
+    conflicts: () => PatchedSurface[];
+}
+
+export type { PatchedSurface as P, RecoveredError as R, ShieldOptions as S, TranslationInfo as T, ShieldHandle as a, TranslatorEngine as b };

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "translate-shield",
+  "version": "0.1.0",
+  "description": "Keeps React and Next.js apps correct when a browser translator rewrites the DOM: no crash, no frozen values, and no flash of the original language.",
+  "keywords": [
+    "google-translate",
+    "browser-translation",
+    "react",
+    "nextjs",
+    "removechild",
+    "notfounderror",
+    "mutationobserver",
+    "i18n",
+    "dom",
+    "accessibility"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "@types/react": "*",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "bunchee",
+    "dev": "npm run dev -w tests/app",
+    "recorder": "vite --port 5200 --strictPort research/recorder",
+    "test": "vitest run",
+    "test:e2e": "playwright test",
+    "typecheck": "tsc --noEmit",
+    "summarise": "node scripts/summarise-fingerprints.mjs",
+    "verify": "npm run typecheck && npm run build && npm run smoke && npx publint --strict && npx @arethetypeswrong/cli --pack .",
+    "prepublishOnly": "npm run typecheck && npm run build && npm run smoke && npx publint --strict",
+    "postbuild": "node scripts/assert-directives.mjs",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.0",
+    "@playwright/test": "^1.55.0",
+    "@types/node": "^26.4.1",
+    "@types/react": "^19.0.0",
+    "bunchee": "^7.0.1",
+    "esbuild": "^0.28.2",
+    "publint": "^0.3.0",
+    "react": "^19.0.0",
+    "translation-resilience": "^0.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "workspaces": [
+    "tests/app"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Davlatbek Aliev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alievdavlat/translate-shield.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alievdavlat/translate-shield/issues"
+  },
+  "homepage": "https://github.com/alievdavlat/translate-shield#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "typesVersions": {
+    "*": {
+      "react": [
+        "./dist/react.d.ts"
+      ]
+    }
+  }
+}