@procore/ai-translations 0.8.1 → 0.9.0

package/dist/modern/index.mjs

@@ -627,6 +627,7 @@ var TRANSLATION_COMPLETE_EVENT_NAME = "ai-translation-completed";
 var RERENDER_EVENT_NAME = "ai-translations-component-rerender";
 var TRANSLATION_PROGRESS_EVENT_NAME = "ai-translations-progress";
 var MODEL_DOWNLOAD_PROGRESS_EVENT_NAME = "ai-translations-model-download-progress";
+var MODEL_CONSENT_REQUIRED_EVENT_NAME = "ai-translations-model-consent-required";
 
 // src/utils/eventHandler.ts
 var EventHandler = class {
@@ -700,12 +701,14 @@ var EventHandler = class {
    * Not tool-scoped — a Chrome language model is shared across the entire
    * browser session, so all Provider instances receive it.
    */
-  publishModelDownloadProgressEvent(loaded, total, progress) {
+  publishModelDownloadProgressEvent(loaded, total, progress, sourceLanguage, targetLanguage) {
     this.aiTranslationEvents.publish(MODEL_DOWNLOAD_PROGRESS_EVENT_NAME, {
       loaded,
       total,
       progress,
-      isComplete: loaded === total
+      isComplete: loaded === total,
+      sourceLanguage,
+      targetLanguage
     });
   }
   subscribeToModelDownloadProgressEvent(callback) {
@@ -715,7 +718,29 @@ var EventHandler = class {
         loaded: detail.data?.loaded ?? 0,
         total: detail.data?.total ?? 0,
         progress: detail.data?.progress ?? 0,
-        isComplete: detail.data?.isComplete ?? false
+        isComplete: detail.data?.isComplete ?? false,
+        sourceLanguage: detail.data?.sourceLanguage ?? "",
+        targetLanguage: detail.data?.targetLanguage ?? ""
+      })
+    );
+  }
+  /**
+   * Publishes a request for the user to consent to downloading a specific
+   * source -> target language model. Like the download-progress event this is
+   * NOT tool-scoped — a language model is shared across the whole session.
+   */
+  publishModelConsentRequiredEvent(sourceLanguage, targetLanguage) {
+    this.aiTranslationEvents.publish(MODEL_CONSENT_REQUIRED_EVENT_NAME, {
+      sourceLanguage,
+      targetLanguage
+    });
+  }
+  subscribeToModelConsentRequiredEvent(callback) {
+    return this.aiTranslationEvents.subscribe(
+      MODEL_CONSENT_REQUIRED_EVENT_NAME,
+      (detail) => callback({
+        sourceLanguage: detail.data?.sourceLanguage ?? "",
+        targetLanguage: detail.data?.targetLanguage ?? ""
       })
     );
   }
@@ -724,6 +749,111 @@ var EventHandler = class {
   }
 };
 
