@procore/ai-translations 0.8.1 → 0.9.0

package/README.md

@@ -4,14 +4,14 @@ React package for AI-powered UI string translation in frontend apps. It provides
 
 - `AITranslationProvider` to initialize translation context
 - `AITranslateText` to render translated text
-- `useAITranslation` for direct access to translation and progress state
+- `useAITranslation` for direct access to translation, consent, and progress state
 
 Need deeper implementation details? See the internal guide: [`README.internal.md`](./README.internal.md).
 
 This package supports two runtime strategies:
 
-- `frontend_translations`: browser-based translation (Chrome-family AI APIs)
-- `backend_translations`: server-side translation API
+- `frontend_translations`: browser-based translation (Chrome-family AI APIs). Translation runs sequentially and is gated on user consent when an on-device model must be downloaded.
+- `backend_translations`: server-side translation API. No on-device model downloads; model-consent popups are suppressed automatically.
 
 For Procore-specific operational details, see `README.internal.md`.
 
@@ -190,8 +190,21 @@ Returns:
 - `tool: string`
 - `translationProgress: { progress: number; current: number; total: number } | null`
 - `modelDownloadProgress: ModelDownloadProgress | null`
+- `modelConsent: ModelConsentRequest | null` - non-null while the translation run is paused awaiting user consent to download a source→target model; `null` otherwise
+- `confirmModelDownload: () => void` - call this (e.g. from a Download button's `onClick`) to provide the required user gesture, start the download, and resume translation; no-op when `modelConsent` is `null` or when the active strategy is `backend_translations`
 - `renderVersion: number | undefined`
 
+### `normalizeLanguage(language: string): string`
+
+Utility that strips the region/script subtag from a BCP-47 language tag (e.g. `"en-US"` → `"en"`). Falls back to the original string when no subtag is present.
+
+```ts
+import { normalizeLanguage } from '@procore/ai-translations';
+
+normalizeLanguage('en-US'); // 'en'
+normalizeLanguage('fr'); // 'fr'
+```
+
 ### Feature flag helpers
 
 - `AI_TRANSLATION_FEATURE_FLAG_KEY`
@@ -210,14 +223,35 @@ queueText --> manager[TranslationManager]
 manager --> strategy[TranslatorStrategy]
 strategy --> frontendClient[ChromeFrontendClient]
 strategy --> backendClient[BackendApiClient]
-frontendClient --> persist[PersistToIndexedDB]
+frontendClient --> modelGate{ModelDownloadGate}
+modelGate -- model ready --> translate[Translate]
+modelGate -- model missing --> consentEvent[MODEL_CONSENT_REQUIRED event]
+consentEvent --> popup[ModelDownloadConsentPopup]
+popup -- user clicks Download --> confirmModelDownload[confirmModelDownload]
+confirmModelDownload --> downloadModel[downloadModel]
+downloadModel --> markReady[gate.markReady]
+markReady --> translate
+translate --> persist[PersistToIndexedDB]
 backendClient --> persist
 persist --> publish[PublishTranslationEvents]
 publish --> rerender[AITranslateTextRerender]
 rerender --> translatedUi[DisplayTranslatedText]
 ```
 
-At runtime, strings are registered through `ait()`, processed in batches, cached in memory and IndexedDB, and then rerendered via package events.
+At runtime, strings are registered through `ait()`, processed sequentially (frontend strategy) or in configurable batches (backend strategy), cached in memory and IndexedDB, and then rerendered via package events.
+
+### Frontend model-download consent flow
+
+When the `frontend_translations` strategy encounters a source→target model that has not yet been downloaded, Chrome requires a user gesture to initiate the download. The package handles this automatically:
+
+1. The translation run **pauses** and fires a `MODEL_CONSENT_REQUIRED` event carrying `{ sourceLanguage, targetLanguage }`.
+2. `useAITranslation().modelConsent` becomes non-null — render `<ModelDownloadConsentPopup />` (from `@procore/ai-translation-utils`) to surface the consent UI to the user.
+3. The user clicks the **Download** button, calling `confirmModelDownload()` which provides the required gesture, starts the download, and shows `<ModelDownloadProgressPopup />`.
+4. When the download completes, `modelDownloadGate.markReady(source, target)` is called and the paused translation run **resumes automatically**.
+5. Steps 1–4 repeat for each unique source→target model pair that is not yet cached. Already-downloaded models skip the consent step entirely.
+6. After all texts are translated the run terminates. Translated text is displayed immediately as each translation completes, not only at the end.
+
+> **Important**: your app must render `<ModelDownloadConsentPopup />` inside `AITranslationProvider` for the consent flow to work. Without it, `ensureModelReady` will never resolve and the translation run will hang indefinitely.
 
 ## Configuration
 

package/dist/legacy/index.d.mts

@@ -64,6 +64,20 @@ interface ModelDownloadProgress {
     progress: number;
     /** True once the model has finished downloading */
     isComplete: boolean;
+    /** Source language of the model being downloaded (e.g. `"fr"`) */
+    sourceLanguage: string;
+    /** Target language of the model being downloaded (e.g. `"en"`) */
+    targetLanguage: string;
+}
+/**
+ * A pending request for the user to consent to downloading a specific
+ * source -> target language model before translation can continue.
+ */
+interface ModelConsentRequest {
+    /** Source language of the model that needs downloading (e.g. `"fr"`). */
+    sourceLanguage: string;
+    /** Target language of the model that needs downloading (e.g. `"en"`). */
+    targetLanguage: string;
 }
 interface AITranslationContextValue {
     ait: (text: string) => Promise<string>;
@@ -77,6 +91,17 @@ interface AITranslationContextValue {
     translationProgress: TranslationProgress | null;
     /** Chrome AI model download progress; `null` until a download begins. */
     modelDownloadProgress: ModelDownloadProgress | null;
+    /**
+     * Pending model the translation run is paused on, awaiting the user's consent
+     * to download; `null` when no consent is required.
+     */
+    modelConsent: ModelConsentRequest | null;
+    /**
+     * Confirms the pending {@link modelConsent} download. Must be called from a
+     * user gesture (e.g. a click handler) since Chrome requires a gesture to
+     * start a model download.
+     */
+    confirmModelDownload: () => void;
     tool: string;
     /** Called by `useAIAnalytics` with a fully assembled event. The MFE is responsible for sending it. */
     onTrackAnalyticsEvent?: AIAnalyticsTracker;
@@ -171,7 +196,7 @@ type Action = (typeof ACTION)[keyof typeof ACTION];
  * Builds the `object` segment: `{pageContext}_{buttonType}_button`
  * e.g. `buildObject('view', 'translate')` → `'view_translate_button'`
  */
-declare function buildObject(pageContext: string, buttonType: ButtonType): string;
+declare function buildObject(buttonType: ButtonType): string;
 /**
  * Builds a fully-qualified event key:
  * `ux.web.feature.{scope}.{tool}.{object}.{action}`
@@ -335,4 +360,4 @@ declare global {
     var _BACKEND_AI_TRANSLATION_IN_PROGRESS_: boolean;
 }
 
-export { ACTION, type AIAnalyticsEventProperties, type AIAnalyticsTracker, AITranslateText, type AITranslateTextProps, AITranslationProvider, AI_TRANSLATION_FEATURE_FLAG_KEY, type Action, type AnalyticEvent, BUTTON_TYPE, type BuildAnalyticEventParams, type ButtonType, CustomizableAITranslateText, type CustomizableAITranslateTextProps, type EventKeyParts, type Scope, type TextSegmenter, type TranslatableSegment, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, isSupportedBrowser, useAIAnalytics, useAITranslation, useConfig };
+export { ACTION, type AIAnalyticsEventProperties, type AIAnalyticsTracker, AITranslateText, type AITranslateTextProps, AITranslationProvider, AI_TRANSLATION_FEATURE_FLAG_KEY, type Action, type AnalyticEvent, BUTTON_TYPE, type BuildAnalyticEventParams, type ButtonType, CustomizableAITranslateText, type CustomizableAITranslateTextProps, type EventKeyParts, type ModelConsentRequest, type ModelDownloadProgress, type Scope, type TextSegmenter, type TranslatableSegment, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, isSupportedBrowser, useAIAnalytics, useAITranslation, useConfig };

package/dist/legacy/index.d.ts

@@ -64,6 +64,20 @@ interface ModelDownloadProgress {
     progress: number;
     /** True once the model has finished downloading */
     isComplete: boolean;
+    /** Source language of the model being downloaded (e.g. `"fr"`) */
+    sourceLanguage: string;
+    /** Target language of the model being downloaded (e.g. `"en"`) */
+    targetLanguage: string;
+}
+/**
+ * A pending request for the user to consent to downloading a specific
+ * source -> target language model before translation can continue.
+ */
+interface ModelConsentRequest {
+    /** Source language of the model that needs downloading (e.g. `"fr"`). */
+    sourceLanguage: string;
+    /** Target language of the model that needs downloading (e.g. `"en"`). */
+    targetLanguage: string;
 }
 interface AITranslationContextValue {
     ait: (text: string) => Promise<string>;
@@ -77,6 +91,17 @@ interface AITranslationContextValue {
     translationProgress: TranslationProgress | null;
     /** Chrome AI model download progress; `null` until a download begins. */
     modelDownloadProgress: ModelDownloadProgress | null;
+    /**
+     * Pending model the translation run is paused on, awaiting the user's consent
+     * to download; `null` when no consent is required.
+     */
+    modelConsent: ModelConsentRequest | null;
+    /**
+     * Confirms the pending {@link modelConsent} download. Must be called from a
+     * user gesture (e.g. a click handler) since Chrome requires a gesture to
+     * start a model download.
+     */
+    confirmModelDownload: () => void;
     tool: string;
     /** Called by `useAIAnalytics` with a fully assembled event. The MFE is responsible for sending it. */
     onTrackAnalyticsEvent?: AIAnalyticsTracker;
@@ -171,7 +196,7 @@ type Action = (typeof ACTION)[keyof typeof ACTION];
  * Builds the `object` segment: `{pageContext}_{buttonType}_button`
  * e.g. `buildObject('view', 'translate')` → `'view_translate_button'`
  */
-declare function buildObject(pageContext: string, buttonType: ButtonType): string;
+declare function buildObject(buttonType: ButtonType): string;
 /**
  * Builds a fully-qualified event key:
  * `ux.web.feature.{scope}.{tool}.{object}.{action}`
@@ -335,4 +360,4 @@ declare global {
     var _BACKEND_AI_TRANSLATION_IN_PROGRESS_: boolean;
 }
 
-export { ACTION, type AIAnalyticsEventProperties, type AIAnalyticsTracker, AITranslateText, type AITranslateTextProps, AITranslationProvider, AI_TRANSLATION_FEATURE_FLAG_KEY, type Action, type AnalyticEvent, BUTTON_TYPE, type BuildAnalyticEventParams, type ButtonType, CustomizableAITranslateText, type CustomizableAITranslateTextProps, type EventKeyParts, type Scope, type TextSegmenter, type TranslatableSegment, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, isSupportedBrowser, useAIAnalytics, useAITranslation, useConfig };
+export { ACTION, type AIAnalyticsEventProperties, type AIAnalyticsTracker, AITranslateText, type AITranslateTextProps, AITranslationProvider, AI_TRANSLATION_FEATURE_FLAG_KEY, type Action, type AnalyticEvent, BUTTON_TYPE, type BuildAnalyticEventParams, type ButtonType, CustomizableAITranslateText, type CustomizableAITranslateTextProps, type EventKeyParts, type ModelConsentRequest, type ModelDownloadProgress, type Scope, type TextSegmenter, type TranslatableSegment, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, isSupportedBrowser, useAIAnalytics, useAITranslation, useConfig };