npm - @dabalabs/lang - Versions diffs - 0.0.6-beta → 0.0.8-beta - Mend

@dabalabs/lang 0.0.6-beta → 0.0.8-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/dist/dabalang.d.cts CHANGED Viewed

@@ -30,6 +30,17 @@ interface DabaLangOptions {
      *   project's languages directly, anchored to the trigger — for sites
      *   that want the languages visible in one click, no overlay. */
     view?: "modal" | "dropdown";
+    /**
+     * Translate each page into every configured language in the background,
+     * not just the one the visitor is reading.
+     *
+     * The gateway caches by content hash, so this makes the first visitor to
+     * a page pay for it once and everyone after — in any language — get it
+     * instantly. Off by default: it is extra requests per page view, and
+     * that should be a site owner's decision rather than something the
+     * widget starts doing on its own.
+     */
+    prewarm?: boolean;
     onError?: (error: DabaLangError) => void;
     onLanguageChange?: (langCode: string) => void;
 }
@@ -89,6 +100,7 @@ declare class DabaLang {
     private metadata;
     private pathRouter;
     private navWatcher;
+    private prewarmer;
     /** Tail of the re-translation chain; see retranslateCurrentPage. */
     private retranslating;
     /** Currently active language (null = original). Tracked here rather
@@ -104,6 +116,8 @@ declare class DabaLang {
      * A no-op in the source language — there is nothing to apply — and on
      * a site-translated page, where the page already *is* the translation.
      */
+    /** Warms every configured language except the one on screen. */
+    private startPrewarm;
     private retranslateCurrentPage;
     /** True when the site serves this language's content itself (CMS,
      * localized build): a pre-translated ("developer") language. Combined
@@ -180,4 +194,19 @@ declare class PathRouter {
     private matchPrefix;
 }
-export { DabaLang, type DabaLangError, type DabaLangOptions, type LanguageConfig, PathRouter, type ProjectMetadata, type TranslationResult };
+/**
+ * Call as early as possible — ideally an inline `<script>` in `<head>`,
+ * before the body parses. Safe to call more than once.
+ *
+ * Text is hidden with `visibility`, not `display`: layout still happens,
+ * so nothing reflows when it is revealed and the page does not jump.
+ */
+declare function preventFlash(projectId: string): void;
+/** Reveals the page. Idempotent, and safe to call before preventFlash. */
+declare function reveal(): void;
+/** The inline snippet, for sites that want this without loading the widget
+ *  first. Kept in one place so the published copy cannot drift from the
+ *  implementation above. */
+declare function inlineSnippet(projectId: string): string;
+export { DabaLang, type DabaLangError, type DabaLangOptions, type LanguageConfig, PathRouter, type ProjectMetadata, type TranslationResult, inlineSnippet, preventFlash, reveal };

package/dist/dabalang.d.ts CHANGED Viewed

@@ -30,6 +30,17 @@ interface DabaLangOptions {
      *   project's languages directly, anchored to the trigger — for sites
      *   that want the languages visible in one click, no overlay. */
     view?: "modal" | "dropdown";
+    /**
+     * Translate each page into every configured language in the background,
+     * not just the one the visitor is reading.
+     *
+     * The gateway caches by content hash, so this makes the first visitor to
+     * a page pay for it once and everyone after — in any language — get it
+     * instantly. Off by default: it is extra requests per page view, and
+     * that should be a site owner's decision rather than something the
+     * widget starts doing on its own.
+     */
+    prewarm?: boolean;
     onError?: (error: DabaLangError) => void;
     onLanguageChange?: (langCode: string) => void;
 }
@@ -89,6 +100,7 @@ declare class DabaLang {
     private metadata;
     private pathRouter;
     private navWatcher;
+    private prewarmer;
     /** Tail of the re-translation chain; see retranslateCurrentPage. */
     private retranslating;
     /** Currently active language (null = original). Tracked here rather
@@ -104,6 +116,8 @@ declare class DabaLang {
      * A no-op in the source language — there is nothing to apply — and on
      * a site-translated page, where the page already *is* the translation.
      */
+    /** Warms every configured language except the one on screen. */
+    private startPrewarm;
     private retranslateCurrentPage;
     /** True when the site serves this language's content itself (CMS,
      * localized build): a pre-translated ("developer") language. Combined
@@ -180,4 +194,19 @@ declare class PathRouter {
     private matchPrefix;
 }
-export { DabaLang, type DabaLangError, type DabaLangOptions, type LanguageConfig, PathRouter, type ProjectMetadata, type TranslationResult };
+/**
+ * Call as early as possible — ideally an inline `<script>` in `<head>`,
+ * before the body parses. Safe to call more than once.
+ *
+ * Text is hidden with `visibility`, not `display`: layout still happens,
+ * so nothing reflows when it is revealed and the page does not jump.
+ */
+declare function preventFlash(projectId: string): void;
+/** Reveals the page. Idempotent, and safe to call before preventFlash. */
+declare function reveal(): void;
+/** The inline snippet, for sites that want this without loading the widget
+ *  first. Kept in one place so the published copy cannot drift from the
+ *  implementation above. */
+declare function inlineSnippet(projectId: string): string;
+export { DabaLang, type DabaLangError, type DabaLangOptions, type LanguageConfig, PathRouter, type ProjectMetadata, type TranslationResult, inlineSnippet, preventFlash, reveal };

package/dist/dabalang.js CHANGED Viewed

@@ -143,6 +143,35 @@ async function submitCorrection(gatewayUrl, projectId, apiKey, targetLang, sourc
   await parseOrThrow(response);
 }
+// src/translation-cache.ts
+var PREFIX = "dabalang:tcache:";
+var VERSION = 1;
+var MAX_ENTRY_BYTES = 512 * 1024;
+function key(projectId, lang) {
+  return `${PREFIX}${projectId}:${lang}`;
+}
+function readCachedTranslations(projectId, lang) {
+  try {
+    const raw = window.localStorage.getItem(key(projectId, lang));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || parsed.v !== VERSION || typeof parsed.t !== "object") return null;
+    return new Map(Object.entries(parsed.t));
+  } catch {
+    return null;
+  }
+}
+function writeCachedTranslations(projectId, lang, translations) {
+  try {
+    if (translations.size === 0) return;
+    const payload = { v: VERSION, t: Object.fromEntries(translations) };
+    const serialised = JSON.stringify(payload);
+    if (serialised.length > MAX_ENTRY_BYTES) return;
+    window.localStorage.setItem(key(projectId, lang), serialised);
+  } catch {
+  }
+}
 // src/dom/ignore.ts
 var IGNORE_ATTR = "data-dabalang-ignore";
 var SENSITIVE_ELEMENT_SELECTOR = `[${IGNORE_ATTR}], input[type="password"], input[type="hidden"], [autocomplete="current-password"], [autocomplete="new-password"], [autocomplete^="cc-"]`;
@@ -273,8 +302,63 @@ var TranslationApplier = class {
     }
     return null;
   }
