@dabalabs/lang 0.0.1-beta → 0.0.3-beta

package/dist/dabalang.d.cts

@@ -51,6 +51,12 @@ interface LanguageConfig {
     pathPrefix: string | null;
     /** Language applied on un-prefixed paths when path routing is on. */
     isDefault: boolean;
+    /** False while the language is still being populated. The switcher
+     * omits it, so a visitor is never offered a language that would
+     * translate the page live in front of them. Absent (older gateways)
+     * counts as ready — a widget must not hide working languages because
+     * the server predates the field. */
+    ready: boolean;
 }
 interface ProjectMetadata {
     projectId: string;
@@ -82,6 +88,9 @@ declare class DabaLang {
     private switcher;
     private metadata;
     private pathRouter;
+    private navWatcher;
+    /** Tail of the re-translation chain; see retranslateCurrentPage. */
+    private retranslating;
     /** Currently active language (null = original). Tracked here rather
      * than via the applier because a site-translated page (see
      * isSiteTranslated) never runs the applier at all. */
@@ -89,11 +98,28 @@ declare class DabaLang {
     private readonly ready;
     constructor(options: DabaLangOptions);
     private init;
+    /**
+     * Re-applies the active language to content that arrived after init.
+     *
+     * 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.
+     */
+    private retranslateCurrentPage;
     /** True when the site serves this language's content itself (CMS,
      * localized build): a pre-translated ("developer") language. Combined
      * with a prefix match, the widget never machine-translates that page.
      * (A prefix-less developer language instead swaps its uploaded
      * catalogue in place.) */
+    /** Target languages that actually have translations behind them.
+     *
+     * A configured-but-unpopulated language is worse than a missing one: a
+     * visitor picks it and watches the page translate live, paragraph by
+     * paragraph, or lands on a half-translated page while a run is still
+     * going. Languages with no config row at all are legacy
+     * target_languages entries that predate per-language config — they are
+     * shown, because hiding a language that has been serving traffic would
+     * be a regression. */
+    private readyLanguages;
     private isSiteTranslated;
     private selectLanguage;
     /** Overridable seam for tests — jsdom can't perform real navigation. */
@@ -102,6 +128,18 @@ declare class DabaLang {
     /** Resolves once the initial metadata fetch + pill render has settled
      * (successfully or not) — mainly useful in tests. */
     whenReady(): Promise<void>;
+    /**
+     * Switch language programmatically — the same path the switcher takes,
+     * so the choice is applied, persisted and reported identically.
+     *
+     * Exists because a host page often has its own reason to change
+     * language: a footer link, a country picker, a preference synced from
+     * an account. Without it those would have to fake a click on the
+     * widget's own DOM.
+     *
+     * Pass null to return to the source language.
+     */
+    setLanguage(langCode: string | null): Promise<void>;
     currentLanguage(): string | null;
     destroy(): void;
 }

package/dist/dabalang.d.ts

@@ -51,6 +51,12 @@ interface LanguageConfig {
     pathPrefix: string | null;
     /** Language applied on un-prefixed paths when path routing is on. */
     isDefault: boolean;
+    /** False while the language is still being populated. The switcher
+     * omits it, so a visitor is never offered a language that would
+     * translate the page live in front of them. Absent (older gateways)
+     * counts as ready — a widget must not hide working languages because
+     * the server predates the field. */
+    ready: boolean;
 }
 interface ProjectMetadata {
     projectId: string;
@@ -82,6 +88,9 @@ declare class DabaLang {
     private switcher;
     private metadata;
     private pathRouter;
+    private navWatcher;
+    /** Tail of the re-translation chain; see retranslateCurrentPage. */
+    private retranslating;
     /** Currently active language (null = original). Tracked here rather
      * than via the applier because a site-translated page (see
      * isSiteTranslated) never runs the applier at all. */
@@ -89,11 +98,28 @@ declare class DabaLang {
     private readonly ready;
     constructor(options: DabaLangOptions);
     private init;
+    /**
+     * Re-applies the active language to content that arrived after init.
+     *
+     * 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.
+     */
+    private retranslateCurrentPage;
     /** True when the site serves this language's content itself (CMS,
      * localized build): a pre-translated ("developer") language. Combined
      * with a prefix match, the widget never machine-translates that page.
      * (A prefix-less developer language instead swaps its uploaded
      * catalogue in place.) */
+    /** Target languages that actually have translations behind them.
+     *
+     * A configured-but-unpopulated language is worse than a missing one: a
+     * visitor picks it and watches the page translate live, paragraph by
+     * paragraph, or lands on a half-translated page while a run is still
+     * going. Languages with no config row at all are legacy
+     * target_languages entries that predate per-language config — they are
+     * shown, because hiding a language that has been serving traffic would
+     * be a regression. */
+    private readyLanguages;
     private isSiteTranslated;
     private selectLanguage;
     /** Overridable seam for tests — jsdom can't perform real navigation. */
@@ -102,6 +128,18 @@ declare class DabaLang {
     /** Resolves once the initial metadata fetch + pill render has settled
      * (successfully or not) — mainly useful in tests. */
     whenReady(): Promise<void>;
+    /**
+     * Switch language programmatically — the same path the switcher takes,
+     * so the choice is applied, persisted and reported identically.
+     *
+     * Exists because a host page often has its own reason to change
+     * language: a footer link, a country picker, a preference synced from
+     * an account. Without it those would have to fake a click on the
+     * widget's own DOM.
+     *
+     * Pass null to return to the source language.
+     */
+    setLanguage(langCode: string | null): Promise<void>;
     currentLanguage(): string | null;
     destroy(): void;
 }

package/dist/dabalang.js

@@ -95,7 +95,10 @@ async function fetchProjectMetadata(gatewayUrl, projectId, apiKey) {
       code: l.code,
       provider: l.provider,
       pathPrefix: l.path_prefix,
-      isDefault: l.is_default
+      isDefault: l.is_default,
+      // Absent means an older gateway that has no readiness concept —
+      // treat as ready rather than hiding every language.
+      ready: l.ready ?? true
     }))
   };
 }
@@ -204,13 +207,38 @@ var TranslationApplier = class {
     this.apiKey = apiKey;
     this.fetchedLanguages = /* @__PURE__ */ new Map();
     this.activeLang = null;
-    this.groups = groupByText(crawlVisibleText(root));
+    /** The true source text of every node the widget has ever crawled.
+     *
+     * Needed because a re-crawl reads the DOM as it stands, and after a
+     * translation the DOM no longer holds the source. On a single-page app
+     * the shell — header, nav, footer — stays mounted across a navigation
+     * with its text already translated, so a naive re-crawl would record
+     * "Начать" as the source for the Get Started link. Everything
+     * downstream then works from a corrupted map: the widget pays to
+     * translate Russian into Russian, and restoreOriginal() writes the
+     * Russian back as if it were the original, leaving the shell stuck in a
+     * language the visitor just switched out of.
+     *
+     * Weak so it holds no node alive: entries vanish with the nodes. */
+    this.sourceByNode = /* @__PURE__ */ new WeakMap();
+    this.groups = this.absorb(crawlVisibleText(root));
+  }
+  /** Groups a crawl, preferring each node's remembered source text over
+   *  whatever it currently displays, and remembering the rest. */
+  absorb(crawled) {
+    const corrected = crawled.map(({ node, sourceText }) => {
+      const known = this.sourceByNode.get(node);
+      if (known !== void 0) return { node, sourceText: known };
+      this.sourceByNode.set(node, sourceText);
+      return { node, sourceText };
+    });
+    return groupByText(corrected);
   }
   /** Re-crawls the current DOM — call after content is known to have
    * changed (e.g. after a route change in an SPA). Not called
    * automatically; dabalang does one crawl per page load. */
   recrawl() {
-    this.groups = groupByText(crawlVisibleText(this.root));
+    this.groups = this.absorb(crawlVisibleText(this.root));
   }
   currentLanguage() {
     return this.activeLang;
@@ -432,6 +460,97 @@ var InlineEditor = class {
   }
 };
 
+// src/dom/navigation-watcher.ts
+var SETTLE_MS = 250;
+var FOLLOW_UP_PASSES = 3;
+var subscribers = /* @__PURE__ */ new Set();
+var unpatchHistory = null;
+function subscribeToHistory(fn) {
+  subscribers.add(fn);
+  if (!unpatchHistory) {
+    const original = {
+      pushState: window.history.pushState,
+      replaceState: window.history.replaceState
+    };
+    for (const method of ["pushState", "replaceState"]) {
+      window.history[method] = function(...args) {
+        const result = original[method].apply(this, args);
+        for (const sub of [...subscribers]) sub();
+        return result;
+      };
+    }
+    unpatchHistory = () => {
+      window.history.pushState = original.pushState;
+      window.history.replaceState = original.replaceState;
+    };
+  }
+  return () => {
+    subscribers.delete(fn);
+    if (subscribers.size === 0 && unpatchHistory) {
+      unpatchHistory();
+      unpatchHistory = null;
+    }
+  };
+}
+var NavigationWatcher = class {
+  constructor(onNavigated) {
+    this.onNavigated = onNavigated;
+    this.observer = null;
+    this.timer = null;
+    this.lastPath = "";
+    this.passesLeft = 0;
+    this.restorers = [];
+  }
+  start() {
+    if (typeof window === "undefined" || this.observer) return;
+    this.lastPath = this.currentPath();
+    this.restorers.push(subscribeToHistory(() => this.onRouteMaybeChanged()));
+    const onPop = () => this.onRouteMaybeChanged();
+    window.addEventListener("popstate", onPop);
+    this.restorers.push(() => window.removeEventListener("popstate", onPop));
+    this.observer = new MutationObserver(() => {
+      if (this.currentPath() !== this.lastPath) {
+        this.schedule();
+      } else if (this.passesLeft > 0) {
+        this.schedule();
+      }
+    });
+    this.observer.observe(document.body, { childList: true, subtree: true });
+  }
+  currentPath() {
+    return window.location.pathname + window.location.search;
+  }
+  onRouteMaybeChanged() {
+    if (this.currentPath() === this.lastPath) return;
+    this.schedule();
+  }
+  /** Debounced: a route change produces a burst of mutations, and the
+   *  handler must run once, after the last one. */
+  schedule() {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      const path = this.currentPath();
+      if (path !== this.lastPath) {
+        this.lastPath = path;
+        this.passesLeft = FOLLOW_UP_PASSES;
+        this.onNavigated();
+      } else if (this.passesLeft > 0) {
+        this.passesLeft -= 1;
+        this.onNavigated();
+      }
+    }, SETTLE_MS);
+  }
+  stop() {
+    this.observer?.disconnect();
+    this.observer = null;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.passesLeft = 0;
+    while (this.restorers.length) this.restorers.pop()?.();
+  }
+};
+
 // src/path-routing.ts
 var PathRouter = class {
   constructor(languages) {
@@ -475,6 +594,26 @@ var PathRouter = class {
   }
 };
 
+// src/preference.ts
+var PREFIX = "dabalang:lang:";
+function readPreferredLanguage(projectId) {
+  try {
+    return window.localStorage.getItem(PREFIX + projectId);
+  } catch {
+    return null;
+  }
+}
+function writePreferredLanguage(projectId, langCode) {
+  try {
+    if (langCode === null) {
+      window.localStorage.removeItem(PREFIX + projectId);
+    } else {
+      window.localStorage.setItem(PREFIX + projectId, langCode);
+    }
+  } catch {
+  }
+}
+
 // 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==",
@@ -629,10 +768,14 @@ function injectStyles() {
   display: inline-flex;
   align-items: center;
   gap: 6px;
-  border: 1px solid rgba(0, 0, 0, 0.12);
-  background: #ffffff;
-  color: rgba(0, 0, 0, 0.75);
-  border-radius: 999px;
+  border: 1px solid var(--dabalang-border-color, rgba(0, 0, 0, 0.12));
+  background: var(--dabalang-bg, #ffffff);
+  color: var(--dabalang-color, rgba(0, 0, 0, 0.75));
+  /* Themeable so the switcher can match the host's own buttons. A widget
+     cannot know whether a site uses pills or 6px corners, and defaulting
+     to a pill made this the one control on the page that did not match.
+     Set --dabalang-radius on any ancestor to align it. */
+  border-radius: var(--dabalang-radius, 999px);
   padding: 6px 12px;
   cursor: pointer;
   font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
@@ -899,8 +1042,10 @@ function injectStyles() {
   max-height: 320px;
   overflow-y: auto;
   background: #ffffff;
-  border: 1px solid rgba(0, 0, 0, 0.1);
-  border-radius: 14px;
+  border: 1px solid var(--dabalang-border-color, rgba(0, 0, 0, 0.1));
+  /* Panel corners follow the trigger's family, one step softer, so a
+     square-cornered host does not get a pill-shaped dropdown. */
+  border-radius: var(--dabalang-panel-radius, 14px);
   box-shadow: 0 12px 32px rgba(0, 0, 0, 0.14);
   padding: 6px;
   box-sizing: border-box;
@@ -1227,6 +1372,9 @@ var DabaLang = class {
     this.switcher = null;
     this.metadata = null;
     this.pathRouter = null;
+    this.navWatcher = null;
+    /** Tail of the re-translation chain; see retranslateCurrentPage. */
+    this.retranslating = Promise.resolve();
     /** Currently active language (null = original). Tracked here rather
      * than via the applier because a site-translated page (see
      * isSiteTranslated) never runs the applier at all. */
@@ -1255,13 +1403,19 @@ var DabaLang = class {
     });
     this.switcher = renderLanguageSwitcher(
       this.container,
-      this.metadata.targetLanguages,
+      this.readyLanguages(),
       this.metadata.sourceLang,
       (langCode) => {
         void this.selectLanguage(langCode);
       },
       this.options.view ?? "modal"
     );
+    if (typeof window !== "undefined") {
+      this.navWatcher = new NavigationWatcher(() => {
+        void this.retranslateCurrentPage();
+      });
+      this.navWatcher.start();
+    }
     if (this.metadata.enablePathRouting && typeof window !== "undefined") {
       this.pathRouter = new PathRouter(this.metadata.languages);
       const detected = this.pathRouter.detect(window.location.pathname);
@@ -1277,12 +1431,59 @@ var DabaLang = class {
         }
       }
     }
+    if (this.activeLang === null && !this.pathRouter) {
+      const remembered = readPreferredLanguage(this.options.projectId);
+      if (remembered) {
+        const stillOffered = (this.metadata?.targetLanguages ?? []).includes(remembered);
+        if (!stillOffered) {
+          writePreferredLanguage(this.options.projectId, null);
+        } else if (this.readyLanguages().includes(remembered)) {
+          await this.selectLanguage(remembered, { navigate: false });
+        }
+      }
+    }
+  }
+  /**
+   * Re-applies the active language to content that arrived after init.
+   *
+   * 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.
+   */
+  async retranslateCurrentPage() {
+    if (!this.applier || this.activeLang === null) return;
+    if (this.isSiteTranslated(this.activeLang)) return;
+    this.retranslating = this.retranslating.catch(() => void 0).then(async () => {
+      if (!this.applier || this.activeLang === null) return;
+      this.applier.recrawl();
+      try {
+        await this.applier.applyLanguage(this.activeLang);
+      } catch (err) {
+        this.handleError(err);
+      }
+    });
+    await this.retranslating;
   }
   /** True when the site serves this language's content itself (CMS,
    * localized build): a pre-translated ("developer") language. Combined
    * with a prefix match, the widget never machine-translates that page.
    * (A prefix-less developer language instead swaps its uploaded
    * catalogue in place.) */
+  /** Target languages that actually have translations behind them.
+   *
+   * A configured-but-unpopulated language is worse than a missing one: a
+   * visitor picks it and watches the page translate live, paragraph by
+   * paragraph, or lands on a half-translated page while a run is still
+   * going. Languages with no config row at all are legacy
+   * target_languages entries that predate per-language config — they are
+   * shown, because hiding a language that has been serving traffic would
+   * be a regression. */
+  readyLanguages() {
+    const configs = this.metadata?.languages ?? [];
+    return (this.metadata?.targetLanguages ?? []).filter((code) => {
+      const config = configs.find((l) => l.code === code);
+      return config ? config.ready : true;
+    });
+  }
   isSiteTranslated(langCode) {
     const config = this.metadata?.languages.find((l) => l.code === langCode);
     return config?.provider === "developer";
@@ -1308,6 +1509,7 @@ var DabaLang = class {
       }
       this.activeLang = langCode;
       this.switcher.setActive(langCode);
+      writePreferredLanguage(this.options.projectId, langCode);
       this.options.onLanguageChange?.(langCode ?? this.metadata?.sourceLang ?? "");
     } catch (err) {
       this.handleError(err);
@@ -1330,10 +1532,27 @@ var DabaLang = class {
   whenReady() {
     return this.ready;
   }
+  /**
+   * Switch language programmatically — the same path the switcher takes,
+   * so the choice is applied, persisted and reported identically.
+   *
+   * Exists because a host page often has its own reason to change
+   * language: a footer link, a country picker, a preference synced from
+   * an account. Without it those would have to fake a click on the
+   * widget's own DOM.
+   *
+   * Pass null to return to the source language.
+   */
+  async setLanguage(langCode) {
+    await this.ready;
+    await this.selectLanguage(langCode);
+  }
   currentLanguage() {
     return this.activeLang;
   }
   destroy() {
+    this.navWatcher?.stop();
+    this.navWatcher = null;
     this.editor?.detach();
     this.switcher?.destroy();
     this.docLang.restore();