@lovalingo/lovalingo 0.0.11 → 0.0.13

package/README.md

@@ -1,11 +1,11 @@
-# @aixyte/Lovalingo
+# @lovalingo/lovalingo
 
 Seamless website translation for React and Next.js applications with **zero-flash rendering** and **automatic language routing**.
 
 ## Installation
 
 ```bash
-npm install @aixyte/Lovalingo react-router-dom
+npm install @lovalingo/lovalingo react-router-dom
 ```
 
 ## Quick Start
@@ -15,7 +15,7 @@ npm install @aixyte/Lovalingo react-router-dom
 **One-line setup** that automatically handles language routing like `/en/pricing`, `/fr/pricing`, `/de/pricing`:
 
 ```tsx
-import { LangRouter, LovalingoProvider } from '@aixyte/Lovalingo';
+import { LangRouter, LovalingoProvider } from '@lovalingo/lovalingo';
 import { Routes, Route } from 'react-router-dom';
 import { useRef } from 'react';
 
@@ -46,6 +46,24 @@ function App() {
 
 **Important:** Pass the same `navigateRef` to both `<LangRouter>` and `<LovalingoProvider>` for proper URL synchronization.
 
+**Common error (React Router v6):** If you see `LovalingoProvider is not a <Route> component`, you’re either:
+- on an older `@lovalingo/lovalingo` version (upgrade), or
+- you accidentally placed `<LovalingoProvider>` directly inside `<Routes>`.
+
+Correct:
+```tsx
+<LovalingoProvider ...>
+  <Routes>...</Routes>
+</LovalingoProvider>
+```
+
+Incorrect:
+```tsx
+<Routes>
+  <LovalingoProvider ... />
+</Routes>
+```
+
 URLs automatically work as:
 - `/en/`, `/en/home`, `/en/pricing`, `/en/about`
 - `/fr/`, `/fr/home`, `/fr/pricing`, `/fr/about`
@@ -56,7 +74,7 @@ URLs automatically work as:
 Use query parameters like `/pricing?t=fr`:
 
 ```tsx