+  /** Writes every translation this map covers into the DOM. */
+  paint(translations) {
+    let painted = 0;
+    for (const [sourceText, nodes] of this.groups) {
+      const translated = translations.get(sourceText);
+      if (translated === void 0) continue;
+      for (const node of nodes) node.textContent = translated;
+      painted += 1;
+    }
+    return painted;
+  }
+  /** True when every string on this page is already translated for
+   *  `targetLang`, so warming it would be a request that changes nothing. */
+  isFullyCached(targetLang) {
+    const cached = this.fetchedLanguages.get(targetLang) ?? readCachedTranslations(this.projectId, targetLang) ?? void 0;
+    if (!cached) return false;
+    return this.sourceTexts().every((t) => cached.has(t));
+  }
+  /**
+   * Translates this page into `targetLang` WITHOUT touching the DOM.
+   *
+   * Used to warm languages the visitor is not reading. The gateway caches
+   * by content hash, so the first visitor to a page pays for it and every
+   * later visitor — in any language — gets it instantly. Painting here
+   * would replace the text the visitor is currently reading with a
+   * language they did not ask for, so this is deliberately fetch-only and
+   * shares nothing with applyLanguage beyond the cache it fills.
+   */
+  async warmLanguage(targetLang) {
+    const existing = this.fetchedLanguages.get(targetLang) ?? readCachedTranslations(this.projectId, targetLang) ?? /* @__PURE__ */ new Map();
+    const missing = this.sourceTexts().filter((t) => !existing.has(t));
+    if (missing.length === 0) {
+      this.fetchedLanguages.set(targetLang, existing);
+      return;
+    }
+    const results = await batchTranslate(
+      this.gatewayUrl,
+      this.projectId,
+      this.apiKey,
+      targetLang,
+      missing
+    );
+    for (const r of results) existing.set(r.sourceText, r.translatedText);
+    this.fetchedLanguages.set(targetLang, existing);
+    writeCachedTranslations(this.projectId, targetLang, existing);
+  }
   async applyLanguage(targetLang) {
-    const cached = this.fetchedLanguages.get(targetLang);
+    let cached = this.fetchedLanguages.get(targetLang);
+    if (!cached) {
+      const stored = readCachedTranslations(this.projectId, targetLang);
+      if (stored && stored.size > 0) {
+        cached = stored;
+        this.fetchedLanguages.set(targetLang, stored);
+        this.paint(stored);
+        this.activeLang = targetLang;
+      }
+    }
     const allTexts = this.sourceTexts();
     const missing = cached ? allTexts.filter((t) => !cached.has(t)) : allTexts;
     if (missing.length > 0) {
@@ -282,13 +366,9 @@ var TranslationApplier = class {
       const map = cached ?? /* @__PURE__ */ new Map();
       for (const r of results) map.set(r.sourceText, r.translatedText);
       this.fetchedLanguages.set(targetLang, map);
+      writeCachedTranslations(this.projectId, targetLang, map);
     }
-    const translations = this.fetchedLanguages.get(targetLang);
-    for (const [sourceText, nodes] of this.groups) {
-      const translated = translations.get(sourceText);
-      if (translated === void 0) continue;
-      for (const node of nodes) node.textContent = translated;
-    }
+    this.paint(this.fetchedLanguages.get(targetLang));
     this.activeLang = targetLang;
   }
   restoreOriginal() {
@@ -600,10 +680,10 @@ var PathRouter = class {
 };
 // src/preference.ts
-var PREFIX = "dabalang:lang:";
+var PREFIX2 = "dabalang:lang:";
 function readPreferredLanguage(projectId) {
   try {
-    return window.localStorage.getItem(PREFIX + projectId);
+    return window.localStorage.getItem(PREFIX2 + projectId);
   } catch {
     return null;
   }
@@ -611,14 +691,101 @@ function readPreferredLanguage(projectId) {
 function writePreferredLanguage(projectId, langCode) {
   try {
     if (langCode === null) {
-      window.localStorage.removeItem(PREFIX + projectId);
+      window.localStorage.removeItem(PREFIX2 + projectId);
     } else {
-      window.localStorage.setItem(PREFIX + projectId, langCode);
+      window.localStorage.setItem(PREFIX2 + projectId, langCode);
     }
   } catch {
   }
 }
+// src/prevent-flash.ts
+var STYLE_ID = "dabalang-prevent-flash";
+var READY_ATTR = "data-dabalang-ready";
+var PREF_PREFIX = "dabalang:lang:";
+var MAX_HIDE_MS = 1200;
+function preventFlash(projectId) {
+  if (typeof document === "undefined") return;
+  let preferred = null;
+  try {
+    preferred = window.localStorage.getItem(PREF_PREFIX + projectId);
+  } catch {
+    return;
+  }
+  if (!preferred) return;
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = `html:not([${READY_ATTR}]) body :not([data-dabalang-ignore]):not([data-dabalang-ignore] *) { visibility: hidden !important; }html:not([${READY_ATTR}]) body [data-dabalang-ignore], html:not([${READY_ATTR}]) body [data-dabalang-ignore] * { visibility: visible !important; }`;
+  (document.head || document.documentElement).appendChild(style);
+  window.setTimeout(reveal, MAX_HIDE_MS);
+}
+function reveal() {
+  if (typeof document === "undefined") return;
+  document.documentElement.setAttribute(READY_ATTR, "");
+}
+function inlineSnippet(projectId) {
+  return `<script>(function(){try{if(!localStorage.getItem('${PREF_PREFIX}${projectId}'))return;var s=document.createElement('style');s.id='${STYLE_ID}';s.textContent='html:not([${READY_ATTR}]) body :not([data-dabalang-ignore]):not([data-dabalang-ignore] *){visibility:hidden!important}';(document.head||document.documentElement).appendChild(s);setTimeout(function(){document.documentElement.setAttribute('${READY_ATTR}','')},${MAX_HIDE_MS});}catch(e){}})();</script>`;
+}
+// src/prewarm.ts
+var GAP_MS = 600;
+function whenIdle(fn) {
+  const ric = window.requestIdleCallback;
+  if (typeof ric === "function") {
+    ric(fn, { timeout: 3e3 });
+  } else {
+    window.setTimeout(fn, 1200);
+  }
+}
+function warmOrder(targetLanguages, activeLang) {
+  return targetLanguages.filter((code) => code !== activeLang);
+}
+var Prewarmer = class {
+  constructor(target) {
+    this.target = target;
+    this.running = false;
+    this.cancelled = false;
+  }
+  /**
+   * Warms `languages` one at a time. Calling again while a run is in
+   * flight cancels the old one first, so a visitor clicking quickly
+   * through pages warms the page they landed on rather than queueing up
+   * every page they passed through.
+   */
+  start(languages) {
+    this.cancel();
+    const queue = languages.filter((lang) => !this.target.isFullyCached(lang));
+    if (queue.length === 0) return;
+    this.cancelled = false;
+    whenIdle(() => {
+      if (this.cancelled) return;
+      void this.run(queue);
+    });
+  }
+  async run(queue) {
+    if (this.running) return;
+    this.running = true;
+    try {
+      for (const lang of queue) {
+        if (this.cancelled) return;
+        try {
+          await this.target.warm(lang);
+        } catch {
+        }
+        if (this.cancelled) return;
+        await new Promise((r) => window.setTimeout(r, GAP_MS));
+      }
+    } finally {
+      this.running = false;
+    }
+  }
+  /** Stops after the language currently in flight. */
+  cancel() {
+    this.cancelled = true;
+  }
+};
 // src/ui/flag-svgs.ts
 var FLAG_IMAGES = {
   us: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADwAAAAtCAMAAADFqPh+AAACClBMVEUZL13jrrHw0tQaMF7nurzsxsj46uv///+9PUT03t++rLjhqKv68PCcOkkfNWEwQ20lOmUcMV8dMmAvQ2wxRW4nPGc6TXXR1d9hcJAeNGE4S3MeM2A3SnI2SXEkOWV+iqQtQWs+UHdwfptndZQrP2o8T3Zba4s5THQoPWi+xNFSYoUgNmJKW39jcpEhNmPx8vVPYINZaYozR29ebY1reZc9UHbh5OpYaIkpPmiYordfb49IWX5MXYGTnbPS1t98iaM0R3BVZYcwRG4uQmwyRm8sQGqbpLh/i6WosMEqPmnn6e6Qm7FDVXtNXoLV2eFCVXqAjKU1SHE5THMmOmZod5XQ1d6apLiMl64iN2OGkqqHk6vc3+Z9iqTJztmcpbnN0tyPmrBUZIbf4ui5j5w/UXjNydO+nqnIu8UbMV7AxtNWZojCp7N4haD9/f7o6u6NmK8bMV+1vMvZ3eTM0dv8/f16hqGiq75sepccMl+eqLvr7fHL0Nr7/PyUnrNzgZ2WoLU7TnVldJJGWH3k5+yEkKmCjqeRm7G7ws/X2+Owt8dgb497iKJOX4JBU3nx8/Xi5etAUnh5haDHzNi6wc9ebo6OmbDFy9b09fd0gZ3Fsb2ep7onO2dicZAjOGSmrsBHWX3U2OFxf5tEVnustMW3vsyIk6tJWn9RYoTCyNR3hJ+oscJygJydprrny88smqUCAAAACXBIWXMAAC4jAAAuIwF4pT92AAACiUlEQVRIx9WURXMbQRCFOxk7tgMLkqyILLAtiy2DZEuKZWaMmSnMzMzMzMzwH/NGqcptd6uyB5Xf4aup3p6dhukh0tSafCXhY5nAXSwc21KcvY5/Bk61zaUb2hlR3e4yuO7dIxKVP3loJyqKdsDQES1SP3lTnIzkdphAr0cGPR5A8PpAn1egjauUlInNdrCYhz8aJpKnAm1Epgc3EU1wNMi/rs1TEj4ysp+uBAfGWsCRzwB7bAFtYzZQdbO0Kw4Pt0vkITS8JApZmpCz39UIQ6PLT5tXKwm+9ePw8jytA13TTkTy6SOWhd08leLuQvWCiSKZKeFsA0W3zIb+GoQEp5gQ1DcTDR04DKZqcLicnnUTVdVPIpWmu02al8RAhoYgeM/VAj56RjJj92uxdMw4QNqSoyRckvQOnOJN3sZ/Ks6ibBMN7604PInGUThZpVpttn09vIpqesEzJ2XwzRwg9JeAJf2Cep+dEq0jJ+OUJmTDB5IkesusQsYgWGlrgZIyBTNfvASej/ahYC/etaC901eQSu2dWs2CFZIhEgbPWdxgMEWv7ezVLSwHbwyC6lO1vxinXAj08RSvomChuR4+VYFqGKoDGlPVfhRove4BI0fwH5riFbR2VoKVnVbamaskPhisPObHMAzHnIyONUcExkIjpfuISTEJZvVqExlPXOYhnhoAj18bJuqq6eFdP1ShOZImsttsYKupCzSbyV/OfD4sjc1GkJ4vVxJR27cZJPql/isfotlmPEM/fuGGOeYzl2TeoV6wyQgvWDrOH5NxfsO+/+Q3bGERXFzQnKr/fnpXauq3cs55OqRvc64OUb4OZXFzgQ5lsVU5OrRUW7VCh7LYqmU6tERb9Qf3Y5Nqb/wo6gAAAABJRU5ErkJggg==",
@@ -670,7 +837,7 @@ var FLAG_IMAGES = {
 };
 // src/ui/language-switcher.ts
-var STYLE_ID = "dabalang-switcher-styles";
+var STYLE_ID2 = "dabalang-switcher-styles";
 var LANGUAGE_LABELS = {
   en: "English",
   es: "Espa\xF1ol",
@@ -764,9 +931,9 @@ var ALL_WORLD_LANGUAGES = [
   { code: "is", label: "\xCDslenska", flag: "is" }
 ];
 function injectStyles() {
-  if (document.getElementById(STYLE_ID)) return;
+  if (document.getElementById(STYLE_ID2)) return;
   const style = document.createElement("style");
-  style.id = STYLE_ID;
+  style.id = STYLE_ID2;
   style.textContent = `
 .dabalang-trigger {
   appearance: none;
@@ -1380,6 +1547,7 @@ var DabaLang = class {
     this.metadata = null;
     this.pathRouter = null;
     this.navWatcher = null;
+    this.prewarmer = null;
     /** Tail of the re-translation chain; see retranslateCurrentPage. */
     this.retranslating = Promise.resolve();
     /** Currently active language (null = original). Tracked here rather
@@ -1395,9 +1563,11 @@ var DabaLang = class {
     this.ready = this.init();
   }
   async init() {
+    preventFlash(this.options.projectId);
     try {
       this.metadata = await fetchProjectMetadata(this.gatewayUrl, this.options.projectId, this.options.apiKey);
     } catch (err) {
+      reveal();
       this.handleError(err);
       return;
     }
@@ -1449,6 +1619,8 @@ var DabaLang = class {
         }
       }
     }
+    reveal();
+    this.startPrewarm();
   }
   /**
    * Re-applies the active language to content that arrived after init.
@@ -1456,6 +1628,16 @@ var DabaLang = class {
    * A no-op in the source language — there is nothing to apply — and on
    * a site-translated page, where the page already *is* the translation.
    */
+  /** Warms every configured language except the one on screen. */
+  startPrewarm() {
+    if (!this.options.prewarm || !this.applier) return;
+    const applier = this.applier;
+    this.prewarmer ?? (this.prewarmer = new Prewarmer({
+      warm: (lang) => applier.warmLanguage(lang),
+      isFullyCached: (lang) => applier.isFullyCached(lang)
+    }));
+    this.prewarmer.start(warmOrder(this.readyLanguages(), this.activeLang));
+  }
   async retranslateCurrentPage() {
     if (!this.applier || this.activeLang === null) return;
     if (this.isSiteTranslated(this.activeLang)) return;
@@ -1467,6 +1649,7 @@ var DabaLang = class {
       } catch (err) {
         this.handleError(err);
       }
+      this.startPrewarm();
     });
     await this.retranslating;
   }
@@ -1517,6 +1700,7 @@ var DabaLang = class {
       this.activeLang = langCode;
       this.switcher.setActive(langCode);
       writePreferredLanguage(this.options.projectId, langCode);
+      this.startPrewarm();
       this.options.onLanguageChange?.(langCode ?? this.metadata?.sourceLang ?? "");
     } catch (err) {
       this.handleError(err);
@@ -1559,6 +1743,7 @@ var DabaLang = class {
   }
   destroy() {
     this.navWatcher?.stop();
+    this.prewarmer?.cancel();
     this.navWatcher = null;
     this.editor?.detach();
     this.switcher?.destroy();
@@ -1566,6 +1751,6 @@ var DabaLang = class {
   }
 };
-export { DabaLang, PathRouter };
+export { DabaLang, PathRouter, inlineSnippet, preventFlash, reveal };
 //# sourceMappingURL=dabalang.js.map
 //# sourceMappingURL=dabalang.js.map