From 35006cbf779ec10544bb201e1e3d63eddd967f33 Mon Sep 17 00:00:00 2001
From: Navid Shad <navidshad72@gmail.com>
Date: Fri, 16 Oct 2026 19:05:10 +0300
Subject: [PATCH] perf(translation): E-04 E-06 share in-flight translations and
 translate each caption once

- E-04: TranslateService keeps a map of requests in flight by cache key.
  An identical call made before the first one answers waits for it and
  gets the same answer, so only one request goes out. The entry is removed
  when the request settles; a failure reaches every waiting caller and is
  never cached.
- E-06: new src/subtitle/helpers/caption-translation-gate.ts. With
  "translate whole caption" on, the Netflix and support-template caption
  components wait about 150 ms for the caption to settle, then send it
  only when the joined text differs from the caption already translated
  on screen. A failed caption can be sent again. Turning the option on
  still translates at once.
- Tests: in-flight cases in tests/translate.service.test.ts, new
  tests/caption-translation-gate.test.ts.

Work list: subturtle-doc docs/tech/analytics-fixes-implementation.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                                     |  1 +
 src/common/services/translate.service.ts      | 38 +++++++++
 .../_support-template/components/Subtitle.vue | 39 +++++++--
 .../helpers/caption-translation-gate.ts       | 71 ++++++++++++++++
 .../web_netflix/components/Subtitle.vue       | 37 +++++++--
 tests/caption-translation-gate.test.ts        | 83 +++++++++++++++++++
 tests/translate.service.test.ts               | 69 +++++++++++++++
 7 files changed, 322 insertions(+), 16 deletions(-)
 create mode 100644 src/subtitle/helpers/caption-translation-gate.ts
 create mode 100644 tests/caption-translation-gate.test.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 5cd2e44..25470e7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -442,6 +442,7 @@ tests/
   settings-host.test.ts             # nibbleDisabledDomains normalize / toggle
   language-detection.test.ts        # RTL detection, title lookup, supported codes
   selection-popup.test.ts           # @mousedown.prevent.stop regression
+  caption-translation-gate.test.ts  # whole-caption translation: settle ~150 ms, skip the caption already sent (E-06); in-flight sharing is in translate.service.test.ts (E-04)
   nibble-surface.test.ts            # bridge-driven hide/show
   translate-card.test.ts            # popup translate input flow
   login-password.test.ts            # popup password form (ENABLE_PASSWORD_AUTH=true)
