@lovalingo/lovalingo 0.0.11

package/dist/utils/api.js

@@ -0,0 +1,145 @@
+import { processPath } from './pathNormalizer';
+export class LovalingoAPI {
+    constructor(apiKey, apiBase, pathConfig) {
+        this.apiKey = apiKey;
+        this.apiBase = apiBase;
+        this.pathConfig = pathConfig;
+    }
+    async fetchTranslations(sourceLocale, targetLocale) {
+        try {
+            // Use path normalization utility
+            const normalizedPath = processPath(window.location.pathname, this.pathConfig);
+            const response = await fetch(`${this.apiBase}/functions/v1/bundle?key=${this.apiKey}&locale=${targetLocale}&path=${normalizedPath}`);
+            if (!response.ok)
+                throw new Error('Failed to fetch translations');
+            const data = await response.json();
+            // 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 [];
+        }
+        catch (error) {
+            console.error('Error fetching translations:', error);
+            return [];
+        }
+    }
+    async fetchExclusions() {
+        try {
+            const response = await fetch(`${this.apiBase}/functions/v1/exclusions?key=${this.apiKey}`);
+            if (!response.ok)
+                throw new Error('Failed to fetch exclusions');
+            const data = await response.json();
+            // Handle response format { exclusions: [...] }
+            return Array.isArray(data.exclusions) ? data.exclusions : [];
+        }
+        catch (error) {
+            console.error('Error fetching exclusions:', error);
+            return [];
+        }
+    }
+    async reportMisses(misses, sourceLocale, targetLocale) {
+        try {
+            // Use path normalization utility
+            const normalizedPath = processPath(window.location.pathname, this.pathConfig);
+            // CRITICAL: Filter out invalid misses
+            const validMisses = misses.filter(m => {
+                const isValid = m?.text &&
+                    typeof m.text === 'string' &&
+                    m.text.trim().length > 1;
+                if (!isValid) {
+                    console.warn('[Lovalingo] ⚠️ Filtered invalid miss:', m);
+                }
+                return isValid;
+            });
+            if (validMisses.length === 0) {
+                console.log('[Lovalingo] ℹ️ No valid misses to report');
+                return;
+            }
+            // Format for API
+            const formattedMisses = validMisses.map(m => ({
+                source_text: m.text.trim(), // Tokenized text
+                source_text_raw: m.raw, // Original HTML
+                placeholder_map: m.placeholderMap, // Token → HTML mapping
+                semantic_context: m.semanticContext // Element type
+            }));
+            console.log(`[Lovalingo] 📤 Reporting ${formattedMisses.length} misses to API...`);
+            console.log('[Lovalingo] Sample miss:', formattedMisses[0]);
+            const response = await fetch(`${this.apiBase}/functions/v1/misses`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    key: this.apiKey,
+                    locale: targetLocale,
+                    misses: formattedMisses,
+                    path: normalizedPath,
+                }),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                console.error(`[Lovalingo] ❌ API Error ${response.status}:`, errorText);
+                throw new Error(`Miss reporting failed: ${response.status}`);
+            }
+            const result = await response.json();
+            console.log('[Lovalingo] ✅ Misses reported:', result);
+        }
+        catch (error) {
+            console.error('[Lovalingo] ❌ Error reporting misses:', error);
+        }
+    }
+    async saveExclusion(selector, type) {
+        try {
+            await fetch(`${this.apiBase}/functions/v1/exclusions?key=${this.apiKey}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ selector, type }),
+            });
+        }
+        catch (error) {
+            console.error('Error saving exclusion:', error);
+            throw error;
+        }
+    }
+    /**
+     * Real-time translation - calls Groq directly for instant translation
+     * Used when translation cache misses
+     */
+    async translateRealtime(contentHash, sourceText, sourceLocale, targetLocale) {
+        try {
+            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 (!response.ok) {
+                const errorText = await response.text();
+                console.error(`[Lovalingo] ❌ Real-time translation failed:`, errorText);
+                return null;
+            }
+            const result = await response.json();
+            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/dist/utils/hash.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Simple, fast hash function for content addressing
+ * Uses djb2 algorithm - good distribution, very fast
+ */
+export declare function hashContent(text: string): string;
+/**
+ * Hash with context (includes placeholders info for uniqueness)
+ */
+export declare function hashWithContext(text: string, placeholders?: Map<string, string>): string;

package/dist/utils/hash.js

@@ -0,0 +1,27 @@
+/**
+ * Simple, fast hash function for content addressing
+ * Uses djb2 algorithm - good distribution, very fast
+ */
+export function hashContent(text) {
+    if (!text || text.length === 0) {
+        return '0';
+    }
+    let hash = 5381;
+    for (let i = 0; i < text.length; i++) {
+        hash = ((hash << 5) + hash) + text.charCodeAt(i); // hash * 33 + c
+    }
+    // Convert to positive base36 string (compact representation)
+    return Math.abs(hash).toString(36);
+}
+/**
+ * Hash with context (includes placeholders info for uniqueness)
+ */
+export function hashWithContext(text, placeholders) {
+    const baseHash = hashContent(text);
+    if (!placeholders || placeholders.size === 0) {
+        return baseHash;
+    }
+    // Include placeholder keys in hash for uniqueness
+    const placeholderKeys = Array.from(placeholders.keys()).sort().join(',');
+    return hashContent(`${text}:${placeholderKeys}`);
+}

package/dist/utils/pathNormalizer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Path Normalization Utility
+ *
+ * Normalizes URL paths by replacing dynamic segments (UUIDs, IDs, slugs)
+ * with placeholders to enable translation bundle sharing across similar pages.
+ *
+ * Example:
+ *   /dashboard/projects/4458eb10-608c-4622-a92e-ec3ed2eeb524/setup
+ *   → /dashboard/projects/:id/setup
+ */
+export interface PathNormalizationRule {
+    pattern: string;
+    replacement: string;
+    includeSubpaths?: boolean;
+}
+export interface PathNormalizationConfig {
+    enabled: boolean;
+    rules?: PathNormalizationRule[];
+    supportedLocales?: string[];
+}
+/**
+ * Normalizes a path by replacing dynamic segments with placeholders
+ */
+export declare function normalizePath(path: string, config?: PathNormalizationConfig): string;
+/**
+ * Cleans path by removing locale prefix and trailing slashes
+ */
+export declare function cleanPath(path: string, supportedLocales?: string[]): string;
+/**
+ * Combined path processing: clean + normalize
+ */
+export declare function processPath(path: string, config?: PathNormalizationConfig): string;
+/**
+ * Detects if a path segment looks like a dynamic ID
+ */
+export declare function isDynamicSegment(segment: string): boolean;
+/**
+ * Analyzes a path and returns which segments are dynamic
+ */
+export interface PathAnalysis {
+    original: string;
+    normalized: string;
+    segments: Array<{
+        original: string;
+        normalized: string;
+        isDynamic: boolean;
+    }>;
+}
+export declare function analyzePath(path: string, supportedLocales?: string[]): PathAnalysis;

package/dist/utils/pathNormalizer.js

@@ -0,0 +1,114 @@
+/**
+ * Path Normalization Utility
+ *
+ * Normalizes URL paths by replacing dynamic segments (UUIDs, IDs, slugs)
+ * with placeholders to enable translation bundle sharing across similar pages.
+ *
+ * Example:
+ *   /dashboard/projects/4458eb10-608c-4622-a92e-ec3ed2eeb524/setup
+ *   → /dashboard/projects/:id/setup
+ */
+// Common patterns for dynamic segments
+const UUID_PATTERN = /[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/gi;
+const NUMERIC_ID_PATTERN = /\/\d+(?=\/|$)/g;
+const HASH_PATTERN = /\/[a-f0-9]{32,}(?=\/|$)/gi; // MD5, SHA hashes
+const ALPHANUMERIC_ID_PATTERN = /\/[a-z0-9]{20,}(?=\/|$)/gi; // Long random IDs
+/**
+ * Normalizes a path by replacing dynamic segments with placeholders
+ */
+export function normalizePath(path, config) {
+    if (config?.enabled === false) {
+        return path;
+    }
+    let normalized = path;
+    let shouldIncludeSubpaths = false;
+    // Apply automatic detection patterns
+    normalized = normalized.replace(UUID_PATTERN, ':id');
+    normalized = normalized.replace(HASH_PATTERN, ':hash');
+    normalized = normalized.replace(ALPHANUMERIC_ID_PATTERN, ':id');
+    normalized = normalized.replace(NUMERIC_ID_PATTERN, '/:id');
+    // Apply custom user-defined rules
+    if (config?.rules) {
+        for (const rule of config.rules) {
+            try {
+                const regex = new RegExp(rule.pattern, 'gi');
+                const beforeReplace = normalized;
+                normalized = normalized.replace(regex, rule.replacement);
+                // Track if this rule was applied and has includeSubpaths enabled
+                if (beforeReplace !== normalized && rule.includeSubpaths) {
+                    shouldIncludeSubpaths = true;
+                }
+            }
+            catch (error) {
+                console.warn('[PathNormalizer] Invalid pattern:', rule.pattern, error);
+            }
+        }
+    }
+    // Collapse consecutive :id placeholders (e.g., /:id/:id → /:id)
+    normalized = normalized.replace(/\/:id(\/):id/g, '/:id$1*');
+    // If includeSubpaths is enabled, replace everything after the first placeholder with /*
+    if (shouldIncludeSubpaths) {
+        // Find the first placeholder (:id, :hash, :slug, etc.)
+        const placeholderMatch = normalized.match(/(:[a-z]+)/);
+        if (placeholderMatch) {
+            const placeholderIndex = normalized.indexOf(placeholderMatch[0]);
+            const beforePlaceholder = normalized.substring(0, placeholderIndex + placeholderMatch[0].length);
+            normalized = beforePlaceholder + '/*';
+        }
+    }
+    return normalized;
+}
+/**
+ * Cleans path by removing locale prefix and trailing slashes
+ */
+export function cleanPath(path, supportedLocales) {
+    let cleaned = path;
+    // Strip locale prefix from path if it matches a supported locale
+    // e.g., /fr/pricing -> /pricing, /en -> /
+    if (supportedLocales && supportedLocales.length > 0) {
+        const segments = cleaned.split('/').filter(Boolean);
+        if (segments.length > 0 && supportedLocales.includes(segments[0])) {
+            // First segment is a valid locale - remove it
+            cleaned = '/' + segments.slice(1).join('/');
+            if (cleaned === '')
+                cleaned = '/';
+        }
+    }
+    // Remove trailing slash except for root
+    if (cleaned !== '/' && cleaned.endsWith('/')) {
+        cleaned = cleaned.slice(0, -1);
+    }
+    return cleaned;
+}
+/**
+ * Combined path processing: clean + normalize
+ */
+export function processPath(path, config) {
+    const cleaned = cleanPath(path, config?.supportedLocales);
+    const normalized = normalizePath(cleaned, config);
+    return normalized;
+}
+/**
+ * Detects if a path segment looks like a dynamic ID
+ */
+export function isDynamicSegment(segment) {
+    return (UUID_PATTERN.test(segment) ||
+        /^\d+$/.test(segment) ||
+        HASH_PATTERN.test(segment) ||
+        ALPHANUMERIC_ID_PATTERN.test(segment));
+}
+export function analyzePath(path, supportedLocales) {
+    const cleaned = cleanPath(path, supportedLocales);
+    const normalized = normalizePath(cleaned);
+    const originalSegments = cleaned.split('/').filter(Boolean);
+    const normalizedSegments = normalized.split('/').filter(Boolean);
+    return {
+        original: cleaned,
+        normalized,
+        segments: originalSegments.map((seg, idx) => ({
+            original: seg,
+            normalized: normalizedSegments[idx] || seg,
+            isDynamic: seg !== normalizedSegments[idx],
+        })),
+    };
+}

package/dist/utils/translator.d.ts

@@ -0,0 +1,80 @@
+import { Translation, Exclusion, MissedTranslation } from '../types';
+export declare class Translator {
+    private translationMap;
+    private exclusions;
+    private missedStrings;
+    private nonTranslatableTerms;
+    constructor();
+    /**
+     * Check if element is interactive (should be preserved as island)
+     */
+    private isInteractive;
+    /**
+     * Check if text contains actual translatable content
+     */
+    private isTranslatableText;
+    /**
+     * Check if element should be treated as semantic boundary
+     * even though it's not in the predefined SEMANTIC_BOUNDARIES set
+     *
+     * Phase 1: Conservative approach - only leaf elements (no element children)
+     * This catches cases like: <span>text</span>, <div>text</div>, etc.
+     */
+    private shouldTreatAsSemantic;
+    setTranslations(translations: Translation[]): void;
+    setExclusions(exclusions: Exclusion[]): void;
+    getMissedStrings(): MissedTranslation[];
+    clearMissedStrings(): void;
+    private isExcluded;
+    /**
+     * DOM-BASED EXTRACTION
+     * Uses DOM APIs to reliably parse and tokenize HTML
+     */
+    private extractTranslatableContent;
+    /**
+     * RECONSTRUCTION: Replace tokens with original HTML
+     */
+    private reconstructHTML;
+    /**
+     * Restore element to original HTML while preserving event listeners
+     */
+    private restoreElement;
+    /**
+     * Restore all elements to original state
+     */
+    restoreDOM(): void;
+    /**
+     * Mark all descendant elements with unique IDs before translation
+     * This allows us to reuse original DOM nodes (preserving event listeners)
+     */
+    private markElements;
+    /**
+     * After reconstruction, transplant original LIVE elements into new structure
+     * This preserves event listeners and framework connections
+     */
+    private transplantOriginalElements;
+    /**
+     * Directly update the parent element's children by transplanting from temp
+     * This avoids using innerHTML which would destroy event listeners
+     */
+    private updateElementChildren;
+    /**
+     * Update only text nodes within an element, preserving child elements
+     * Enhanced to handle nested structures recursively
+     */
+    private updateTextNodesOnly;
+    translateElement(element: HTMLElement): void;
+    /**
+     * Restore attribute to original value
+     */
+    private restoreAttribute;
+    /**
+     * Translate interactive element safely (preserves event handlers)
+     */
+    private translateInteractive;
+    /**
+     * Translate individual attributes
+     */
+    private translateAttribute;
+    translateDOM(): void;
+}