+// src/utils/modelDownloadGate.ts
+var ModelDownloadGateImpl = class _ModelDownloadGateImpl {
+  eventHandler = null;
+  ready = /* @__PURE__ */ new Set();
+  pending = /* @__PURE__ */ new Map();
+  resolvers = /* @__PURE__ */ new Map();
+  rejecters = /* @__PURE__ */ new Map();
+  getEventHandler() {
+    if (!this.eventHandler) {
+      this.eventHandler = new EventHandler("__chrome_model__");
+    }
+    return this.eventHandler;
+  }
+  static key(sourceLanguage, targetLanguage) {
+    return `${sourceLanguage}->${targetLanguage}`;
+  }
+  /**
+   * Resolves once the model for `sourceLanguage -> targetLanguage` is downloaded
+   * and ready. Pauses (stays pending) until the user confirms the download and
+   * it completes. Re-prompts are deduped per model.
+   */
+  ensureModelReady(sourceLanguage, targetLanguage) {
+    const key = _ModelDownloadGateImpl.key(sourceLanguage, targetLanguage);
+    if (this.ready.has(key)) {
+      return Promise.resolve();
+    }
+    const existing = this.pending.get(key);
+    if (existing) {
+      return existing;
+    }
+    const promise = new Promise((resolve, reject) => {
+      this.resolvers.set(key, resolve);
+      this.rejecters.set(key, reject);
+    });
+    this.pending.set(key, promise);
+    this.getEventHandler().publishModelConsentRequiredEvent(
+      sourceLanguage,
+      targetLanguage
+    );
+    return promise;
+  }
+  /**
+   * Marks a model as ready and resolves any waiter. Resolved exclusively when
+   * `downloadModel` resolves (wired in the Provider). This guarantees Chrome's
+   * `Translator.create()` has returned and the translator instance is cached in
+   * `chromeTranslatorRegistry`, so the resumed translation reuses it instead of
+   * calling `Translator.create()` again outside the user gesture (which throws
+   * `NotAllowedError`). It is deliberately NOT resolved on the intermediate
+   * `MODEL_DOWNLOAD_PROGRESS` `isComplete` event, which fires before
+   * `Translator.create()` returns.
+   */
+  markReady(sourceLanguage, targetLanguage) {
+    const key = _ModelDownloadGateImpl.key(sourceLanguage, targetLanguage);
+    this.ready.add(key);
+    const resolve = this.resolvers.get(key);
+    if (resolve) {
+      resolve();
+    }
+    this.clearPending(key);
+  }
+  /**
+   * Marks a model download as failed and rejects any waiter so the paused
+   * translation run can move past this text instead of hanging forever. Called
+   * when `downloadModel` rejects (e.g. Chrome returns 404 for a pair it
+   * reported as downloadable). The pair is NOT cached as ready, so it can be
+   * re-attempted later.
+   */
+  markFailed(sourceLanguage, targetLanguage, error) {
+    const key = _ModelDownloadGateImpl.key(sourceLanguage, targetLanguage);
+    const reject = this.rejecters.get(key);
+    if (reject) {
+      reject(
+        error instanceof Error ? error : new Error(`Model download failed for ${key}`)
+      );
+    }
+    this.clearPending(key);
+  }
+  isReady(sourceLanguage, targetLanguage) {
+    return this.ready.has(
+      _ModelDownloadGateImpl.key(sourceLanguage, targetLanguage)
+    );
+  }
+  /**
+   * Clears all gate state. Intended for test teardown so cached "ready" models
+   * do not leak between cases.
+   */
+  reset() {
+    this.ready.clear();
+    this.pending.clear();
+    this.resolvers.clear();
+    this.rejecters.clear();
+  }
+  clearPending(key) {
+    this.resolvers.delete(key);
+    this.rejecters.delete(key);
+    this.pending.delete(key);
+  }
+};
+var modelDownloadGate = new ModelDownloadGateImpl();
+
+// src/utils/language.ts
+function normalizeLanguage(language) {
+  return language.split("-")[0] ?? language;
+}
+
 // src/utils/renderVersionManager.ts
 var RenderVersionManager = class {
   version = 0;
@@ -780,27 +910,30 @@ var TranslationManager = class {
     this.translationProgress.total = queueManager.queueSize(
       this.currentTranslatorStrategy
     );
-    do {
-      for (const batch of queueManager.generateBatches(
-        this.translator.getConfig()
-      )) {
-        batch.forEach((entry) => this.mfeToBeNotified.add(entry.tool));
-        const result = await this.translator.processTranslations(
-          batch.map(
-            (entry) => this.convertTranslationQueueEntryToTranslationRequest(entry)
-          )
-        );
-        this.setTranslationProgress(batch.length);
-        await this.updateDatabaseWithTranslations(result);
-        await this.notifyTranslationCompleted();
+    try {
+      do {
+        for (const batch of queueManager.generateBatches(
+          this.translator.getConfig()
+        )) {
+          batch.forEach((entry) => this.mfeToBeNotified.add(entry.tool));
+          const result = await this.translator.processTranslations(
+            batch.map(
+              (entry) => this.convertTranslationQueueEntryToTranslationRequest(entry)
+            )
+          );
+          this.setTranslationProgress(batch.length);
+          await this.updateDatabaseWithTranslations(result);
+          await this.notifyTranslationCompleted();
+        }
+      } while (queueManager.queueSize(this.currentTranslatorStrategy) > 0);
+      this.resetTranslationProgress();
+      this.publishTranslationProgress();
+    } finally {
+      if (this.currentTranslatorStrategy === "frontend_translations") {
+        globalThis._FRONTEND_AI_TRANSLATION_IN_PROGRESS_ = false;
+      } else {
+        globalThis._BACKEND_AI_TRANSLATION_IN_PROGRESS_ = false;
       }
-    } while (queueManager.queueSize(this.currentTranslatorStrategy) > 0);
-    this.resetTranslationProgress();
-    this.publishTranslationProgress();
-    if (this.currentTranslatorStrategy === "frontend_translations") {
-      globalThis._FRONTEND_AI_TRANSLATION_IN_PROGRESS_ = false;
-    } else {
-      globalThis._BACKEND_AI_TRANSLATION_IN_PROGRESS_ = false;
     }
   }
   async updateDatabaseWithTranslations(translationResult) {
@@ -970,6 +1103,16 @@ var Client = class {
       return this.createTranslationErrorResponse(requests, errorMessage);
     }
   }
+  /**
+   * No-op: backend translation does not manage on-device models, so there is
+   * nothing to download client-side. The parameters are kept to match the
+   * {@link TranslatorClientAdapter.downloadModel} signature and make the no-op
+   * intent explicit to callers.
+   */
+  async downloadModel(sourceLanguage, targetLanguage) {
+    void sourceLanguage;
+    void targetLanguage;
+  }
   createTranslationErrorResponse(requests, errorMessage) {
     return {
       responseBody: requests.map((req) => ({
@@ -1089,6 +1232,7 @@ var ChromeTranslator = class _ChromeTranslator {
     }
   }
   static async init(sourceLanguage, targetLanguage) {
+    this.ensureRegistry();
     if (globalThis.chromeTranslatorRegistry.has(
       this.generateKey(sourceLanguage, targetLanguage)
     )) {
@@ -1103,7 +1247,30 @@ var ChromeTranslator = class _ChromeTranslator {
       new _ChromeTranslator(translator)
     );
   }
-  static async createTranslator(source, target) {
+  /**
+   * Downloads the on-device model for a source -> target language pair. Must be
+   * invoked from a user gesture (e.g. a click handler), since Chrome requires an
+   * active gesture to start a model download.
+   */
+  static async downloadModel(sourceLanguage, targetLanguage) {
+    await this.init(
+      normalizeLanguage(sourceLanguage),
+      normalizeLanguage(targetLanguage)
+    );
+  }
+  /**
+   * Creates a Chrome translator instance for the pair.
+   *
+   * @param publishProgress - When true, `downloadprogress` events are forwarded
+   *   as `MODEL_DOWNLOAD_PROGRESS` events (driving the download-progress popup).
+   *   This should only be true for an explicit, consent-driven download
+   *   (`init`/`downloadModel`). When creating an already-downloaded
+   *   (`available`) model in the translate loop, Chrome still emits
+   *   `downloadprogress` while loading the pack from disk into memory; forwarding
+   *   those would wrongly show a "downloading" popup for a model that is already
+   *   downloaded, so the translate-loop path passes `false`.
+   */
+  static async createTranslator(source, target, publishProgress = true) {
     const key = this.generateKey(source, target);
     let resolveReady;
     const readyPromise = new Promise((resolve) => {
@@ -1120,11 +1287,15 @@ var ChromeTranslator = class _ChromeTranslator {
           const loaded = e.loaded ?? 0;
           const total = e.total ?? 0;
           const progress = total > 0 ? Math.round(loaded / total * 100) : 0;
-          getModelDownloadEventHandler().publishModelDownloadProgressEvent(
-            loaded,
-            total,
-            progress
-          );
+          if (publishProgress) {
+            getModelDownloadEventHandler().publishModelDownloadProgressEvent(
+              loaded,
+              total,
+              progress,
+              source,
+              target
+            );
+          }
           if (total > 0 && loaded >= total) {
             resolveReady();
           }
@@ -1141,26 +1312,27 @@ var ChromeTranslator = class _ChromeTranslator {
   }
   static async translate(text, targetLanguage) {
     this.ensureRegistry();
+    const normalizedTarget = normalizeLanguage(targetLanguage);
+    let sourceLanguage = normalizedTarget;
     try {
       const detector = await ChromeLanguageDetector.getInstance();
-      const sourceLanguage = await detector.detectLanguage(text);
-      const key = this.generateKey(sourceLanguage, targetLanguage);
-      if (!this.isSupportedLanguage(sourceLanguage) || !this.isSupportedLanguage(targetLanguage)) {
+      sourceLanguage = normalizeLanguage(await detector.detectLanguage(text));
+      if (!this.isSupportedLanguage(sourceLanguage) || !this.isSupportedLanguage(normalizedTarget)) {
         return {
           translation: text,
           sourceLanguage,
           success: false,
           retryable: false,
-          errorMessage: `Unsupported language pair: ${sourceLanguage} \u2192 ${targetLanguage}`
+          errorMessage: `Unsupported language pair: ${sourceLanguage} \u2192 ${normalizedTarget}`
         };
       }
-      const existingInstance = globalThis.chromeTranslatorRegistry.get(key);
-      if (!existingInstance) {
-        const translatorCapabilities = await Translator.availability({
+      const key = this.generateKey(sourceLanguage, normalizedTarget);
+      if (!globalThis.chromeTranslatorRegistry.has(key)) {
+        const availability = await Translator.availability({
           sourceLanguage,
-          targetLanguage
+          targetLanguage: normalizedTarget
         });
-        if (translatorCapabilities === "unavailable") {
+        if (availability === "unavailable") {
           return {
             translation: text,
             sourceLanguage,
@@ -1169,47 +1341,93 @@ var ChromeTranslator = class _ChromeTranslator {
             errorMessage: "Translation not supported"
           };
         }
-        const chromeTranslator = await this.createTranslator(
-          sourceLanguage,
-          targetLanguage
-        );
-        if (!globalThis.chromeTranslatorRegistry.has(key)) {
-          globalThis.chromeTranslatorRegistry.set(
-            key,
-            new _ChromeTranslator(chromeTranslator)
-          );
+        if (availability !== "available") {
+          const isUserActivationActive = typeof navigator !== "undefined" && (navigator.userActivation?.isActive ?? false);
+          if (isUserActivationActive) {
+            await _ChromeTranslator.downloadModel(
+              sourceLanguage,
+              normalizedTarget
+            );
+            modelDownloadGate.markReady(sourceLanguage, normalizedTarget);
+          } else {
+            await modelDownloadGate.ensureModelReady(
+              sourceLanguage,
+              normalizedTarget
+            );
+          }
         }
       }
-      const instance = globalThis.chromeTranslatorRegistry.get(key);
-      await this.waitForReady(key);
-      this.translatorReadyPromises.delete(key);
-      const translation = await instance.translator?.translate(text);
-      if (!translation) {
-        return {
-          translation: text,
-          sourceLanguage,
-          success: false,
-          errorMessage: "Translation failed",
-          retryable: false
-        };
-      }
-      return {
-        translation,
+      return await this.createInstanceAndTranslate(
+        text,
         sourceLanguage,
-        success: true,
-        retryable: true
-      };
+        normalizedTarget
+      );
     } catch (error) {
+      const isGestureRequired = error instanceof DOMException && error.name === "NotAllowedError";
+      if (isGestureRequired) {
+        try {
+          await modelDownloadGate.ensureModelReady(
+            sourceLanguage,
+            normalizedTarget
+          );
+          return await this.createInstanceAndTranslate(
+            text,
+            sourceLanguage,
+            normalizedTarget
+          );
+        } catch (retryError) {
+          void retryError;
+        }
+      }
       const message = error instanceof Error ? error.message : "Unknown error";
-      const isPermanentFailure = error instanceof DOMException && error.name === "NotSupportedError";
       return {
         translation: text,
-        sourceLanguage: targetLanguage,
+        sourceLanguage,
         success: false,
         errorMessage: message,
-        retryable: !isPermanentFailure
+        retryable: false,
+        requiresGesture: isGestureRequired
+      };
+    }
+  }
+  /**
+   * Creates the translator instance for the pair if it is not already cached,
+   * waits for the model to be ready, and translates the text. The model is
+   * expected to already be downloaded (or downloadable without a gesture) by
+   * the time this is called.
+   */
+  static async createInstanceAndTranslate(text, sourceLanguage, targetLanguage) {
+    const key = this.generateKey(sourceLanguage, targetLanguage);
+    if (!globalThis.chromeTranslatorRegistry.has(key)) {
+      const chromeTranslator = await this.createTranslator(
+        sourceLanguage,
+        targetLanguage,
+        false
+      );
+      globalThis.chromeTranslatorRegistry.set(
+        key,
+        new _ChromeTranslator(chromeTranslator)
+      );
+    }
+    const instance = globalThis.chromeTranslatorRegistry.get(key);
+    await this.waitForReady(key);
+    this.translatorReadyPromises.delete(key);
+    const translation = await instance.translator?.translate(text);
+    if (!translation) {
+      return {
+        translation: text,
+        sourceLanguage,
+        success: false,
+        errorMessage: "Translation failed",
+        retryable: false
       };
     }
+    return {
+      translation,
+      sourceLanguage,
+      success: true,
+      retryable: true
+    };
   }
   static generateKey(sourceLanguage, targetLanguage) {
     return `${sourceLanguage.toUpperCase()}-${targetLanguage.toUpperCase()}`;
@@ -1257,7 +1475,8 @@ var Client2 = class {
             translation: result.translation,
             sourceLanguage: result.sourceLanguage,
             isTranslated: result.success,
-            retryable: result.retryable
+            retryable: result.retryable,
+            requiresGesture: result.requiresGesture ?? false
           }
         ],
         targetLanguage: request.targetLanguage,
@@ -1272,6 +1491,9 @@ var Client2 = class {
       errorMessage
     };
   }
+  async downloadModel(sourceLanguage, targetLanguage) {
+    await ChromeTranslator.downloadModel(sourceLanguage, targetLanguage);
+  }
   getConfig() {
     return this.config;
   }
@@ -1307,6 +1529,10 @@ var Client3 = class {
     const translator = this.getFrontendTranslator();
     return await translator.translateBatch(...args);
   }
+  async downloadModel(sourceLanguage, targetLanguage) {
+    const translator = this.getFrontendTranslator();
+    await translator.downloadModel(sourceLanguage, targetLanguage);
+  }
 };
 
 // src/translators/translator.ts
@@ -1321,6 +1547,17 @@ var Translator2 = class {
     const translatorClient = this.getTranslatorClient();
     return await translatorClient.translateBatch(translationRequests);
   }
+  /**
+   * Downloads the on-device model for a source -> target language pair via the
+   * active translator client. Must be invoked from a user gesture for clients
+   * (e.g. Chrome) that require one to start a model download.
+   */
+  async downloadModel(sourceLanguage, targetLanguage) {
+    await this.getTranslatorClient().downloadModel(
+      sourceLanguage,
+      targetLanguage
+    );
+  }
   setTranslatorClient(config2) {
     if (config2.getToolConfig().strategy === "frontend_translations") {
       this.translatorClient = new Client3(config2);
@@ -1439,6 +1676,9 @@ function AITranslationInnerProvider(props) {
   } = props;
   const [translationProgress, setTranslationProgress] = useState(null);
   const [modelDownloadProgress, setModelDownloadProgress] = useState(null);
+  const [modelConsent, setModelConsent] = useState(
+    null
+  );
   const [config2, setConfig] = useState(new Config());
   const translator = useRef(new Translator2(config2));
   const eventHandler = useRef(new EventHandler(tool));
@@ -1490,6 +1730,14 @@ function AITranslationInnerProvider(props) {
     );
     return () => unsubscribe();
   }, []);
+  useEffect(() => {
+    const unsubscribe = eventHandler.current.subscribeToModelConsentRequiredEvent(
+      (request) => {
+        setModelConsent(request);
+      }
+    );
+    return () => unsubscribe();
+  }, []);
   useEffect(() => {
     if (!isFetched || !remoteConfig) return;
     const toolConfig = remoteConfig[tool] ?? remoteConfig;
@@ -1506,9 +1754,23 @@ function AITranslationInnerProvider(props) {
   config2.setCompanyId(companyId);
   config2.setProjectId(projectId);
   const ait = useCallback(
-    async (text) => enableAIT ? await aitFunction(text, translationRegistry.current, config2, tool) : await Promise.resolve(text),
+    async (text) => {
+      if (!enableAIT) {
+        return text;
+      }
+      return aitFunction(text, translationRegistry.current, config2, tool);
+    },
     [tool, config2, enableAIT]
   );
+  const confirmModelDownload = useCallback(() => {
+    if (!modelConsent) return;
+    if (config2.getToolConfig().strategy !== "frontend_translations") return;
+    const { sourceLanguage, targetLanguage } = modelConsent;
+    setModelConsent(null);
+    translator.current.downloadModel(sourceLanguage, targetLanguage).then(() => modelDownloadGate.markReady(sourceLanguage, targetLanguage)).catch(
+      (error) => modelDownloadGate.markFailed(sourceLanguage, targetLanguage, error)
+    );
+  }, [modelConsent, config2]);
   const contextValue = {
     ait,
     locale,
@@ -1517,6 +1779,8 @@ function AITranslationInnerProvider(props) {
     renderVersion: renderVersionManager.getVersion(),
     translationProgress,
     modelDownloadProgress,
+    modelConsent,
+    confirmModelDownload,
     tool,
     onTrackAnalyticsEvent,
     page,
@@ -1551,8 +1815,8 @@ var BUTTON_TYPE = {
 var ACTION = {
   CLICKED: "clicked"
 };
-function buildObject(pageContext, buttonType) {
-  return `${pageContext}_${buttonType}_button`;
+function buildObject(buttonType) {
+  return `${buttonType}_button`;
 }
 function buildEventKey(parts) {
   const { scope, tool, object, action } = parts;
@@ -1569,7 +1833,7 @@ function buildAnalyticEvent(params) {
     additionalProperties
   } = params;
   const resolvedAction = action ?? ACTION.CLICKED;
-  const object = buildObject(pageContext, buttonType);
+  const object = buildObject(buttonType);
   const key = buildEventKey({
     scope,
     tool,
@@ -1578,6 +1842,7 @@ function buildAnalyticEvent(params) {
   });
   const properties = {
     ...baseProperties,
+    [`${buttonType}_button_location`]: pageContext,
     ...additionalProperties
   };
   return { key, properties };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@procore/ai-translations",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Library that provides a solution to use AI to translate text into a language",
   "main": "dist/legacy/index.js",
   "types": "dist/legacy/index.d.ts",