diff --git a/src/common/services/translate.service.ts b/src/common/services/translate.service.ts
index 33e4163..93918f6 100644
--- a/src/common/services/translate.service.ts
+++ b/src/common/services/translate.service.ts
@@ -36,6 +36,8 @@ export class TranslateService {
   // Cache for translation results
   private translationCache: TranslationCache = {};
   private readonly CACHE_DURATION = 24 * 60 * 60 * 1000; // 24 hours in milliseconds
+  // Requests on their way, by cache key (E-04).
+  private inFlight = new Map<string, Promise<any>>();
 
   /**
    * The learner's own language code, the one translations are written in.
@@ -135,6 +137,28 @@ export class TranslateService {
     };
   }
 
+  /**
+   * E-04: register a request as in flight, so an identical call made before
+   * it answers waits for it instead of sending a second request. The entry is
+   * removed when the request settles, so a failure is never reused or cached.
+   */
+  private startInFlight(cacheKey: string) {
+    let resolve!: (value: any) => void;
+    let reject!: (reason: unknown) => void;
+    const promise = new Promise<any>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    // Nobody may be waiting on it: a failure here must not be "unhandled".
+    promise.catch(() => {});
+    this.inFlight.set(cacheKey, promise);
+    const settle = () => this.inFlight.delete(cacheKey);
+    return {
+      resolve: (value: any) => (settle(), resolve(value)),
+      reject: (reason: unknown) => (settle(), reject(reason)),
+    };
+  }
+
   // Clean expired cache entries
   private cleanExpiredCache(): void {
     const now = Date.now();
@@ -160,6 +184,11 @@ export class TranslateService {
       return cachedResult;
     }
 
+    // The same request is already on its way: share it (E-04).
+    const pending = this.inFlight.get(cacheKey);
+    if (pending) return pending;
+    const inFlight = this.startInFlight(cacheKey);
+
     // If not cached, fetch from API
     try {
       const result = await withAuthRetry(() =>
@@ -180,11 +209,13 @@ export class TranslateService {
 
       // Cache the result
       this.cacheResult(cacheKey, result);
+      inFlight.resolve(result);
 
       return result;
     } catch (error) {
       // Log error but don't cache failed requests
       console.error("Translation error:", error);
+      inFlight.reject(error);
       throw error;
     }
   }
@@ -204,6 +235,11 @@ export class TranslateService {
       return cachedResult;
     }
 
+    // The same request is already on its way: share it (E-04).
+    const pending = this.inFlight.get(cacheKey);
+    if (pending) return pending;
+    const inFlight = this.startInFlight(cacheKey);
+
     // If not cached, fetch from API
     try {
       const data = await withAuthRetry(() =>
@@ -229,11 +265,13 @@ export class TranslateService {
 
       // Cache the result
       this.cacheResult(cacheKey, data);
+      inFlight.resolve(data);
 
       return data;
     } catch (error) {
       // Log error but don't cache failed requests
       console.error("Detailed translation error:", error);
+      inFlight.reject(error);
       throw error;
     }
   }
diff --git a/src/subtitle/_support-template/components/Subtitle.vue b/src/subtitle/_support-template/components/Subtitle.vue
index 2639cdc..c6946fb 100644
--- a/src/subtitle/_support-template/components/Subtitle.vue
+++ b/src/subtitle/_support-template/components/Subtitle.vue
@@ -69,10 +69,14 @@
 </template>
 
 <script lang="ts">
-import { defineComponent, PropType, StyleValue } from "vue";
+import { defineComponent, markRaw, PropType, StyleValue } from "vue";
 import { clamp } from "../../../common/helper/math";
 import { getDir, rtls } from "../../../common/helper/text";
 import { TranslateService } from "../../../common/services/translate.service";
+import {
+  createCaptionTranslationGate,
+  type CaptionTranslationGate,
+} from "../../helpers/caption-translation-gate";
 import { Dictionary } from "../../../common/types/general.type";
 import { analytic } from "../../../plugins/mixpanel";
 
@@ -84,6 +88,7 @@ interface DataModel {
   sourceLanguage: string;
   showTranslatedSentence: boolean;
   showWordDetail: boolean;
+  captionGate: CaptionTranslationGate | null;
 }
 
 export default defineComponent({
@@ -102,9 +107,21 @@ export default defineComponent({
       sourceLanguage: "en",
       showTranslatedSentence: false,
       showWordDetail: false,
+      captionGate: null,
     };
   },
 
+  created() {
+    // Not reactive state: the gate only holds a timer and the last caption.
+    this.captionGate = markRaw(
+      createCaptionTranslationGate((text) => this.translateWholeCaption(text))
+    );
+  },
+
+  beforeUnmount() {
+    this.captionGate?.cancel();
+  },
+
   computed: {
     lines() {
       let lines = this.translatedLines.length
@@ -174,13 +191,17 @@ export default defineComponent({
 
         if (!this.showTranslatedSentence || !value || !value.length) return;
 
-        this.translateWholeCaption();
+        // Wait for the caption to settle and send it once (E-06).
+        if (this.captionGate!.request(value.join("\n"))) {
+          this.translatedLines = [];
+        }
       },
     },
 
     showTranslatedSentence(value) {
-      if (!value || this.translatedLines.length) return;
-      this.translateWholeCaption();
+      if (!value) return this.captionGate!.cancel();
+      if (this.translatedLines.length || !this.textList?.length) return;
+      this.captionGate!.sendNow(this.textList.join("\n"));
     },
 
     hoveredWord(value) {
@@ -204,10 +225,9 @@ export default defineComponent({
       return list;
     },
 
-    translateWholeCaption() {
-      // let words = this.getWordList();
-      let lines = this.textList as unknown as Array<string>;
-      let translatingList = [lines.join("\n")];
+    /** Called by the caption gate with the settled caption (E-06). */
+    translateWholeCaption(caption: string) {
+      let translatingList = [caption];
 
       this.translatedLines = [];
 
@@ -219,7 +239,8 @@ export default defineComponent({
           translatingList.forEach((result, i) => {
             this.translatedLines.push(translatedText);
           });
-        });
+        })
+        .catch(() => this.captionGate?.forget(caption));
     },
 
     translateWord(word) {
diff --git a/src/subtitle/helpers/caption-translation-gate.ts b/src/subtitle/helpers/caption-translation-gate.ts
new file mode 100644
index 0000000..c3ae620
--- /dev/null
+++ b/src/subtitle/helpers/caption-translation-gate.ts
@@ -0,0 +1,71 @@
+/**
+ * Translate each caption once (E-06).
+ *
+ * With "translate whole caption" on, the caption watcher fires on every
+ * `textList` change, and a player can change it several times for one caption
+ * (lines added one by one, a caption that blinks off and back on). Each change
+ * used to send a translation request.
+ *
+ * The gate waits for the caption to settle (`delayMs`, about 150 ms), then
+ * sends it only when the joined text differs from the one whose translation
+ * is on screen (the last one sent). A failed request is forgotten, so the same
+ * caption can be tried again.
+ */
+export const CAPTION_SETTLE_MS = 150;
+
+export interface CaptionTranslationGate {
+  /**
+   * The caption changed to `text`: send it once it has been stable for the
+   * delay, unless its translation is already on screen. Returns true when the
+   * translation on screen belongs to another caption, so the caller should
+   * clear it now instead of showing it under the new text while it settles.
+   */
+  request(text: string): boolean;
+  /** Send `text` now, even if it was sent before (the user turned it on). */
+  sendNow(text: string): void;
+  /** The request for `text` failed: let the same caption be sent again. */
+  forget(text: string): void;
+  /** Drop a waiting request (unmount, translation turned off). */
+  cancel(): void;
+}
+
+export function createCaptionTranslationGate(
+  send: (text: string) => void,
+  delayMs: number = CAPTION_SETTLE_MS
+): CaptionTranslationGate {
+  // The caption whose translation is on screen, or on its way.
+  let lastSent: string | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const cancel = () => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+  };
+
+  const sendNow = (text: string) => {
+    cancel();
+    lastSent = text;
+    send(text);
+  };
+
+  return {
+    request(text) {
+      cancel();
+      const stale = text !== lastSent;
+      // The caller clears the old translation, so nothing is on screen now.
+      if (stale) lastSent = null;
+      timer = setTimeout(() => {
+        timer = null;
+        if (text !== lastSent) sendNow(text);
+      }, delayMs);
+      return stale;
+    },
+    sendNow,
+    forget(text) {
+      if (lastSent === text) lastSent = null;
+    },
+    cancel() {
+      cancel();
+    },
+  };
+}
diff --git a/src/subtitle/web_netflix/components/Subtitle.vue b/src/subtitle/web_netflix/components/Subtitle.vue
index c426da7..6c4d556 100644
--- a/src/subtitle/web_netflix/components/Subtitle.vue
+++ b/src/subtitle/web_netflix/components/Subtitle.vue
@@ -71,7 +71,7 @@
 </template>
 
 <script lang="ts">
-import { defineComponent, PropType, StyleValue } from "vue";
+import { defineComponent, markRaw, PropType, StyleValue } from "vue";
 import { mapState, mapActions } from "pinia";
 import { useMarkerStore } from "../../../stores/marker";
 import { clamp } from "../../../common/helper/math";
@@ -79,6 +79,10 @@ import { getDir, rtls, cleanText } from "../../../common/helper/text";
 import { TranslateService } from "../../../common/services/translate.service";
 import { log } from "../../../common/helper/log";
 import { LOADING_ICON } from "../../../common/icons/icons";
+import {
+  createCaptionTranslationGate,
+  type CaptionTranslationGate,
+} from "../../helpers/caption-translation-gate";
 
 interface DataModel {
   translatedLines: String[];
@@ -86,6 +90,7 @@ interface DataModel {
   showTranslatedSentence: boolean;
   showWordDetail: boolean;
   isTranslatingWholeCaption: boolean;
+  captionGate: CaptionTranslationGate | null;
 }
 
 export default defineComponent({
@@ -101,9 +106,21 @@ export default defineComponent({
       showTranslatedSentence: false,
       showWordDetail: false,
       isTranslatingWholeCaption: false,
+      captionGate: null,
     };
   },
 
+  created() {
+    // Not reactive state: the gate only holds a timer and the last caption.
+    this.captionGate = markRaw(
+      createCaptionTranslationGate((text) => this.translateWholeCaption(text))
+    );
+  },
+
+  beforeUnmount() {
+    this.captionGate?.cancel();
+  },
+
   computed: {
     ...mapState(useMarkerStore, [
       "selectedPhrase",
@@ -210,7 +227,10 @@ export default defineComponent({
 
         if (!this.showTranslatedSentence || !value || !value.length) return;
 
-        this.translateWholeCaption();
+        // Wait for the caption to settle and send it once (E-06).
+        if (this.captionGate!.request(value.join("\n"))) {
+          this.translatedLines = [];
+        }
       },
     },
 
@@ -218,8 +238,11 @@ export default defineComponent({
       log("showTranslatedSentence", value);
 
       if (value == true) {
-        this.translateWholeCaption();
+        if (this.textList?.length) {
+          this.captionGate!.sendNow(this.textList.join("\n"));
+        }
       } else {
+        this.captionGate!.cancel();
         this.translatedLines = [];
         this.clear();
       }
@@ -241,10 +264,9 @@ export default defineComponent({
       return list;
     },
 
-    translateWholeCaption() {
-      // let words = this.getWordList();
-      let lines = this.textList as unknown as Array<string>;
-      let translatingList = [lines.join("\n")];
+    /** Called by the caption gate with the settled caption (E-06). */
+    translateWholeCaption(caption: string) {
+      let translatingList = [caption];
 
       this.translatedLines = [];
 
@@ -257,6 +279,7 @@ export default defineComponent({
             this.translatedLines.push(translationResult);
           });
         })
+        .catch(() => this.captionGate?.forget(caption))
         .finally(() => {
           this.isTranslatingWholeCaption = false;
         });
diff --git a/tests/caption-translation-gate.test.ts b/tests/caption-translation-gate.test.ts
new file mode 100644
index 0000000..28f5622
--- /dev/null
+++ b/tests/caption-translation-gate.test.ts
@@ -0,0 +1,83 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  CAPTION_SETTLE_MS,
+  createCaptionTranslationGate,
+} from "../src/subtitle/helpers/caption-translation-gate";
+
+// E-06: with "translate whole caption" on, each real caption change sends one
+// request, after the caption settles.
+describe("caption translation gate", () => {
+  let send: ReturnType<typeof vi.fn>;
+  let gate: ReturnType<typeof createCaptionTranslationGate>;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    send = vi.fn();
+    gate = createCaptionTranslationGate(send);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("waits for the caption to settle, then sends it once", () => {
+    gate.request("Hello");
+    gate.request("Hello\nworld");
+    vi.advanceTimersByTime(CAPTION_SETTLE_MS - 1);
+    expect(send).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(1);
+    expect(send).toHaveBeenCalledTimes(1);
+    expect(send).toHaveBeenCalledWith("Hello\nworld");
+  });
+
+  it("skips a caption equal to the last one sent", () => {
+    gate.request("Hello");
+    vi.runAllTimers();
+    // The caption blinks off and comes back: no new request, nothing stale.
+    expect(gate.request("Hello")).toBe(false);
+    vi.runAllTimers();
+    expect(send).toHaveBeenCalledTimes(1);
+  });
+
+  it("reports a new caption as stale and sends it", () => {
+    gate.request("Hello");
+    vi.runAllTimers();
+    expect(gate.request("Bye")).toBe(true);
+    vi.runAllTimers();
+    expect(send.mock.calls).toEqual([["Hello"], ["Bye"]]);
+  });
+
+  it("sends the first caption again after A → B → A (its translation was cleared)", () => {
+    gate.request("A");
+    vi.runAllTimers();
+    gate.request("B");
+    expect(gate.request("A")).toBe(true);
+    vi.runAllTimers();
+    // B never settled, so only A is sent again.
+    expect(send.mock.calls).toEqual([["A"], ["A"]]);
+  });
+
+  it("sendNow sends at once, even the same caption", () => {
+    gate.request("Hello");
+    vi.runAllTimers();
+    gate.sendNow("Hello");
+    expect(send).toHaveBeenCalledTimes(2);
+  });
+
+  it("forget lets a failed caption be sent again", () => {
+    gate.request("Hello");
+    vi.runAllTimers();
+    gate.forget("Hello");
+    gate.request("Hello");
+    vi.runAllTimers();
+    expect(send).toHaveBeenCalledTimes(2);
+  });
+
+  it("cancel drops a waiting request", () => {
+    gate.request("Hello");
+    gate.cancel();
+    vi.runAllTimers();
+    expect(send).not.toHaveBeenCalled();
+  });
+});
diff --git a/tests/translate.service.test.ts b/tests/translate.service.test.ts
index 440721a..0b76e39 100644
--- a/tests/translate.service.test.ts
+++ b/tests/translate.service.test.ts
@@ -41,6 +41,7 @@ describe("TranslateService cache", () => {
     // The singleton is shared across imports; reset the private cache so
     // tests don't leak state into each other.
     (TranslateService.instance as any).translationCache = {};
+    (TranslateService.instance as any).inFlight = new Map();
     svc = TranslateService.instance;
 
     runMock.mockReset();
@@ -116,6 +117,74 @@ describe("TranslateService cache", () => {
     expect(result).toBe("ok");
     expect(runMock).toHaveBeenCalledTimes(2);
   });
+
+  // E-04: identical calls made while the first one is on its way share it.
+  describe("in-flight sharing", () => {
+    function deferred<T>() {
+      let resolve!: (v: T) => void;
+      let reject!: (e: unknown) => void;
+      const promise = new Promise<T>((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      return { promise, resolve, reject };
+    }
+
+    it("sends one request for two identical calls in flight", async () => {
+      const d = deferred<string>();
+      runMock.mockReturnValueOnce(d.promise);
+
+      const a = svc.fetchSimpleTranslation("hello", "ctx");
+      const b = svc.fetchSimpleTranslation("hello", "ctx");
+      await vi.waitFor(() => expect(runMock).toHaveBeenCalledTimes(1));
+      d.resolve("shared");
+
+      expect(await a).toBe("shared");
+      expect(await b).toBe("shared");
+      expect(runMock).toHaveBeenCalledTimes(1);
+      expect((svc as any).inFlight.size).toBe(0);
+    });
+
+    it("shares detailed requests too", async () => {
+      const d = deferred<any>();
+      runMock.mockReturnValueOnce(d.promise);
+
+      const a = svc.fetchDetailedTranslation("hello", "ctx");
+      const b = svc.fetchDetailedTranslation("hello", "ctx");
+      await vi.waitFor(() => expect(runMock).toHaveBeenCalledTimes(1));
+      d.resolve({ translation: { phrase: "x" } });
+
+      expect(await b).toBe(await a);
+      expect(runMock).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not share different keys", async () => {
+      await Promise.all([
+        svc.fetchSimpleTranslation("hello", "ctxA"),
+        svc.fetchSimpleTranslation("hello", "ctxB"),
+      ]);
+      expect(runMock).toHaveBeenCalledTimes(2);
+    });
+
+    it("a failure reaches every waiting caller and is not kept", async () => {
+      const d = deferred<string>();
+      runMock.mockReturnValueOnce(d.promise);
+
+      const a = svc.fetchSimpleTranslation("hello", "ctx");
+      const b = svc.fetchSimpleTranslation("hello", "ctx");
+      await vi.waitFor(() => expect(runMock).toHaveBeenCalledTimes(1));
+      d.reject(new Error("network"));
+
+      await expect(a).rejects.toThrow("network");
+      await expect(b).rejects.toThrow("network");
+      expect((svc as any).inFlight.size).toBe(0);
+
+      // The next call sends a new request.
+      runMock.mockResolvedValue("ok");
+      expect(await svc.fetchSimpleTranslation("hello", "ctx")).toBe("ok");
+      expect(runMock).toHaveBeenCalledTimes(2);
+    });
+  });
 });
 
 // Regression net for the "Translation failed / User not found" report: a stale