@lovalingo/lovalingo 0.5.8 → 0.5.10

package/dist/components/LovalingoProvider.js

@@ -1,4 +1,4 @@
-import React, { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { LovalingoContext } from '../context/LovalingoContext';
 import { LangRoutingContext } from '../context/LangRoutingContext';
 import { LovalingoAPI } from '../utils/api';
@@ -11,10 +11,13 @@ import { useNavigationPrefetch } from '../hooks/provider/useNavigationPrefetch';
 import { useLinkAutoPrefix } from '../hooks/provider/useLinkAutoPrefix';
 import { usePageviewTracking } from '../hooks/provider/usePageviewTracking';
 import { useSitemapLinkTag } from '../hooks/provider/useSitemapLinkTag';
+import { useStringMissReporting } from '../hooks/provider/useStringMissReporting';
 import { LanguageSwitcher } from './LanguageSwitcher';
 const LOCALE_STORAGE_KEY = 'Lovalingo_locale';
 const LOADING_BG_STORAGE_PREFIX = "Lovalingo_loading_bg_color";
 const BRANDING_STORAGE_PREFIX = "Lovalingo_branding_enabled";
+// Why: run initial load before first paint on the client to avoid a prehide flash; useEffect on SSR.
+const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
 export const LovalingoProvider = ({ children, apiKey: apiKeyProp, publicAnonKey, defaultLocale, locales, apiBase = 'https://cdn.lovalingo.com', routing = 'path', // Default to path mode (SEO-friendly, recommended)
 autoPrefixLinks = true, overlayBgColor, autoApplyRules = true, switcherPosition = 'bottom-right', switcherOffsetY = 20, switcherTheme = 'dark', editMode: initialEditMode = false, editKey = 'KeyE', pathNormalization = { enabled: true }, // Enable by default
 mode = 'dom', // Default to legacy DOM mode for backward compatibility
@@ -524,7 +527,7 @@ navigateRef, // For path mode routing
         detectLocaleRef.current = detectLocale;
     }, [detectLocale]);
     // Initialize
-    useEffect(() => {
+    useIsomorphicLayoutEffect(() => {
         const initialLocale = detectLocaleRef.current();
         lastNormalizedPathRef.current = processPath(window.location.pathname, enhancedPathConfig);
         // Track initial page (fallback discovery for pages not present in the routes feed).
@@ -561,6 +564,17 @@ navigateRef, // For path mode routing
         allLocales,
         enhancedPathConfig,
     });
+    useStringMissReporting({
+        apiRef,
+        resolvedApiKey,
+        locale,
+        defaultLocale,
+        routing,
+        allLocales,
+        nonLocalizedPaths: routingConfig.nonLocalizedPaths,
+        isLoading,
+        mode,
+    });
     // Dynamic DOM updates are handled by the marker engine observer (React-safe in-place text/attr updates).
     // No periodic string-miss reporting. Page discovery is tracked via pageview only.
     const translateElement = useCallback((element) => {

package/dist/hooks/provider/useStringMissReporting.d.ts

@@ -0,0 +1,14 @@
+import type { MutableRefObject } from "react";
+import type { LovalingoAPI } from "../../utils/api";
+import { type NonLocalizedPathRule } from "../../utils/nonLocalizedPaths";
+export declare function useStringMissReporting(args: {
+    apiRef: MutableRefObject<LovalingoAPI>;
+    resolvedApiKey: string;
+    locale: string;
+    defaultLocale: string;
+    routing: "path" | "query";
+    allLocales: string[];
+    nonLocalizedPaths: NonLocalizedPathRule[];
+    isLoading: boolean;
+    mode: "dom";
+}): void;

package/dist/hooks/provider/useStringMissReporting.js

@@ -0,0 +1,150 @@
+import { useCallback, useEffect, useRef } from "react";
+import { addActiveTranslations, applyActiveTranslations, clearMissBlur, scanDomForMisses } from "../../utils/markerEngine";
+import { isNonLocalizedPath, stripLocalePrefix } from "../../utils/nonLocalizedPaths";
+// Why: throttle miss scans so we stay responsive on DOM-heavy pages.
+const MISS_SCAN_THROTTLE_MS = 600;
+// Why: allow large pages to report plenty of misses while keeping payloads bounded.
+const MISS_MAX_PER_PAGE = 500;
+export function useStringMissReporting(args) {
+    const pendingRef = useRef(new Set());
+    const seenRef = useRef(new Set());
+    const blurredRef = useRef(new Map());
+    const scheduledRef = useRef(null);
+    const inFlightRef = useRef(false);
+    const mergeBlurred = useCallback((incoming) => {
+        for (const [text, elements] of incoming.entries()) {
+            let set = blurredRef.current.get(text);
+            if (!set) {
+                set = new Set();
+                blurredRef.current.set(text, set);
+            }
+            elements.forEach((el) => set.add(el));
+        }
+    }, []);
+    const clearBlurForText = useCallback((text) => {
+        const elements = blurredRef.current.get(text);
+        if (!elements)
+            return;
+        clearMissBlur(elements);
+        blurredRef.current.delete(text);
+    }, []);
+    useEffect(() => {
+        pendingRef.current.clear();
+        seenRef.current.clear();
+        for (const elements of blurredRef.current.values()) {
+            clearMissBlur(elements);
+        }
+        blurredRef.current.clear();
+    }, [args.locale]);
+    const shouldSkip = useCallback(() => {
+        if (typeof window === "undefined" || typeof document === "undefined")
+            return true;
+        if (!args.resolvedApiKey || args.mode !== "dom")
+            return true;
+        if (args.isLoading)
+            return true;
+        if (args.locale === args.defaultLocale)
+            return true;
+        if (args.routing === "path") {
+            const stripped = stripLocalePrefix(window.location.pathname, args.allLocales);
+            if (isNonLocalizedPath(stripped, args.nonLocalizedPaths))
+                return true;
+        }
+        return false;
+    }, [args.allLocales, args.defaultLocale, args.isLoading, args.locale, args.mode, args.nonLocalizedPaths, args.resolvedApiKey, args.routing]);
+    const runScan = useCallback(async () => {
+        scheduledRef.current = null;
+        if (shouldSkip())
+            return;
+        if (!document.body)
+            return;
+        if (inFlightRef.current)
+            return;
+        const ignore = new Set([...pendingRef.current, ...seenRef.current]);
+        const { misses, blurred } = scanDomForMisses({ max: MISS_MAX_PER_PAGE, ignore, blur: true });
+        if (misses.length === 0)
+            return;
+        mergeBlurred(blurred);
+        misses.forEach((miss) => pendingRef.current.add(miss.source_text));
+        inFlightRef.current = true;
+        try {
+            const response = await args.apiRef.current.reportStringMisses(args.locale, misses, {
+                sourceLocale: args.defaultLocale,
+                locales: args.allLocales,
+            });
+            if (response?.ignored) {
+                for (const miss of misses) {
+                    pendingRef.current.delete(miss.source_text);
+                    clearBlurForText(miss.source_text);
+                    seenRef.current.add(miss.source_text);
+                }
+                return;
+            }
+            const translations = Array.isArray(response?.translations) ? response.translations : [];
+            const pii = Array.isArray(response?.pii) ? response.pii : [];
+            const resolved = new Set();
+            pii.forEach((text) => resolved.add(text));
+            translations.forEach((row) => {
+                if (row?.source_text)
+                    resolved.add(row.source_text);
+            });
+            if (translations.length > 0) {
+                const additions = translations
+                    .map((row) => ({
+                    source_text: row.source_text,
+                    translated_text: row.translated_text,
+                    source_locale: args.defaultLocale,
+                    target_locale: args.locale,
+                }))
+                    .filter((row) => row.source_text && row.translated_text);
+                if (additions.length > 0) {
+                    addActiveTranslations(additions);
+                    applyActiveTranslations(document.body);
+                }
+            }
+            for (const miss of misses) {
+                pendingRef.current.delete(miss.source_text);
+                clearBlurForText(miss.source_text);
+                if (resolved.has(miss.source_text)) {
+                    seenRef.current.add(miss.source_text);
+                }
+            }
+        }
+        catch {
+            for (const miss of misses) {
+                pendingRef.current.delete(miss.source_text);
+                clearBlurForText(miss.source_text);
+            }
+        }
+        finally {
+            inFlightRef.current = false;
+        }
+    }, [args.apiRef, args.defaultLocale, args.locale, clearBlurForText, mergeBlurred, shouldSkip]);
+    const scheduleScan = useCallback(() => {
+        if (scheduledRef.current != null)
+            return;
+        scheduledRef.current = window.setTimeout(() => {
+            void runScan();
+        }, MISS_SCAN_THROTTLE_MS);
+    }, [runScan]);
+    useEffect(() => {
+        if (shouldSkip())
+            return;
+        scheduleScan();
+        if (!document.body)
+            return;
+        const observer = new MutationObserver(() => scheduleScan());
+        observer.observe(document.body, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+        });
+        return () => {
+            observer.disconnect();
+            if (scheduledRef.current != null) {
+                window.clearTimeout(scheduledRef.current);
+                scheduledRef.current = null;
+            }
+        };
+    }, [scheduleScan, shouldSkip]);
+}

package/dist/utils/api.d.ts

@@ -59,6 +59,24 @@ export type BootstrapResponse = {
     };
     etag?: string;
 };
+export type MissReportItem = {
+    source_text: string;
+    semantic_context?: string | null;
+};
+export type MissReportResponse = {
+    translations?: Array<{
+        source_text: string;
+        translated_text: string;
+    }>;
+    pii?: string[];
+    ignored?: boolean;
+    reason?: string;
+};
+export type MissReportOptions = {
+    pathOrUrl?: string;
+    sourceLocale?: string;
+    locales?: string[];
+};
 export declare class LovalingoAPI {
     private apiKey;
     private apiBase;
@@ -78,6 +96,7 @@ export declare class LovalingoAPI {
         critical_count?: number;
         critical_hash?: string;
     }): Promise<void>;
+    reportStringMisses(targetLocale: string, misses: MissReportItem[], opts?: MissReportOptions): Promise<MissReportResponse | null>;
     fetchTranslations(sourceLocale: string, targetLocale: string): Promise<Translation[]>;
     fetchBundle(localeHint: string, pathOrUrl?: string): Promise<{
         map: Record<string, string>;

package/dist/utils/api.js

@@ -143,6 +143,42 @@ export class LovalingoAPI {
             // Ignore tracking errors.
         }
     }
+    async reportStringMisses(targetLocale, misses, opts) {
+        try {
+            if (!this.hasApiKey())
+                return null;
+            if (!Array.isArray(misses) || misses.length === 0)
+                return null;
+            const pathParam = this.buildPathParam(opts?.pathOrUrl);
+            const response = await fetch(`${this.apiBase}/functions/v1/misses`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    key: this.apiKey,
+                    locale: targetLocale,
+                    path: pathParam,
+                    source_locale: opts?.sourceLocale,
+                    locales: Array.isArray(opts?.locales) ? opts?.locales : undefined,
+                    misses,
+                }),
+            });
+            if (this.isActivationRequiredResponse(response)) {
+                this.logActivationRequired("reportStringMisses", response);
+                return null;
+            }
+            if (!response.ok)
+                return null;
+            const data = await response.json();
+            if (this.isActivationRequiredResponse(response, data)) {
+                this.logActivationRequired("reportStringMisses", response);
+                return null;
+            }
+            return data;
+        }
+        catch {
+            return null;
+        }
+    }
     async fetchTranslations(sourceLocale, targetLocale) {
         try {
             if (!this.hasApiKey()) {

package/dist/utils/markerEngine.d.ts

@@ -39,6 +39,14 @@ export type DomScanResult = {
     };
     truncated: boolean;
 };
+export type DomMiss = {
+    source_text: string;
+    semantic_context: string;
+};
+export type DomMissScanResult = {
+    misses: DomMiss[];
+    blurred: Map<string, Set<HTMLElement>>;
+};
 export type CriticalFingerprint = {
     critical_count: number;
     critical_hash: string;
@@ -53,6 +61,13 @@ export declare function stopMarkerEngine(): void;
 export declare function getMarkerStats(): MarkerStats;
 export declare function setMarkerEngineExclusions(exclusions: Exclusion[] | null): void;
 export declare function setActiveTranslations(translations: Translation[] | null): void;
+export declare function addActiveTranslations(translations: Translation[] | Record<string, string> | null): number;
 export declare function applyActiveTranslations(root?: ParentNode | null): number;
+export declare function clearMissBlur(elements: Iterable<HTMLElement>): void;
+export declare function scanDomForMisses(opts: {
+    max: number;
+    ignore?: Set<string>;
+    blur?: boolean;
+}): DomMissScanResult;
 export declare function restoreDom(root?: ParentNode | null): void;
 export {};

package/dist/utils/markerEngine.js

@@ -10,6 +10,8 @@ const ATTRIBUTE_MARKS = [
     { attr: "aria-label", marker: "data-lovalingo-aria-label-original" },
     { attr: "placeholder", marker: "data-lovalingo-placeholder-original" },
 ];
+const MISS_BLUR_ATTR = "data-lovalingo-miss-blur";
+const MISS_BLUR_STYLE_ID = "lovalingo-miss-blur-style";
 const unsafeSelector = Array.from(UNSAFE_CONTAINER_TAGS).join(",");
 let observer = null;
 let scheduled = null;
@@ -176,6 +178,31 @@ function getOrInitAttrOriginal(el, attr) {
     map.set(attr, value);
     return value;
 }
+// Why: avoid blurring large containers; keep the effect scoped to leaf text nodes.
+function shouldBlurElement(el) {
+    if (!el)
+        return false;
+    if (el.tagName === "HTML" || el.tagName === "BODY")
+        return false;
+    if (el.childElementCount > 0)
+        return false;
+    return true;
+}
+function ensureMissBlurStyles() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(MISS_BLUR_STYLE_ID))
+        return;
+    const style = document.createElement("style");
+    style.id = MISS_BLUR_STYLE_ID;
+    style.textContent =
+        `[${MISS_BLUR_ATTR}="1"] {` +
+            "filter: blur(2px);" +
+            "transition: filter 0.18s ease-out;" +
+            "will-change: filter;" +
+            "}";
+    document.head.appendChild(style);
+}
 function isInViewport(rect, viewportHeight, bufferPx) {
     if (!rect)
         return false;
@@ -552,6 +579,38 @@ export function setActiveTranslations(translations) {
     }
     activeTranslationMap = map;
 }
+export function addActiveTranslations(translations) {
+    if (!translations)
+        return 0;
+    const map = activeTranslationMap ?? new Map();
+    let added = 0;
+    if (Array.isArray(translations)) {
+        for (const t of translations) {
+            const source = normalizeWhitespace((t?.source_text || "").toString());
+            const translated = (t?.translated_text ?? "").toString();
+            if (!source || !translated)
+                continue;
+            if (map.get(source) === translated)
+                continue;
+            map.set(source, translated);
+            added += 1;
+        }
+    }
+    else {
+        for (const [keyRaw, valueRaw] of Object.entries(translations || {})) {
+            const source = normalizeWhitespace((keyRaw || "").toString());
+            const translated = (valueRaw ?? "").toString();
+            if (!source || !translated)
+                continue;
+            if (map.get(source) === translated)
+                continue;
+            map.set(source, translated);
+            added += 1;
+        }
+    }
+    activeTranslationMap = map;
+    return added;
+}
 function applyTranslationMap(bundle, root) {
     if (!root)
         return 0;
@@ -641,6 +700,100 @@ export function applyActiveTranslations(root = document.body) {
     }
     return applied;
 }
+export function clearMissBlur(elements) {
+    for (const el of elements) {
+        if (!el)
+            continue;
+        if (el.getAttribute(MISS_BLUR_ATTR) !== "1")
+            continue;
+        el.removeAttribute(MISS_BLUR_ATTR);
+    }
+}
+export function scanDomForMisses(opts) {
+    const root = document.body;
+    const misses = [];
+    const blurred = new Map();
+    if (!root || !activeTranslationMap || activeTranslationMap.size === 0) {
+        return { misses, blurred };
+    }
+    const max = Math.max(0, Math.floor(opts.max || 0));
+    if (max <= 0)
+        return { misses, blurred };
+    if (opts.blur)
+        ensureMissBlurStyles();
+    const ignore = opts.ignore || new Set();
+    const seen = new Set();
+    const recordMiss = (text, context, el) => {
+        if (!text || seen.has(text) || ignore.has(text))
+            return;
+        if (activeTranslationMap?.has(text))
+            return;
+        if (misses.length >= max)
+            return;
+        seen.add(text);
+        misses.push({ source_text: text, semantic_context: context });
+        if (opts.blur && el instanceof HTMLElement && shouldBlurElement(el)) {
+            el.setAttribute(MISS_BLUR_ATTR, "1");
+            let set = blurred.get(text);
+            if (!set) {
+                set = new Set();
+                blurred.set(text, set);
+            }
+            set.add(el);
+        }
+    };
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    let node = walker.nextNode();
+    while (node && misses.length < max) {
+        if (node.nodeType !== Node.TEXT_NODE) {
+            node = walker.nextNode();
+            continue;
+        }
+        const textNode = node;
+        const parent = textNode.parentElement;
+        if (!parent || isExcludedElement(parent) || findUnsafeContainer(parent)) {
+            node = walker.nextNode();
+            continue;
+        }
+        const raw = textNode.nodeValue || "";
+        const trimmed = raw.trim();
+        if (!trimmed || !isTranslatableText(trimmed)) {
+            node = walker.nextNode();
+            continue;
+        }
+        const original = getOrInitTextOriginal(textNode, parent);
+        const key = normalizeWhitespace(original.trimmed);
+        if (key) {
+            recordMiss(key, "text", parent);
+        }
+        node = walker.nextNode();
+    }
+    if (misses.length < max) {
+        const nodes = root.querySelectorAll("[title],[aria-label],[placeholder]");
+        nodes.forEach((el) => {
+            if (misses.length >= max)
+                return;
+            if (isExcludedElement(el) || findUnsafeContainer(el))
+                return;
+            for (const { attr } of ATTRIBUTE_MARKS) {
+                if (misses.length >= max)
+                    break;
+                const value = el.getAttribute(attr);
+                if (!value)
+                    continue;
+                const trimmed = value.trim();
+                if (!trimmed || !isTranslatableText(trimmed))
+                    continue;
+                const original = normalizeWhitespace(getOrInitAttrOriginal(el, attr));
+                if (!original)
+                    continue;
+                const context = attr === "title" ? "attr:title" : attr === "aria-label" ? "attr:aria-label" : "attr:placeholder";
+                recordMiss(original, context);
+            }
+        });
+    }
+    return { misses, blurred };
+}
 export function restoreDom(root = document.body) {
     if (!root)
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovalingo/lovalingo",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "React translation runtime with i18n routing, deterministic bundles + DOM rules, and zero-flash rendering.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",