-import { LovalingoProvider } from '@aixyte/Lovalingo';
+import { LovalingoProvider } from '@lovalingo/lovalingo';
 import { BrowserRouter } from 'react-router-dom';
 
 function App() {
@@ -79,7 +97,7 @@ function App() {
 
 ```tsx
 // app/layout.tsx
-import { LovalingoProvider } from '@aixyte/Lovalingo';
+import { LovalingoProvider } from '@lovalingo/lovalingo';
 
 export default function RootLayout({ children }) {
   return (
@@ -112,7 +130,7 @@ export default function RootLayout({ children }) {
   editMode={false}                    // Optional: Enable edit mode
   editKey="KeyE"                      // Optional: Keyboard shortcut for edit mode
   mode="dom"                          // Optional: 'dom' | 'context' (default: 'dom')
-  sitemap={true}                      // Optional: Auto-inject sitemap link (default: true) - NEW in v4.2.2
+  sitemap={true}                      // Optional: Auto-inject sitemap link (default: true) - NEW in v0.0.x
 >
   {children}
 </LovalingoProvider>
@@ -130,12 +148,12 @@ export default function RootLayout({ children }) {
   - SEO-optimized URLs
   - See [PATH_EXAMPLES.md](./PATH_EXAMPLES.md) for detailed examples
 
-## Path Mode Helpers (v4.2+)
+## Path Mode Helpers (v0.0.x+)
 
 ### LangLink - Language-Aware Links
 
 ```tsx
-import { LangLink } from '@aixyte/Lovalingo';
+import { LangLink } from '@lovalingo/lovalingo';
 
 function Navigation() {
   return (
@@ -151,7 +169,7 @@ function Navigation() {
 ### useLang - Get Current Language
 
 ```tsx
-import { useLang } from '@aixyte/Lovalingo';
+import { useLang } from '@lovalingo/lovalingo';
 
 function MyComponent() {
   const lang = useLang(); // 'en', 'fr', 'de', etc.
@@ -162,7 +180,7 @@ function MyComponent() {
 ### useLangNavigate - Programmatic Navigation
 
 ```tsx
-import { useLangNavigate } from '@aixyte/Lovalingo';
+import { useLangNavigate } from '@lovalingo/lovalingo';
 
 function MyComponent() {
   const navigate = useLangNavigate();
@@ -182,7 +200,7 @@ function MyComponent() {
 Access locale state and switching:
 
 ```tsx
-import { useLovalingo } from '@aixyte/Lovalingo';
+import { useLovalingo } from '@lovalingo/lovalingo';
 
 function MyComponent() {
   const { locale, setLocale, isLoading, config } = useLovalingo();
@@ -200,7 +218,7 @@ function MyComponent() {
 Manual translation control:
 
 ```tsx
-import { useLovalingoTranslate } from '@aixyte/Lovalingo';
+import { useLovalingoTranslate } from '@lovalingo/lovalingo';
 
 function MyComponent() {
   const { translateElement, translateDOM } = useLovalingoTranslate();
@@ -223,7 +241,7 @@ function MyComponent() {
 Edit mode for excluding elements:
 
 ```tsx
-import { useLovalingoEdit } from '@aixyte/Lovalingo';
+import { useLovalingoEdit } from '@lovalingo/lovalingo';
 
 function MyComponent() {
   const { editMode, toggleEditMode, excludeElement } = useLovalingoEdit();
@@ -246,11 +264,11 @@ function MyComponent() {
 - ✅ Works with React Router and Next.js
 - ✅ Edit mode for managing exclusions
 - ✅ Automatic translation miss detection
-- ✅ **Automatic multilingual sitemap generation (v4.2.2+)**
+- ✅ **Automatic multilingual sitemap generation (v0.0.x+)**
 
-## Automatic Sitemap (v4.2.2+)
+## Automatic Sitemap (v0.0.x+)
 
-Your multilingual sitemap is **automatically generated** with zero configuration. Just install `@aixyte/Lovalingo` and it works!
+Your multilingual sitemap is **automatically generated** with zero configuration. Just install `@lovalingo/lovalingo` and it works!
 
 ### Zero Configuration
 
@@ -264,7 +282,7 @@ Your multilingual sitemap is **automatically generated** with zero configuration
 </LovalingoProvider>
 
 // ✅ That's it! Sitemap exists automatically at:
-// https://mvbumiwzjytmxswfjgzn.supabase.co/functions/v1/generate-sitemap/aix_xxx
+// https://leuskvkajliuzalrlwhw.supabase.co/functions/v1/generate-sitemap/aix_xxx
 ```
 
 ### Features
@@ -304,7 +322,7 @@ Your multilingual sitemap is **automatically generated** with zero configuration
 # netlify.toml
 [[redirects]]
   from = "/sitemap.xml"
-  to = "https://mvbumiwzjytmxswfjgzn.supabase.co/functions/v1/generate-sitemap/YOUR_API_KEY"
+  to = "https://leuskvkajliuzalrlwhw.supabase.co/functions/v1/generate-sitemap/YOUR_API_KEY"
   status = 200
 ```
 
@@ -314,7 +332,7 @@ Your multilingual sitemap is **automatically generated** with zero configuration
 {
   "rewrites": [{
     "source": "/sitemap.xml",
-    "destination": "https://mvbumiwzjytmxswfjgzn.supabase.co/functions/v1/generate-sitemap/YOUR_API_KEY"
+    "destination": "https://leuskvkajliuzalrlwhw.supabase.co/functions/v1/generate-sitemap/YOUR_API_KEY"
   }]
 }
 ```
@@ -325,7 +343,7 @@ Your multilingual sitemap is **automatically generated** with zero configuration
 // app/sitemap.xml/route.ts
 export async function GET() {
   const res = await fetch(
-    'https://mvbumiwzjytmxswfjgzn.supabase.co/functions/v1/generate-sitemap/YOUR_API_KEY'
+    'https://leuskvkajliuzalrlwhw.supabase.co/functions/v1/generate-sitemap/YOUR_API_KEY'
   );
   return new Response(await res.text(), {
     headers: { 'Content-Type': 'application/xml' }

package/dist/components/AixsterProvider.js

@@ -37,6 +37,7 @@ navigateRef, // For path mode routing
         ? { ...pathNormalization, supportedLocales: allLocales }
         : pathNormalization;
     const apiRef = useRef(new LovalingoAPI(apiKey, apiBase, enhancedPathConfig));
+    const [entitlements, setEntitlements] = useState(() => apiRef.current.getEntitlements());
     const observerRef = useRef(null);
     const missReportIntervalRef = useRef(null);
     const retryTimeoutRef = useRef(null);
@@ -60,6 +61,88 @@ navigateRef, // For path mode routing
         pathNormalization,
         mode,
     };
+    const setDocumentLocale = useCallback((nextLocale) => {
+        try {
+            const html = document.documentElement;
+            if (!html)
+                return;
+            html.setAttribute("lang", nextLocale);
+            const rtlLocales = new Set(["ar", "he", "fa", "ur"]);
+            html.setAttribute("dir", rtlLocales.has(nextLocale) ? "rtl" : "ltr");
+        }
+        catch {
+            // ignore
+        }
+    }, []);
+    const updateSeoLinks = useCallback((activeLocale, hreflangEnabled) => {
+        try {
+            const head = document.head;
+            if (!head)
+                return;
+            // Remove old links inserted by Lovalingo
+            head.querySelectorAll('link[data-Lovalingo="hreflang"], link[data-Lovalingo="canonical"]').forEach((el) => el.remove());
+            const all = allLocales;
+            const url = new URL(window.location.href);
+            // Derive a locale-neutral base pathname for path routing
+            let basePathname = url.pathname;
+            if (routing === "path") {
+                const parts = basePathname.split("/").filter(Boolean);
+                if (parts.length > 0 && all.includes(parts[0])) {
+                    parts.shift();
+                }
+                basePathname = "/" + parts.join("/");
+                if (basePathname === "/") {
+                    // ok
+                }
+                else if (basePathname.endsWith("/") && basePathname.length > 1) {
+                    basePathname = basePathname.slice(0, -1);
+                }
+            }
+            const buildUrlForLocale = (localeForUrl) => {
+                const next = new URL(window.location.origin + basePathname + url.search + url.hash);
+                if (routing === "path") {
+                    const path = basePathname === "/" ? "" : basePathname;
+                    next.pathname = localeForUrl === defaultLocale ? `${path || "/"}` : `/${localeForUrl}${path}`;
+                    return next.toString();
+                }
+                // Query mode: keep pathname, set/remove locale param
+                next.searchParams.delete("t");
+                next.searchParams.delete("locale");
+                if (localeForUrl !== defaultLocale) {
+                    next.searchParams.set("t", localeForUrl);
+                }
+                return next.toString();
+            };
+            // Canonical should point to the current locale variant
+            const canonicalHref = buildUrlForLocale(activeLocale);
+            const canonical = document.createElement("link");
+            canonical.rel = "canonical";
+            canonical.href = canonicalHref;
+            canonical.setAttribute("data-Lovalingo", "canonical");
+            head.appendChild(canonical);
+            if (!hreflangEnabled)
+                return;
+            // hreflang alternates for each locale
+            all.forEach((loc) => {
+                const link = document.createElement("link");
+                link.rel = "alternate";
+                link.hreflang = loc;
+                link.href = buildUrlForLocale(loc);
+                link.setAttribute("data-Lovalingo", "hreflang");
+                head.appendChild(link);
+            });
+            // x-default -> default locale
+            const xDefault = document.createElement("link");
+            xDefault.rel = "alternate";
+            xDefault.hreflang = "x-default";
+            xDefault.href = buildUrlForLocale(defaultLocale);
+            xDefault.setAttribute("data-Lovalingo", "hreflang");
+            head.appendChild(xDefault);
+        }
+        catch (e) {
+            console.warn("[Lovalingo] updateSeoLinks() failed:", e);
+        }
+    }, [allLocales, defaultLocale, routing]);
     // Detect locale from URL or localStorage
     const detectLocale = useCallback(() => {
         // 1. Check URL first based on routing mode
@@ -92,6 +175,23 @@ navigateRef, // For path mode routing
         // 3. Default locale
         return defaultLocale;
     }, [allLocales, defaultLocale, routing]);
+    // Fetch entitlements early so SEO can be enabled even on default locale
+    useEffect(() => {
+        let cancelled = false;
+        (async () => {
+            const next = await apiRef.current.fetchEntitlements(detectLocale());
+            if (!cancelled && next)
+                setEntitlements(next);
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [detectLocale]);
+    // Keep <html lang> + canonical/hreflang in sync with routing + entitlements
+    useEffect(() => {
+        setDocumentLocale(locale);
+        updateSeoLinks(locale, Boolean(entitlements?.hreflangEnabled));
+    }, [locale, entitlements, setDocumentLocale, updateSeoLinks]);
     // Load translations and exclusions
     const loadData = useCallback(async (targetLocale, previousLocale, showOverlay = false) => {
         // Cancel any pending retry scan to prevent race conditions
@@ -106,6 +206,7 @@ navigateRef, // For path mode routing
                 setIsNavigationLoading(false);
             translatorRef.current.setTranslations([]);
             translatorRef.current.restoreDOM(); // Safe to restore when going back to source language
+            translatorRef.current.restoreHead();
             isNavigatingRef.current = false;
             return;
         }
@@ -121,6 +222,7 @@ navigateRef, // For path mode routing
             translatorRef.current.setTranslations(cachedTranslations);
             translatorRef.current.setExclusions(cachedExclusions);
             translatorRef.current.translateDOM();
+            translatorRef.current.translateHead();
             // Delayed retry scan to catch late-rendering content
             retryTimeoutRef.current = setTimeout(() => {
                 // Don't scan if we're navigating (prevents React conflicts)
@@ -129,6 +231,7 @@ navigateRef, // For path mode routing
                 }
                 console.log(`[Lovalingo] 🔄 Retry scan for late-rendering content`);
                 translatorRef.current.translateDOM();
+                translatorRef.current.translateHead();
                 // Immediately report any misses found
                 const missed = translatorRef.current.getMissedStrings();
                 if (missed.length > 0) {
@@ -157,12 +260,16 @@ navigateRef, // For path mode routing
                 apiRef.current.fetchTranslations(defaultLocale, targetLocale),
                 apiRef.current.fetchExclusions(),
             ]);
+            const nextEntitlements = apiRef.current.getEntitlements();
+            if (nextEntitlements)
+                setEntitlements(nextEntitlements);
             // Store in cache for next time
             translationCacheRef.current.set(cacheKey, translations);
             exclusionsCacheRef.current = exclusions;
             translatorRef.current.setTranslations(translations);
             translatorRef.current.setExclusions(exclusions);
             translatorRef.current.translateDOM();
+            translatorRef.current.translateHead();
             // Delayed retry scan to catch late-rendering content
             retryTimeoutRef.current = setTimeout(() => {
                 // Don't scan if we're navigating (prevents React conflicts)
@@ -171,6 +278,7 @@ navigateRef, // For path mode routing
                 }
                 console.log(`[Lovalingo] 🔄 Retry scan for late-rendering content`);
                 translatorRef.current.translateDOM();
+                translatorRef.current.translateHead();
                 // Immediately report any misses found
                 const missed = translatorRef.current.getMissedStrings();
                 if (missed.length > 0) {
@@ -281,6 +389,11 @@ navigateRef, // For path mode routing
         console.log(`[Lovalingo] v4.0.0 initialized (mode: ${mode})`);
         const initialLocale = detectLocale();
         setLocaleState(initialLocale);
+        // Fetch tier/entitlements early (so the badge can render even on default locale)
+        apiRef.current.fetchEntitlements(initialLocale).then((next) => {
+            if (next)
+                setEntitlements(next);
+        });
         // Only load data for DOM mode (context mode uses AutoTranslate)
         if (mode === 'dom') {
             loadData(initialLocale);
@@ -490,6 +603,8 @@ navigateRef, // For path mode routing
     };
     return (React.createElement(LovalingoContext.Provider, { value: contextValue },
         children,
-        React.createElement(LanguageSwitcher, { locales: allLocales, currentLocale: locale, onLocaleChange: setLocale, position: switcherPosition, offsetY: switcherOffsetY }),
+        React.createElement(LanguageSwitcher, { locales: allLocales, currentLocale: locale, onLocaleChange: setLocale, position: switcherPosition, offsetY: switcherOffsetY, branding: entitlements?.brandingRequired
+                ? { required: true, href: "https://lovalingo.com" }
+                : undefined }),
         React.createElement(NavigationOverlay, { isVisible: isNavigationLoading })));
 };

package/dist/components/LangRouter.js

@@ -54,7 +54,7 @@ export function LangRouter({ children, defaultLang, langs, navigateRef }) {
         React.createElement(NavigateExporter, { navigateRef: navigateRef }),
         React.createElement(Routes, null,
             React.createElement(Route, { path: ":lang/*", element: React.createElement(LangGuard, { defaultLang: defaultLang, langs: langs }) },
-                React.createElement(Route, { index: true, element: null }),
-                children),
+                React.createElement(Route, { index: true, element: React.createElement(React.Fragment, null, children) }),
+                React.createElement(Route, { path: "*", element: React.createElement(React.Fragment, null, children) })),
             React.createElement(Route, { path: "*", element: React.createElement(Navigate, { to: `/${defaultLang}`, replace: true }) }))));
 }

package/dist/components/LanguageSwitcher.d.ts

@@ -5,6 +5,11 @@ interface LanguageSwitcherProps {
     onLocaleChange: (locale: string) => void;
     position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
     offsetY?: number;
+    branding?: {
+        required?: boolean;
+        label?: string;
+        href?: string;
+    };
 }
 export declare const LanguageSwitcher: React.FC<LanguageSwitcherProps>;
 export {};

package/dist/components/LanguageSwitcher.js

@@ -22,7 +22,7 @@ const LANGUAGE_FLAGS = {
     no: '🇳🇴',
     fi: '🇫🇮',
 };
-export const LanguageSwitcher = ({ locales, currentLocale, onLocaleChange, position = 'bottom-right', offsetY = 20, }) => {
+export const LanguageSwitcher = ({ locales, currentLocale, onLocaleChange, position = 'bottom-right', offsetY = 20, branding, }) => {
     const [isOpen, setIsOpen] = useState(false);
     const containerRef = useRef(null);
     const isRight = position.endsWith('right');
@@ -104,13 +104,37 @@ export const LanguageSwitcher = ({ locales, currentLocale, onLocaleChange, posit
         pointerEvents: isOpen ? 'auto' : 'none',
         background: 'rgba(26, 26, 26, 0.93)',
         backdropFilter: 'blur(12px)',
-        borderRadius: '9999px',
-        padding: '8px 14px',
+        borderRadius: '16px',
+        padding: '10px 12px',
         display: 'flex',
+        flexDirection: 'column',
         gap: '10px',
         boxShadow: '0 8px 24px rgba(0, 0, 0, 0.3), inset 0 0 1px rgba(255, 255, 255, 0.1)',
         transition: 'opacity 0.25s ease, transform 0.25s ease',
     };
+    const localeRowStyles = {
+        display: 'flex',
+        gap: '10px',
+        padding: '0 2px',
+    };
+    const badgeRowStyles = {
+        display: 'flex',
+        alignItems: 'center',
+        gap: '8px',
+        paddingTop: '8px',
+        borderTop: '1px solid rgba(255, 255, 255, 0.12)',
+        fontSize: '12px',
+        color: 'rgba(255, 255, 255, 0.82)',
+        userSelect: 'none',
+        whiteSpace: 'nowrap',
+    };
+    const badgeLinkStyles = {
+        color: 'rgba(255, 255, 255, 0.92)',
+        textDecoration: 'none',
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: '6px',
+    };
     const flagButtonStyles = (locale) => ({
         pointerEvents: 'auto',
         width: '32px',
@@ -141,22 +165,42 @@ export const LanguageSwitcher = ({ locales, currentLocale, onLocaleChange, posit
                         ? '-2px 0 8px rgba(0, 0, 0, 0.2), inset 0 0 1px rgba(255, 255, 255, 0.1)'
                         : '2px 0 8px rgba(0, 0, 0, 0.2), inset 0 0 1px rgba(255, 255, 255, 0.1)';
                 }, "aria-label": "Open language switcher", "aria-expanded": isOpen }, LANGUAGE_FLAGS[currentLocale] || '🌐'),
-            React.createElement("div", { style: panelStyles, role: "toolbar", "aria-label": "Language options" }, orderedLocales.map((locale) => (React.createElement("button", { key: locale, style: flagButtonStyles(locale), onClick: (e) => {
-                    e.stopPropagation();
-                    if (locale === currentLocale) {
-                        setIsOpen(false);
-                    }
-                    else {
-                        onLocaleChange(locale);
-                        setIsOpen(false);
-                    }
-                }, onMouseEnter: (e) => {
-                    if (locale !== currentLocale) {
-                        e.currentTarget.style.filter = 'brightness(1.3)';
-                    }
-                    e.currentTarget.style.transform = 'scale(1.1)';
-                }, onMouseLeave: (e) => {
-                    e.currentTarget.style.filter = 'brightness(1)';
-                    e.currentTarget.style.transform = 'scale(1)';
-                }, "aria-label": `Switch to ${locale.toUpperCase()}`, title: locale.toUpperCase(), tabIndex: isOpen ? 0 : -1 }, LANGUAGE_FLAGS[locale] || '🏳️')))))));
+            React.createElement("div", { style: panelStyles, role: "toolbar", "aria-label": "Language options" },
+                React.createElement("div", { style: localeRowStyles }, orderedLocales.map((locale) => (React.createElement("button", { key: locale, style: flagButtonStyles(locale), onClick: (e) => {
+                        e.stopPropagation();
+                        if (locale === currentLocale) {
+                            setIsOpen(false);
+                        }
+                        else {
+                            onLocaleChange(locale);
+                            setIsOpen(false);
+                        }
+                    }, onMouseEnter: (e) => {
+                        if (locale !== currentLocale) {
+                            e.currentTarget.style.filter = 'brightness(1.3)';
+                        }
+                        e.currentTarget.style.transform = 'scale(1.1)';
+                    }, onMouseLeave: (e) => {
+                        e.currentTarget.style.filter = 'brightness(1)';
+                        e.currentTarget.style.transform = 'scale(1)';
+                    }, "aria-label": `Switch to ${locale.toUpperCase()}`, title: locale.toUpperCase(), tabIndex: isOpen ? 0 : -1 }, LANGUAGE_FLAGS[locale] || '🏳️')))),
+                branding?.required && (React.createElement("div", { style: badgeRowStyles, "aria-label": "Lovalingo branding" },
+                    React.createElement("a", { href: branding.href || 'https://lovalingo.com', target: "_blank", rel: "noreferrer", style: badgeLinkStyles, tabIndex: isOpen ? 0 : -1, "aria-label": "Localized by Lovalingo", title: "Localized by Lovalingo" },
+                        React.createElement("span", { style: {
+                                width: '16px',
+                                height: '16px',
+                                borderRadius: '5px',
+                                background: '#6BD63D',
+                                display: 'inline-flex',
+                                alignItems: 'center',
+                                justifyContent: 'center',
+                                boxShadow: 'inset 0 0 0 1px rgba(0,0,0,0.25)',
+                                flexShrink: 0,
+                            } },
+                            React.createElement("svg", { width: "10", height: "10", viewBox: "0 0 24 24", fill: "none", "aria-hidden": "true" },
+                                React.createElement("path", { d: "M9 5a2 2 0 0 1 2 2v10h8a2 2 0 1 1 0 4H9a2 2 0 0 1-2-2V7a2 2 0 0 1 2-2Z", fill: "#0D0D0D" }))),
+                        React.createElement("span", null,
+                            branding.label || 'Localized by',
+                            " ",
+                            React.createElement("strong", { style: { color: 'white' } }, "Lovalingo")))))))));
 };

package/dist/utils/api.d.ts

@@ -1,10 +1,22 @@
 import { Translation, Exclusion, MissedTranslation } from '../types';
 import { PathNormalizationConfig } from './pathNormalizer';
+export interface ProjectEntitlements {
+    tier: 'starter' | 'startup' | 'global';
+    maxTargetLocales: number;
+    allowedTargetLocales: string[];
+    brandingRequired: boolean;
+    hreflangEnabled: boolean;
+}
 export declare class LovalingoAPI {
     private apiKey;
     private apiBase;
     private pathConfig?;
+    private entitlements;
     constructor(apiKey: string, apiBase: string, pathConfig?: PathNormalizationConfig);
+    private hasApiKey;
+    private warnMissingApiKey;
+    getEntitlements(): ProjectEntitlements | null;
+    fetchEntitlements(localeHint: string): Promise<ProjectEntitlements | null>;
     fetchTranslations(sourceLocale: string, targetLocale: string): Promise<Translation[]>;
     fetchExclusions(): Promise<Exclusion[]>;
     reportMisses(misses: MissedTranslation[], sourceLocale: string, targetLocale: string): Promise<void>;

package/dist/utils/api.js

@@ -1,18 +1,57 @@
 import { processPath } from './pathNormalizer';
 export class LovalingoAPI {
     constructor(apiKey, apiBase, pathConfig) {
+        this.entitlements = null;
         this.apiKey = apiKey;
         this.apiBase = apiBase;
         this.pathConfig = pathConfig;
     }
+    hasApiKey() {
+        return typeof this.apiKey === 'string' && this.apiKey.trim().length > 0;
+    }
+    warnMissingApiKey(action) {
+        // Avoid hard-crashing apps; make the failure mode obvious.
+        console.warn(`[Lovalingo] Missing apiKey: ${action} was skipped. Pass apiKey to <LovalingoProvider apiKey="..."> (or set VITE_LOVALINGO_API_KEY).`);
+    }
+    getEntitlements() {
+        return this.entitlements;
+    }
+    async fetchEntitlements(localeHint) {
+        try {
+            if (!this.hasApiKey()) {
+                this.warnMissingApiKey('fetchEntitlements');
+                return null;
+            }
+            const normalizedPath = processPath(window.location.pathname, this.pathConfig);
+            const response = await fetch(`${this.apiBase}/functions/v1/bundle?key=${this.apiKey}&locale=${localeHint}&path=${normalizedPath}`);
+            if (!response.ok)
+                return null;
+            const data = await response.json();
+            if (data?.entitlements) {
+                this.entitlements = data.entitlements;
+                return this.entitlements;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
     async fetchTranslations(sourceLocale, targetLocale) {
         try {
+            if (!this.hasApiKey()) {
+                this.warnMissingApiKey('fetchTranslations');
+                return [];
+            }
             // 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();
+            if (data?.entitlements) {
+                this.entitlements = data.entitlements;
+            }
             // Convert map to array of Translation objects
             if (data.map && typeof data.map === 'object') {
                 return Object.entries(data.map).map(([source_text, translated_text]) => ({
@@ -31,6 +70,10 @@ export class LovalingoAPI {
     }
     async fetchExclusions() {
         try {
+            if (!this.hasApiKey()) {
+                this.warnMissingApiKey('fetchExclusions');
+                return [];
+            }
             const response = await fetch(`${this.apiBase}/functions/v1/exclusions?key=${this.apiKey}`);
             if (!response.ok)
                 throw new Error('Failed to fetch exclusions');
@@ -45,6 +88,10 @@ export class LovalingoAPI {
     }
     async reportMisses(misses, sourceLocale, targetLocale) {
         try {
+            if (!this.hasApiKey()) {
+                this.warnMissingApiKey('reportMisses');
+                return;
+            }
             // Use path normalization utility
             const normalizedPath = processPath(window.location.pathname, this.pathConfig);
             // CRITICAL: Filter out invalid misses
@@ -94,6 +141,10 @@ export class LovalingoAPI {
     }
     async saveExclusion(selector, type) {
         try {
+            if (!this.hasApiKey()) {
+                this.warnMissingApiKey('saveExclusion');
+                return;
+            }
             await fetch(`${this.apiBase}/functions/v1/exclusions?key=${this.apiKey}`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
@@ -111,6 +162,10 @@ export class LovalingoAPI {
      */
     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',

package/dist/utils/translator.d.ts

@@ -77,4 +77,12 @@ export declare class Translator {
      */
     private translateAttribute;
     translateDOM(): void;
+    /**
+     * Translate SEO-relevant <head> elements (title + meta content) that are not part of the body DOM tree.
+     */
+    translateHead(): void;
+    /**
+     * Restore original <head> SEO content (title + meta content) after returning to default locale.
+     */
+    restoreHead(): void;
 }

package/dist/utils/translator.js

@@ -763,4 +763,103 @@ export class Translator {
         const elapsed = performance.now() - startTime;
         console.log(`[Lovalingo] 🏁 translateDOM() complete in ${elapsed.toFixed(2)}ms. Missed: ${this.missedStrings.size}`);
     }
+    /**
+     * Translate SEO-relevant <head> elements (title + meta content) that are not part of the body DOM tree.
+     */
+    translateHead() {
+        try {
+            const head = document.head;
+            if (!head)
+                return;
+            const titleEl = head.querySelector("title");
+            if (titleEl) {
+                const originalKey = "data-Lovalingo-title-original";
+                if (!titleEl.getAttribute(originalKey)) {
+                    titleEl.setAttribute(originalKey, titleEl.textContent || "");
+                }
+                const sourceTitle = (titleEl.getAttribute(originalKey) || "").trim();
+                if (sourceTitle && this.isTranslatableText(sourceTitle)) {
+                    const translated = this.translationMap.get(sourceTitle);
+                    if (translated) {
+                        titleEl.textContent = translated;
+                    }
+                    else if (sourceTitle.length < 500) {
+                        this.missedStrings.set(sourceTitle, {
+                            text: sourceTitle,
+                            raw: sourceTitle,
+                            placeholderMap: {},
+                            semanticContext: "title",
+                        });
+                    }
+                }
+            }
+            const metaSelectors = [
+                'meta[name="description"]',
+                'meta[property="og:title"]',
+                'meta[property="og:description"]',
+                'meta[name="twitter:title"]',
+                'meta[name="twitter:description"]',
+            ];
+            metaSelectors.forEach((selector) => {
+                head.querySelectorAll(selector).forEach((node) => {
+                    if (!(node instanceof HTMLMetaElement))
+                        return;
+                    const originalAttrKey = "data-Lovalingo-content-original";
+                    if (!node.getAttribute(originalAttrKey)) {
+                        const content = (node.getAttribute("content") || "").trim();
+                        node.setAttribute(originalAttrKey, content);
+                    }
+                    const sourceValue = (node.getAttribute(originalAttrKey) || "").trim();
+                    if (!sourceValue || sourceValue.length <= 1)
+                        return;
+                    if (!this.isTranslatableText(sourceValue))
+                        return;
+                    const translated = this.translationMap.get(sourceValue);
+                    if (translated) {
+                        node.setAttribute("content", translated);
+                    }
+                    else if (sourceValue.length < 500) {
+                        const context = selector.includes("description") ? "meta-description" : "meta-title";
+                        this.missedStrings.set(sourceValue, {
+                            text: sourceValue,
+                            raw: sourceValue,
+                            placeholderMap: {},
+                            semanticContext: context,
+                        });
+                    }
+                });
+            });
+        }
+        catch (e) {
+            console.warn("[Lovalingo] translateHead() failed:", e);
+        }
+    }
+    /**
+     * Restore original <head> SEO content (title + meta content) after returning to default locale.
+     */
+    restoreHead() {
+        try {
+            const head = document.head;
+            if (!head)
+                return;
+            const titleEl = head.querySelector("title");
+            if (titleEl) {
+                const original = titleEl.getAttribute("data-Lovalingo-title-original");
+                if (original !== null) {
+                    titleEl.textContent = original;
+                }
+            }
+            head.querySelectorAll('meta[data-Lovalingo-content-original]').forEach((node) => {
+                if (!(node instanceof HTMLMetaElement))
+                    return;
+                const original = node.getAttribute("data-Lovalingo-content-original");
+                if (original !== null) {
+                    node.setAttribute("content", original);
+                }
+            });
+        }
+        catch (e) {
+            console.warn("[Lovalingo] restoreHead() failed:", e);
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovalingo/lovalingo",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "React translation library with automatic routing, real-time AI translation, and zero-flash rendering. One-line language routing setup.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",