@lovalingo/lovalingo 0.0.26 → 0.0.27

package/README.md

@@ -123,7 +123,6 @@ export default function RootLayout({ children }) {
 ```tsx
 <LovalingoProvider
   publicAnonKey="aix_xxx"             // Required: Your Lovalingo Public Anon Key (safe to expose)
-  // Backwards compatible: apiKey="aix_xxx"
   defaultLocale="en"                  // Required: Source language
   locales={['en', 'de', 'fr']}        // Required: Supported languages
   apiBase="https://..."               // Optional: Custom API endpoint

package/dist/components/AixsterProvider.js

@@ -66,8 +66,8 @@ navigateRef, // For path mode routing
     const domRulesCacheRef = useRef(new Map());
     // NEW: Hash-based translation cache for React Context system
     const [hashTranslations, setHashTranslations] = useState(new Map());
-    const translatingHashesRef = useRef(new Set());
-    const [, forceUpdate] = useState({});
+    const contextMissQueueRef = useRef(new Set());
+    const contextMissFlushTimeoutRef = useRef(null);
     const config = {
         apiKey: resolvedApiKey,
         publicAnonKey: resolvedApiKey,
@@ -236,6 +236,7 @@ navigateRef, // For path mode routing
         if (targetLocale === defaultLocale) {
             if (showOverlay)
                 setIsNavigationLoading(false);
+            setHashTranslations(new Map());
             translatorRef.current.setTranslations([]);
             translatorRef.current.restoreDOM(); // Safe to restore when going back to source language
             translatorRef.current.restoreHead();
@@ -246,18 +247,22 @@ navigateRef, // For path mode routing
         const currentPath = window.location.pathname;
         const cacheKey = `${targetLocale}:${currentPath}`;
         // Check if we have cached translations for this locale + path
-        const cachedTranslations = translationCacheRef.current.get(cacheKey);
+        const cachedEntry = translationCacheRef.current.get(cacheKey);
         const cachedExclusions = exclusionsCacheRef.current;
         const cachedDomRules = domRulesCacheRef.current.get(cacheKey);
-        if (cachedTranslations && cachedExclusions) {
+        if (cachedEntry && cachedExclusions) {
             // CACHE HIT - Use cached data immediately (FAST!)
             console.log(`[Lovalingo] Using cached translations for ${targetLocale} on ${currentPath}`);
-            translatorRef.current.setTranslations(cachedTranslations);
+            setHashTranslations(new Map(Object.entries(cachedEntry.hashMap || {})));
+            translatorRef.current.setTranslations(cachedEntry.translations);
             translatorRef.current.setExclusions(cachedExclusions);
-            translatorRef.current.translateDOM();
-            if (isSeoActive())
+            if (mode === 'dom') {
+                translatorRef.current.translateDOM();
+            }
+            if (isSeoActive()) {
                 translatorRef.current.translateHead();
-            if (autoApplyRules && mode === 'dom') {
+            }
+            if (autoApplyRules) {
                 if (Array.isArray(cachedDomRules)) {
                     applyDomRules(cachedDomRules);
                 }
@@ -274,22 +279,27 @@ navigateRef, // For path mode routing
                     return;
                 }
                 console.log(`[Lovalingo] 🔄 Retry scan for late-rendering content`);
-                translatorRef.current.translateDOM();
-                if (isSeoActive())
+                if (mode === 'dom') {
+                    translatorRef.current.translateDOM();
+                }
+                if (isSeoActive()) {
                     translatorRef.current.translateHead();
-                if (autoApplyRules && mode === 'dom') {
+                }
+                if (autoApplyRules) {
                     const rules = domRulesCacheRef.current.get(cacheKey) || cachedDomRules || [];
                     applyDomRules(rules);
                 }
-                // Immediately report any misses found
-                const missed = translatorRef.current.getMissedStrings();
-                if (missed.length > 0) {
-                    console.log(`[Lovalingo] 📤 Reporting ${missed.length} misses immediately`);
-                    apiRef.current.reportMisses(missed, defaultLocale, targetLocale);
-                    translatorRef.current.clearMissedStrings();
-                }
-                else {
-                    console.log(`[Lovalingo] ✅ No misses detected`);
+                if (mode === "dom") {
+                    // Immediately report any misses found
+                    const missed = translatorRef.current.getMissedStrings();
+                    if (missed.length > 0) {
+                        console.log(`[Lovalingo] 📤 Reporting ${missed.length} misses immediately`);
+                        apiRef.current.reportMisses(missed, defaultLocale, targetLocale);
+                        translatorRef.current.clearMissedStrings();
+                    }
+                    else {
+                        console.log(`[Lovalingo] ✅ No misses detected`);
+                    }
                 }
             }, 500);
             if (showOverlay) {
@@ -305,26 +315,39 @@ navigateRef, // For path mode routing
             if (previousLocale && previousLocale !== defaultLocale) {
                 console.log(`[Lovalingo] Switching from ${previousLocale} to ${targetLocale}`);
             }
-            const [translations, exclusions, domRules] = await Promise.all([
-                apiRef.current.fetchTranslations(defaultLocale, targetLocale),
+            const [bundle, exclusions, domRules] = await Promise.all([
+                apiRef.current.fetchBundle(targetLocale),
                 apiRef.current.fetchExclusions(),
-                autoApplyRules && mode === 'dom' ? apiRef.current.fetchDomRules(targetLocale) : Promise.resolve([]),
+                autoApplyRules ? apiRef.current.fetchDomRules(targetLocale) : Promise.resolve([]),
             ]);
             const nextEntitlements = apiRef.current.getEntitlements();
             if (nextEntitlements)
                 setEntitlements(nextEntitlements);
+            const translations = bundle
+                ? Object.entries(bundle.map).map(([source_text, translated_text]) => ({
+                    source_text,
+                    translated_text,
+                    source_locale: defaultLocale,
+                    target_locale: targetLocale,
+                }))
+                : [];
+            const hashMap = bundle?.hashMap || {};
+            setHashTranslations(new Map(Object.entries(hashMap)));
             // Store in cache for next time
-            translationCacheRef.current.set(cacheKey, translations);
+            translationCacheRef.current.set(cacheKey, { translations, hashMap });
             exclusionsCacheRef.current = exclusions;
-            if (autoApplyRules && mode === 'dom') {
+            if (autoApplyRules) {
                 domRulesCacheRef.current.set(cacheKey, domRules);
             }
             translatorRef.current.setTranslations(translations);
             translatorRef.current.setExclusions(exclusions);
-            translatorRef.current.translateDOM();
-            if (isSeoActive())
+            if (mode === 'dom') {
+                translatorRef.current.translateDOM();
+            }
+            if (isSeoActive()) {
                 translatorRef.current.translateHead();
-            if (autoApplyRules && mode === 'dom') {
+            }
+            if (autoApplyRules) {
                 applyDomRules(domRules);
             }
             // Delayed retry scan to catch late-rendering content
@@ -334,22 +357,27 @@ navigateRef, // For path mode routing
                     return;
                 }
                 console.log(`[Lovalingo] 🔄 Retry scan for late-rendering content`);
-                translatorRef.current.translateDOM();
-                if (isSeoActive())
+                if (mode === "dom") {
+                    translatorRef.current.translateDOM();
+                }
+                if (isSeoActive()) {
                     translatorRef.current.translateHead();
-                if (autoApplyRules && mode === 'dom') {
+                }
+                if (autoApplyRules) {
                     const rules = domRulesCacheRef.current.get(cacheKey) || domRules || [];
                     applyDomRules(rules);
                 }
-                // Immediately report any misses found
-                const missed = translatorRef.current.getMissedStrings();
-                if (missed.length > 0) {
-                    console.log(`[Lovalingo] 📤 Reporting ${missed.length} misses immediately`);
-                    apiRef.current.reportMisses(missed, defaultLocale, targetLocale);
-                    translatorRef.current.clearMissedStrings();
-                }
-                else {
-                    console.log(`[Lovalingo] ✅ No misses detected`);
+                if (mode === "dom") {
+                    // Immediately report any misses found
+                    const missed = translatorRef.current.getMissedStrings();
+                    if (missed.length > 0) {
+                        console.log(`[Lovalingo] 📤 Reporting ${missed.length} misses immediately`);
+                        apiRef.current.reportMisses(missed, defaultLocale, targetLocale);
+                        translatorRef.current.clearMissedStrings();
+                    }
+                    else {
+                        console.log(`[Lovalingo] ✅ No misses detected`);
+                    }
                 }
             }, 500);
             if (showOverlay) {
@@ -426,43 +454,30 @@ navigateRef, // For path mode routing
     const getTranslation = useCallback((hash, fallback) => {
         return hashTranslations.get(hash) || null;
     }, [hashTranslations]);
-    // NEW: Queue real-time translation
-    const queueRealTimeTranslation = useCallback(async (hash, text, onComplete) => {
-        // Already translating this hash
-        if (translatingHashesRef.current.has(hash)) {
+    const queueMiss = useCallback((text) => {
+        const cleaned = (text || "").toString().trim();
+        if (!cleaned || cleaned.length < 2)
             return;
-        }
-        // Already have translation
-        if (hashTranslations.has(hash)) {
+        if (locale === defaultLocale)
             return;
-        }
-        // Mark as translating
-        translatingHashesRef.current.add(hash);
-        try {
-            // Call real-time translation API
-            const translation = await apiRef.current.translateRealtime(hash, text, defaultLocale, locale);
-            if (translation) {
-                // Update cache
-                setHashTranslations(prev => {
-                    const newMap = new Map(prev);
-                    newMap.set(hash, translation);
-                    return newMap;
-                });
-                // Force re-render to show translation
-                forceUpdate({});
-                if (onComplete) {
-                    onComplete();
-                }
-            }
-        }
-        catch (error) {
-            console.error(`[Lovalingo] Failed to translate hash ${hash}:`, error);
-        }
-        finally {
-            // Remove from translating set
-            translatingHashesRef.current.delete(hash);
-        }
-    }, [defaultLocale, locale, hashTranslations]);
+        contextMissQueueRef.current.add(cleaned);
+        if (contextMissFlushTimeoutRef.current)
+            return;
+        contextMissFlushTimeoutRef.current = setTimeout(() => {
+            contextMissFlushTimeoutRef.current = null;
+            const batch = Array.from(contextMissQueueRef.current);
+            contextMissQueueRef.current.clear();
+            if (batch.length === 0)
+                return;
+            const misses = batch.map((value) => ({
+                text: value,
+                raw: value,
+                placeholderMap: {},
+                semanticContext: "react",
+            }));
+            void apiRef.current.reportMisses(misses, defaultLocale, locale);
+        }, 800);
+    }, [defaultLocale, locale]);
     // Selenium bridge: allows automation to force-flush misses instead of relying on the 5s interval.
     useEffect(() => {
         if (typeof window === "undefined")
@@ -506,10 +521,8 @@ navigateRef, // For path mode routing
             if (next)
                 setEntitlements(next);
         });
-        // Only load data for DOM mode (context mode uses AutoTranslate)
-        if (mode === 'dom') {
-            loadData(initialLocale);
-        }
+        // Always prefetch artifacts for the initial locale so context mode has hashMap ready.
+        loadData(initialLocale);
         // Set up keyboard shortcut for edit mode
         const handleKeyPress = (e) => {
             if (e.code === editKey && (e.ctrlKey || e.metaKey)) {
@@ -530,7 +543,7 @@ navigateRef, // For path mode routing
     useEffect(() => {
         if (sitemap && resolvedApiKey && isSeoActive()) {
             // Prefer same-origin /sitemap.xml so crawlers discover the canonical sitemap URL.
-            // Hosting should route /sitemap.xml to Lovalingo's generate-sitemap endpoint.
+            // Reminder: /sitemap.xml should be published by the host app (recommended: build-time copy from Lovalingo CDN).
             const sitemapUrl = `${window.location.origin}/sitemap.xml`;
             // Check if link already exists to avoid duplicates
             const existingLink = document.querySelector(`link[rel="sitemap"][href="${sitemapUrl}"]`);
@@ -871,7 +884,7 @@ navigateRef, // For path mode routing
         toggleEditMode,
         excludeElement,
         getTranslation,
-        queueRealTimeTranslation,
+        queueMiss,
     };
     return (React.createElement(LovalingoContext.Provider, { value: contextValue },
         children,

package/dist/components/AutoTranslate.js

@@ -1,4 +1,4 @@
-import React, { useContext, useState } from 'react';
+import React, { useContext } from 'react';
 import { LovalingoContext } from '../context/LovalingoContext';
 import { hashContent } from '../utils/hash';
 /**
@@ -7,12 +7,11 @@ import { hashContent } from '../utils/hash';
  */
 export const AutoTranslate = ({ children }) => {
     const context = useContext(LovalingoContext);
-    const [isTranslating, setIsTranslating] = useState(false);
     if (!context) {
         // Not wrapped in LovalingoProvider - return children as-is
         return React.createElement(React.Fragment, null, children);
     }
-    const { locale, config, getTranslation, queueRealTimeTranslation } = context;
+    const { locale, config, getTranslation, queueMiss } = context;
     // If we're on default locale, no translation needed
     if (locale === config.defaultLocale) {
         return React.createElement(React.Fragment, null, children);
@@ -21,7 +20,11 @@ export const AutoTranslate = ({ children }) => {
     const translateChildren = (node) => {
         // Handle strings (text nodes)
         if (typeof node === 'string') {
-            const trimmed = node.trim();
+            const match = node.match(/^(\s*)(.*?)(\s*)$/s);
+            const leading = match?.[1] ?? "";
+            const core = match?.[2] ?? node;
+            const trailing = match?.[3] ?? "";
+            const trimmed = core.trim();
             // Skip empty or very short strings
             if (trimmed.length === 0 || trimmed.length < 2) {
                 return node;
@@ -32,22 +35,11 @@ export const AutoTranslate = ({ children }) => {
             const translation = getTranslation(contentHash, trimmed);
             if (translation) {
                 // We have translation - return it
-                return translation;
+                return `${leading}${translation}${trailing}`;
             }
-            // No translation - queue for real-time translation
-            if (!isTranslating) {
-                setIsTranslating(true);
-                queueRealTimeTranslation(contentHash, trimmed, () => {
-                    setIsTranslating(false);
-                });
-            }
-            // Return blurred original text while translating
-            return (React.createElement("span", { style: {
-                    filter: 'blur(3px)',
-                    opacity: 0.6,
-                    transition: 'filter 0.3s ease, opacity 0.3s ease',
-                    display: 'inline-block',
-                }, "data-translating": "true", "data-hash": contentHash }, trimmed));
+            // No translation yet: report miss (may enqueue deterministic pipeline job) and show original.
+            queueMiss(trimmed);
+            return node;
         }
         // Handle numbers
         if (typeof node === 'number') {

package/dist/types.d.ts

@@ -2,12 +2,10 @@ import { PathNormalizationConfig } from './utils/pathNormalizer';
 export interface LovalingoConfig {
     /**
      * Public project key (safe to expose in the browser).
-     * Backwards compatible alias: you can still pass `apiKey`.
      */
     publicAnonKey?: string;
     /**
-     * Backwards compatible name for the public project key.
-     * Prefer `publicAnonKey` in new installs.
+     * @deprecated Use `publicAnonKey`.
      */
     apiKey?: string;
     defaultLocale: string;
@@ -35,7 +33,7 @@ export interface LovalingoContextValue {
     toggleEditMode: () => void;
     excludeElement: (selector: string) => Promise<void>;
     getTranslation: (hash: string, fallback: string) => string | null;
-    queueRealTimeTranslation: (hash: string, text: string, onComplete?: () => void) => void;
+    queueMiss: (text: string) => void;
 }
 export interface Translation {
     source_text: string;

package/dist/utils/api.d.ts

@@ -23,13 +23,12 @@ export declare class LovalingoAPI {
     fetchEntitlements(localeHint: string): Promise<ProjectEntitlements | null>;
     trackPageview(pathOrUrl: string): Promise<void>;
     fetchTranslations(sourceLocale: string, targetLocale: string): Promise<Translation[]>;
+    fetchBundle(localeHint: string): Promise<{
+        map: Record<string, string>;
+        hashMap: Record<string, string>;
+    } | null>;
     fetchExclusions(): Promise<Exclusion[]>;
     fetchDomRules(targetLocale: string): Promise<DomRule[]>;
     reportMisses(misses: MissedTranslation[], sourceLocale: string, targetLocale: string): Promise<void>;
     saveExclusion(selector: string, type: 'css' | 'xpath'): Promise<void>;
-    /**
-     * Real-time translation - calls Groq directly for instant translation
-     * Used when translation cache misses
-     */
-    translateRealtime(contentHash: string, sourceText: string, sourceLocale: string, targetLocale: string): Promise<string | null>;
 }

package/dist/utils/api.js

@@ -16,7 +16,7 @@ export class LovalingoAPI {
     logActivationRequired(context, response) {
         console.error(`[Lovalingo] ${context} blocked (HTTP ${response.status}). ` +
             `This project is not activated yet. ` +
-            `Publish a public routes manifest at "/.well-known/lovalingo-routes.json" on your domain, ` +
+            `Publish a public manifest at "/.well-known/lovalingo.json" on your domain, ` +
             `then verify it in the Lovalingo dashboard to activate translations + SEO.`);
     }
     isActivationRequiredPayload(data) {
@@ -92,19 +92,39 @@ export class LovalingoAPI {
                 this.warnMissingApiKey('fetchTranslations');
                 return [];
             }
-            // Use path normalization utility
+            const bundle = await this.fetchBundle(targetLocale);
+            if (!bundle)
+                return [];
+            return Object.entries(bundle.map).map(([source_text, translated_text]) => ({
+                source_text,
+                translated_text,
+                source_locale: sourceLocale,
+                target_locale: targetLocale,
+            }));
+        }
+        catch (error) {
+            console.error('Error fetching translations:', error);
+            return [];
+        }
+    }
+    async fetchBundle(localeHint) {
+        try {
+            if (!this.hasApiKey()) {
+                this.warnMissingApiKey("fetchBundle");
+                return null;
+            }
             const normalizedPath = processPath(window.location.pathname, this.pathConfig);
-            const response = await fetch(`${this.apiBase}/functions/v1/bundle?key=${this.apiKey}&locale=${targetLocale}&path=${normalizedPath}`);
+            const response = await fetch(`${this.apiBase}/functions/v1/bundle?key=${this.apiKey}&locale=${localeHint}&path=${normalizedPath}`);
             if (this.isActivationRequiredResponse(response)) {
-                this.logActivationRequired('fetchTranslations', response);
-                return [];
+                this.logActivationRequired("fetchBundle", response);
+                return null;
             }
             if (!response.ok)
-                throw new Error('Failed to fetch translations');
+                return null;
             const data = await response.json();
             if (this.isActivationRequiredResponse(response, data)) {
-                this.logActivationRequired("fetchTranslations", response);
-                return [];
+                this.logActivationRequired("fetchBundle", response);
+                return null;
             }
             if (data?.entitlements) {
                 this.entitlements = {
@@ -112,20 +132,12 @@ export class LovalingoAPI {
                     seoEnabled: typeof data?.seoEnabled === "boolean" ? data.seoEnabled : undefined,
                 };
             }
-            // Convert map to array of Translation objects
-            if (data.map && typeof data.map === 'object') {
-                return Object.entries(data.map).map(([source_text, translated_text]) => ({
-                    source_text,
-                    translated_text: translated_text,
-                    source_locale: sourceLocale,
-                    target_locale: targetLocale,
-                }));
-            }
-            return [];
+            const map = data?.map && typeof data.map === "object" ? data.map : {};
+            const hashMap = data?.hashMap && typeof data.hashMap === "object" ? data.hashMap : {};
+            return { map, hashMap };
         }
-        catch (error) {
-            console.error('Error fetching translations:', error);
-            return [];
+        catch {
+            return null;
         }
     }
     async fetchExclusions() {
@@ -257,53 +269,4 @@ export class LovalingoAPI {
             throw error;
         }
     }
-    /**
-     * Real-time translation - calls Groq directly for instant translation
-     * Used when translation cache misses
-     */
-    async translateRealtime(contentHash, sourceText, sourceLocale, targetLocale) {
-        try {
-            if (!this.hasApiKey()) {
-                this.warnMissingApiKey('translateRealtime');
-                return null;
-            }
-            console.log(`[Lovalingo] 🚀 Real-time translation: "${sourceText.substring(0, 40)}..."`);
-            const response = await fetch(`${this.apiBase}/functions/v1/translate-realtime`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'x-api-key': this.apiKey,
-                },
-                body: JSON.stringify({
-                    contentHash,
-                    sourceText,
-                    sourceLocale,
-                    targetLocale,
-                }),
-            });
-            if (this.isActivationRequiredResponse(response)) {
-                this.logActivationRequired('translateRealtime', response);
-                return null;
-            }
-            if (!response.ok) {
-                const errorText = await response.text();
-                console.error(`[Lovalingo] ❌ Real-time translation failed:`, errorText);
-                return null;
-            }
-            const result = await response.json();
-            if (this.isActivationRequiredResponse(response, result)) {
-                this.logActivationRequired("translateRealtime", response);
-                return null;
-            }
-            if (result.success && result.translation) {
-                console.log(`[Lovalingo] ✅ Translated: "${result.translation.substring(0, 40)}..." ${result.cached ? '(cached)' : '(new)'}`);
-                return result.translation;
-            }
-            return null;
-        }
-        catch (error) {
-            console.error('[Lovalingo] ❌ Real-time translation error:', error);
-            return null;
-        }
-    }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lovalingo/lovalingo",
-  "version": "0.0.26",
-  "description": "React translation library with automatic routing, real-time AI translation, and zero-flash rendering. One-line language routing setup.",
+  "version": "0.0.27",
+  "description": "React translation runtime with i18n routing, deterministic bundles + DOM rules, and zero-flash rendering.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "publishConfig": {