@procore/ai-translations 0.7.0 → 0.8.1

package/README.md

@@ -81,6 +81,104 @@ Props:
 - `showHighlight?: boolean` (default `false`)
 - `translatedIconProps?: TranslatedIconProps`
 
+### `CustomizableAITranslateText`
+
+Translates only chosen substrings of a string. Use anywhere a value mixes translatable and non-translatable text — descriptions, status fields, breadcrumbs, tags, cards, forms, modals — not just data tables.
+
+Supply a `segmenter` function that splits the full text into an ordered list of `{ text, translate }` segments. Only segments with `translate: true` are sent through the AI pipeline; the rest are rendered verbatim.
+
+Props:
+
+- `text: string` — the full text value, passed to `segmenter`
+- `shouldTranslate: boolean` — master switch; when `false` all segments render as plain text
+- `showHighlight?: boolean` (default `false`) — whether to show the `TranslatedIcon`
+- `highlightMode?: 'segment' | 'cell'` (default `'segment'`) — see below
+- `segmenter?: (text: string) => TranslatableSegment[]` — split rule; when omitted the whole text is one translatable segment
+- `translatedIconProps?: TranslatedIconProps`
+
+#### Segmenter examples
+
+**`"{code} - {label}"`** — keep the code prefix, translate only the label:
+
+```tsx
+import { CustomizableAITranslateText } from '@procore/ai-translations';
+
+<CustomizableAITranslateText
+  text="INS-001 - Safety Inspection"
+  shouldTranslate={true}
+  segmenter={(text) => {
+    const idx = text.indexOf(' - ');
+    if (idx === -1) return [{ text, translate: true }];
+    return [
+      { text: text.slice(0, idx + 3), translate: false }, // "INS-001 - "
+      { text: text.slice(idx + 3), translate: true }, // "Safety Inspection"
+    ];
+  }}
+/>;
+```
+
+**`"Key: Value"`** — keep the field name, translate only the value:
+
+```tsx
+<CustomizableAITranslateText
+  text="Status: Awaiting Review"
+  shouldTranslate={true}
+  segmenter={(text) => {
+    const idx = text.indexOf(': ');
+    if (idx === -1) return [{ text, translate: true }];
+    return [
+      { text: text.slice(0, idx + 2), translate: false }, // "Status: "
+      { text: text.slice(idx + 2), translate: true }, // "Awaiting Review"
+    ];
+  }}
+/>
+```
+
+**`"A | B"`** — translate both halves, keep the divider:
+
+```tsx
+<CustomizableAITranslateText
+  text="Safety | Critical"
+  shouldTranslate={true}
+  segmenter={(text) => {
+    const idx = text.indexOf(' | ');
+    if (idx === -1) return [{ text, translate: true }];
+    return [
+      { text: text.slice(0, idx), translate: true }, // "Safety"
+      { text: ' | ', translate: false }, // " | "
+      { text: text.slice(idx + 3), translate: true }, // "Critical"
+    ];
+  }}
+/>
+```
+
+**`"A > B > C"` breadcrumb** — translate every crumb independently:
+
+```tsx
+<CustomizableAITranslateText
+  text="Projects > Building A > Floor 3"
+  shouldTranslate={true}
+  segmenter={(text) => {
+    const parts = text.split(' > ');
+    return parts.flatMap((part, i) => [
+      { text: part, translate: true },
+      ...(i < parts.length - 1 ? [{ text: ' > ', translate: false }] : []),
+    ]);
+  }}
+/>
+```
+
+#### `highlightMode`
+
+Controls where `TranslatedIcon` appears when a translation actually changes the text:
+
+| Mode                  | Behavior                                                                                                                                                  |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'segment'` (default) | One icon next to each segment whose translated output differs from its source. Precisely marks which substrings are AI-generated.                         |
+| `'cell'`              | A single icon at the very start of the value, only when at least one segment's output actually changed. Cleaner for values with many translated segments. |
+
+`showHighlight={false}` suppresses all icons regardless of mode.
+
 ### `useAITranslation()`
 
 Returns:

package/dist/legacy/index.d.mts

@@ -263,10 +263,64 @@ interface AITranslateTextProps {
  */
 declare const AITranslateText: React.FC<AITranslateTextProps>;
 
+/**
+ * A single piece of a text value. When `translate` is `true`, the segment is
+ * sent through the AI translation pipeline; otherwise it is rendered as plain
+ * text and never reaches the registry.
+ */
+interface TranslatableSegment {
+    text: string;
+    translate: boolean;
+}
+/**
+ * Pure function that turns a string into an ordered list of translatable /
+ * non-translatable segments. Called on every render, so it should be
+ * inexpensive and free of side effects.
+ */
+type TextSegmenter = (text: string) => TranslatableSegment[];
+interface CustomizableAITranslateTextProps {
+    /** The full text value. Fed to the segmenter or — when no segmenter is
+     * supplied — translated as a single piece. */
+    text: string;
+    shouldTranslate: boolean;
+    /** Master switch for the highlight icon. Defaults to `false`. When `true`,
+     * a single icon is shown at the start of the value if at least one segment's
+     * translation actually changed the source text. */
+    showHighlight?: boolean;
+    segmenter?: TextSegmenter;
+    translatedIconProps?: TranslatedIconProps;
+}
+/**
+ * Generic component for translating chosen substrings of a string. Owns its
+ * translation lifecycle directly (does not compose `AITranslateText`), so it
+ * can decide whether a cell-level highlight icon is appropriate based on
+ * whether any segment's translation actually changed the source.
+ *
+ * When `showHighlight` is `true`, a single icon is rendered at the start of
+ * the value if at least one segment changed — i.e. always cell-level mode.
+ *
+ * @example
+ * // Translate only the label half of "{code} - {label}"
+ * <CustomizableAITranslateText
+ *   text="INS-001 - Safety Inspection"
+ *   shouldTranslate={true}
+ *   showHighlight={true}
+ *   segmenter={(t) => {
+ *     const idx = t.indexOf(' - ');
+ *     if (idx === -1) return [{ text: t, translate: true }];
+ *     return [
+ *       { text: t.slice(0, idx + 3), translate: false },
+ *       { text: t.slice(idx + 3), translate: true },
+ *     ];
+ *   }}
+ * />
+ */
+declare const CustomizableAITranslateText: React.FC<CustomizableAITranslateTextProps>;
+
 /**
  * The key used to store/retrieve the feature flag in local storage.
  */
-declare const AI_TRANSLATION_FEATURE_FLAG_KEY = "pe_ai_translations_web_program_visible";
+declare const AI_TRANSLATION_FEATURE_FLAG_KEY = "ai-translation";
 /**
  * Retrieves the LD ID for the AI translation feature flag based on the domain.
  * @param domain - The domain to determine the LD ID for
@@ -281,4 +335,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, type EventKeyParts, type Scope, 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 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

@@ -263,10 +263,64 @@ interface AITranslateTextProps {
  */
 declare const AITranslateText: React.FC<AITranslateTextProps>;
 
+/**
+ * A single piece of a text value. When `translate` is `true`, the segment is
+ * sent through the AI translation pipeline; otherwise it is rendered as plain
+ * text and never reaches the registry.
+ */
+interface TranslatableSegment {
+    text: string;
+    translate: boolean;
+}
+/**
+ * Pure function that turns a string into an ordered list of translatable /
+ * non-translatable segments. Called on every render, so it should be
+ * inexpensive and free of side effects.
+ */
+type TextSegmenter = (text: string) => TranslatableSegment[];
+interface CustomizableAITranslateTextProps {
+    /** The full text value. Fed to the segmenter or — when no segmenter is
+     * supplied — translated as a single piece. */
+    text: string;
+    shouldTranslate: boolean;
+    /** Master switch for the highlight icon. Defaults to `false`. When `true`,
+     * a single icon is shown at the start of the value if at least one segment's
+     * translation actually changed the source text. */
+    showHighlight?: boolean;
+    segmenter?: TextSegmenter;
+    translatedIconProps?: TranslatedIconProps;
+}
+/**
+ * Generic component for translating chosen substrings of a string. Owns its
+ * translation lifecycle directly (does not compose `AITranslateText`), so it
+ * can decide whether a cell-level highlight icon is appropriate based on
+ * whether any segment's translation actually changed the source.
+ *
+ * When `showHighlight` is `true`, a single icon is rendered at the start of
+ * the value if at least one segment changed — i.e. always cell-level mode.
+ *
+ * @example
+ * // Translate only the label half of "{code} - {label}"
+ * <CustomizableAITranslateText
+ *   text="INS-001 - Safety Inspection"
+ *   shouldTranslate={true}
+ *   showHighlight={true}
+ *   segmenter={(t) => {
+ *     const idx = t.indexOf(' - ');
+ *     if (idx === -1) return [{ text: t, translate: true }];
+ *     return [
+ *       { text: t.slice(0, idx + 3), translate: false },
+ *       { text: t.slice(idx + 3), translate: true },
+ *     ];
+ *   }}
+ * />
+ */
+declare const CustomizableAITranslateText: React.FC<CustomizableAITranslateTextProps>;
+
 /**
  * The key used to store/retrieve the feature flag in local storage.
  */
-declare const AI_TRANSLATION_FEATURE_FLAG_KEY = "pe_ai_translations_web_program_visible";
+declare const AI_TRANSLATION_FEATURE_FLAG_KEY = "ai-translation";
 /**
  * Retrieves the LD ID for the AI translation feature flag based on the domain.
  * @param domain - The domain to determine the LD ID for
@@ -281,4 +335,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, type EventKeyParts, type Scope, 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 Scope, type TextSegmenter, type TranslatableSegment, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, isSupportedBrowser, useAIAnalytics, useAITranslation, useConfig };

package/dist/legacy/index.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __export = (target, all) => {
@@ -16,6 +18,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
@@ -27,6 +37,7 @@ __export(index_exports, {
   AITranslationProvider: () => AITranslationProvider,
   AI_TRANSLATION_FEATURE_FLAG_KEY: () => AI_TRANSLATION_FEATURE_FLAG_KEY,
   BUTTON_TYPE: () => BUTTON_TYPE,
+  CustomizableAITranslateText: () => CustomizableAITranslateText,
   buildAnalyticEvent: () => buildAnalyticEvent,
   buildEventKey: () => buildEventKey,
   buildObject: () => buildObject,
@@ -1254,12 +1265,13 @@ var _ChromeTranslator = class _ChromeTranslator {
       };
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
+      const isPermanentFailure = error instanceof DOMException && error.name === "NotSupportedError";
       return {
         translation: text,
         sourceLanguage: targetLanguage,
         success: false,
         errorMessage: message,
-        retryable: true
+        retryable: !isPermanentFailure
       };
     }
   }
@@ -1825,9 +1837,93 @@ var AITranslateText = ({
   ] });
 };
 
+// src/components/CustomizableAITranslateText.tsx
+var import_react6 = __toESM(require("react"));
+var import_jsx_runtime4 = require("react/jsx-runtime");
+var CustomizableAITranslateText = ({
+  text,
+  shouldTranslate,
+  showHighlight = false,
+  segmenter,
+  translatedIconProps
+}) => {
+  const context = (0, import_react6.useContext)(AITranslationContext);
+  const ait = context == null ? void 0 : context.ait;
+  const segments = (0, import_react6.useMemo)(
+    () => segmenter ? segmenter(text) : [{ text, translate: shouldTranslate }],
+    [segmenter, text, shouldTranslate]
+  );
+  const [displayTexts, setDisplayTexts] = (0, import_react6.useState)(
+    () => segments.map((s) => s.text)
+  );
+  const segmentsKey = JSON.stringify(segments);
+  (0, import_react6.useEffect)(() => {
+    setDisplayTexts(segments.map((s) => s.text));
+  }, [segmentsKey]);
+  (0, import_react6.useEffect)(() => {
+    if (!ait || !shouldTranslate) {
+      setDisplayTexts(segments.map((s) => s.text));
+      return;
+    }
+    let cancelled = false;
+    Promise.all(
+      segments.map((s) => s.translate ? ait(s.text) : Promise.resolve(s.text))
+    ).then((resolved) => {
+      if (cancelled) return;
+      setDisplayTexts(resolved);
+    }).catch(() => {
+      if (cancelled) return;
+      setDisplayTexts(segments.map((s) => s.text));
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [ait, shouldTranslate, segmentsKey]);
+  const eventHandlerRef = (0, import_react6.useRef)(null);
+  (0, import_react6.useEffect)(() => {
+    if (!context) return;
+    if (!eventHandlerRef.current) {
+      eventHandlerRef.current = new EventHandler(context.tool);
+    }
+    const unsubscribe = eventHandlerRef.current.subscribeToRerenderEvent(
+      async (sourceTexts) => {
+        if (!shouldTranslate) return;
+        if (!sourceTexts || sourceTexts.length === 0) return;
+        const sourceSet = new Set(sourceTexts);
+        const targets = segments.map((s, i) => ({ s, i })).filter(({ s }) => s.translate && sourceSet.has(s.text));
+        if (targets.length === 0) return;
+        const fresh = await Promise.all(
+          targets.map(({ s }) => context.ait(s.text))
+        );
+        setDisplayTexts((prev) => {
+          const next = [...prev];
+          targets.forEach(({ i }, j) => {
+            const value = fresh[j];
+            if (value !== void 0) next[i] = value;
+          });
+          return next;
+        });
+      }
+    );
+    return () => unsubscribe();
+  }, [context, shouldTranslate, segmentsKey]);
+  const changedFlags = segments.map(
+    (s, i) => s.translate && shouldTranslate && (displayTexts[i] ?? s.text) !== s.text
+  );
+  const anyChanged = changedFlags.some(Boolean);
+  const showCellIcon = showHighlight && anyChanged;
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(import_jsx_runtime4.Fragment, { children: [
+    showCellIcon && /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(TranslatedIcon, { ...translatedIconProps }),
+    segments.map((seg, i) => {
+      const display = displayTexts[i] ?? seg.text;
+      return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_react6.default.Fragment, { children: display }, `${i}-${seg.text}`);
+    })
+  ] });
+};
+
 // src/utils/featureFlag.ts
 var import_web_sdk_mfe_utils = require("@procore/web-sdk-mfe-utils");
-var AI_TRANSLATION_FEATURE_FLAG_KEY = "pe_ai_translations_web_program_visible";
+var AI_TRANSLATION_FEATURE_FLAG_KEY = "ai-translation";
 var getAITranslationLDId = (domain) => {
   const { environment, zone } = (0, import_web_sdk_mfe_utils.getProcoreZone)(domain);
   if ((0, import_web_sdk_mfe_utils.isFederalZone)(zone)) {
@@ -1850,6 +1946,7 @@ var getAITranslationLDId = (domain) => {
   AITranslationProvider,
   AI_TRANSLATION_FEATURE_FLAG_KEY,
   BUTTON_TYPE,
+  CustomizableAITranslateText,
   buildAnalyticEvent,
   buildEventKey,
   buildObject,

package/dist/legacy/index.mjs

@@ -1224,12 +1224,13 @@ var _ChromeTranslator = class _ChromeTranslator {
       };
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
+      const isPermanentFailure = error instanceof DOMException && error.name === "NotSupportedError";
       return {
         translation: text,
         sourceLanguage: targetLanguage,
         success: false,
         errorMessage: message,
-        retryable: true
+        retryable: !isPermanentFailure
       };
     }
   }
@@ -1801,9 +1802,93 @@ var AITranslateText = ({
   ] });
 };
 
+// src/components/CustomizableAITranslateText.tsx
+import React4, { useContext as useContext4, useEffect as useEffect3, useMemo, useRef as useRef3, useState as useState3 } from "react";
+import { Fragment as Fragment2, jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
+var CustomizableAITranslateText = ({
+  text,
+  shouldTranslate,
+  showHighlight = false,
+  segmenter,
+  translatedIconProps
+}) => {
+  const context = useContext4(AITranslationContext);
+  const ait = context == null ? void 0 : context.ait;
+  const segments = useMemo(
+    () => segmenter ? segmenter(text) : [{ text, translate: shouldTranslate }],
+    [segmenter, text, shouldTranslate]
+  );
+  const [displayTexts, setDisplayTexts] = useState3(
+    () => segments.map((s) => s.text)
+  );
+  const segmentsKey = JSON.stringify(segments);
+  useEffect3(() => {
+    setDisplayTexts(segments.map((s) => s.text));
+  }, [segmentsKey]);
+  useEffect3(() => {
+    if (!ait || !shouldTranslate) {
+      setDisplayTexts(segments.map((s) => s.text));
+      return;
+    }
+    let cancelled = false;
+    Promise.all(
+      segments.map((s) => s.translate ? ait(s.text) : Promise.resolve(s.text))
+    ).then((resolved) => {
+      if (cancelled) return;
+      setDisplayTexts(resolved);
+    }).catch(() => {
+      if (cancelled) return;
+      setDisplayTexts(segments.map((s) => s.text));
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [ait, shouldTranslate, segmentsKey]);
+  const eventHandlerRef = useRef3(null);
+  useEffect3(() => {
+    if (!context) return;
+    if (!eventHandlerRef.current) {
+      eventHandlerRef.current = new EventHandler(context.tool);
+    }
+    const unsubscribe = eventHandlerRef.current.subscribeToRerenderEvent(
+      async (sourceTexts) => {
+        if (!shouldTranslate) return;
+        if (!sourceTexts || sourceTexts.length === 0) return;
+        const sourceSet = new Set(sourceTexts);
+        const targets = segments.map((s, i) => ({ s, i })).filter(({ s }) => s.translate && sourceSet.has(s.text));
+        if (targets.length === 0) return;
+        const fresh = await Promise.all(
+          targets.map(({ s }) => context.ait(s.text))
+        );
+        setDisplayTexts((prev) => {
+          const next = [...prev];
+          targets.forEach(({ i }, j) => {
+            const value = fresh[j];
+            if (value !== void 0) next[i] = value;
+          });
+          return next;
+        });
+      }
+    );
+    return () => unsubscribe();
+  }, [context, shouldTranslate, segmentsKey]);
+  const changedFlags = segments.map(
+    (s, i) => s.translate && shouldTranslate && (displayTexts[i] ?? s.text) !== s.text
+  );
+  const anyChanged = changedFlags.some(Boolean);
+  const showCellIcon = showHighlight && anyChanged;
+  return /* @__PURE__ */ jsxs2(Fragment2, { children: [
+    showCellIcon && /* @__PURE__ */ jsx4(TranslatedIcon, { ...translatedIconProps }),
+    segments.map((seg, i) => {
+      const display = displayTexts[i] ?? seg.text;
+      return /* @__PURE__ */ jsx4(React4.Fragment, { children: display }, `${i}-${seg.text}`);
+    })
+  ] });
+};
+
 // src/utils/featureFlag.ts
 import { isFederalZone, getProcoreZone } from "@procore/web-sdk-mfe-utils";
-var AI_TRANSLATION_FEATURE_FLAG_KEY = "pe_ai_translations_web_program_visible";
+var AI_TRANSLATION_FEATURE_FLAG_KEY = "ai-translation";
 var getAITranslationLDId = (domain) => {
   const { environment, zone } = getProcoreZone(domain);
   if (isFederalZone(zone)) {
@@ -1825,6 +1910,7 @@ export {
   AITranslationProvider,
   AI_TRANSLATION_FEATURE_FLAG_KEY,
   BUTTON_TYPE,
+  CustomizableAITranslateText,
   buildAnalyticEvent,
   buildEventKey,
   buildObject,

package/dist/modern/index.d.mts

@@ -263,10 +263,64 @@ interface AITranslateTextProps {
  */
 declare const AITranslateText: React.FC<AITranslateTextProps>;
 
+/**
+ * A single piece of a text value. When `translate` is `true`, the segment is
+ * sent through the AI translation pipeline; otherwise it is rendered as plain
+ * text and never reaches the registry.
+ */
+interface TranslatableSegment {
+    text: string;
+    translate: boolean;
+}
+/**
+ * Pure function that turns a string into an ordered list of translatable /
+ * non-translatable segments. Called on every render, so it should be
+ * inexpensive and free of side effects.
+ */
+type TextSegmenter = (text: string) => TranslatableSegment[];
+interface CustomizableAITranslateTextProps {
+    /** The full text value. Fed to the segmenter or — when no segmenter is
+     * supplied — translated as a single piece. */
+    text: string;
+    shouldTranslate: boolean;
+    /** Master switch for the highlight icon. Defaults to `false`. When `true`,
+     * a single icon is shown at the start of the value if at least one segment's
+     * translation actually changed the source text. */
+    showHighlight?: boolean;
+    segmenter?: TextSegmenter;
+    translatedIconProps?: TranslatedIconProps;
+}
+/**
+ * Generic component for translating chosen substrings of a string. Owns its
+ * translation lifecycle directly (does not compose `AITranslateText`), so it
+ * can decide whether a cell-level highlight icon is appropriate based on
+ * whether any segment's translation actually changed the source.
+ *
+ * When `showHighlight` is `true`, a single icon is rendered at the start of
+ * the value if at least one segment changed — i.e. always cell-level mode.
+ *
+ * @example
+ * // Translate only the label half of "{code} - {label}"
+ * <CustomizableAITranslateText
+ *   text="INS-001 - Safety Inspection"
+ *   shouldTranslate={true}
+ *   showHighlight={true}
+ *   segmenter={(t) => {
+ *     const idx = t.indexOf(' - ');
+ *     if (idx === -1) return [{ text: t, translate: true }];
+ *     return [
+ *       { text: t.slice(0, idx + 3), translate: false },
+ *       { text: t.slice(idx + 3), translate: true },
+ *     ];
+ *   }}
+ * />
+ */
+declare const CustomizableAITranslateText: React.FC<CustomizableAITranslateTextProps>;
+
 /**
  * The key used to store/retrieve the feature flag in local storage.
  */
-declare const AI_TRANSLATION_FEATURE_FLAG_KEY = "pe_ai_translations_web_program_visible";
+declare const AI_TRANSLATION_FEATURE_FLAG_KEY = "ai-translation";
 /**
  * Retrieves the LD ID for the AI translation feature flag based on the domain.
  * @param domain - The domain to determine the LD ID for
@@ -281,4 +335,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, type EventKeyParts, type Scope, 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 Scope, type TextSegmenter, type TranslatableSegment, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, isSupportedBrowser, useAIAnalytics, useAITranslation, useConfig };

package/dist/modern/index.d.ts

@@ -263,10 +263,64 @@ interface AITranslateTextProps {
  */
 declare const AITranslateText: React.FC<AITranslateTextProps>;
 
+/**
+ * A single piece of a text value. When `translate` is `true`, the segment is
+ * sent through the AI translation pipeline; otherwise it is rendered as plain
+ * text and never reaches the registry.
+ */
+interface TranslatableSegment {
+    text: string;
+    translate: boolean;
+}
+/**
+ * Pure function that turns a string into an ordered list of translatable /
+ * non-translatable segments. Called on every render, so it should be
+ * inexpensive and free of side effects.
+ */
+type TextSegmenter = (text: string) => TranslatableSegment[];
+interface CustomizableAITranslateTextProps {
+    /** The full text value. Fed to the segmenter or — when no segmenter is
+     * supplied — translated as a single piece. */
+    text: string;
+    shouldTranslate: boolean;
+    /** Master switch for the highlight icon. Defaults to `false`. When `true`,
+     * a single icon is shown at the start of the value if at least one segment's
+     * translation actually changed the source text. */
+    showHighlight?: boolean;
+    segmenter?: TextSegmenter;
+    translatedIconProps?: TranslatedIconProps;
+}
+/**
+ * Generic component for translating chosen substrings of a string. Owns its
+ * translation lifecycle directly (does not compose `AITranslateText`), so it
+ * can decide whether a cell-level highlight icon is appropriate based on
+ * whether any segment's translation actually changed the source.
+ *
+ * When `showHighlight` is `true`, a single icon is rendered at the start of
+ * the value if at least one segment changed — i.e. always cell-level mode.
+ *
+ * @example
+ * // Translate only the label half of "{code} - {label}"
+ * <CustomizableAITranslateText
+ *   text="INS-001 - Safety Inspection"
+ *   shouldTranslate={true}
+ *   showHighlight={true}
+ *   segmenter={(t) => {
+ *     const idx = t.indexOf(' - ');
+ *     if (idx === -1) return [{ text: t, translate: true }];
+ *     return [
+ *       { text: t.slice(0, idx + 3), translate: false },
+ *       { text: t.slice(idx + 3), translate: true },
+ *     ];
+ *   }}
+ * />
+ */
+declare const CustomizableAITranslateText: React.FC<CustomizableAITranslateTextProps>;
+
 /**
  * The key used to store/retrieve the feature flag in local storage.
  */
-declare const AI_TRANSLATION_FEATURE_FLAG_KEY = "pe_ai_translations_web_program_visible";
+declare const AI_TRANSLATION_FEATURE_FLAG_KEY = "ai-translation";
 /**
  * Retrieves the LD ID for the AI translation feature flag based on the domain.
  * @param domain - The domain to determine the LD ID for
@@ -281,4 +335,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, type EventKeyParts, type Scope, 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 Scope, type TextSegmenter, type TranslatableSegment, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, isSupportedBrowser, useAIAnalytics, useAITranslation, useConfig };

package/dist/modern/index.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -25,6 +35,7 @@ __export(index_exports, {
   AITranslationProvider: () => AITranslationProvider,
   AI_TRANSLATION_FEATURE_FLAG_KEY: () => AI_TRANSLATION_FEATURE_FLAG_KEY,
   BUTTON_TYPE: () => BUTTON_TYPE,
+  CustomizableAITranslateText: () => CustomizableAITranslateText,
   buildAnalyticEvent: () => buildAnalyticEvent,
   buildEventKey: () => buildEventKey,
   buildObject: () => buildObject,
@@ -1233,12 +1244,13 @@ var ChromeTranslator = class _ChromeTranslator {
       };
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
+      const isPermanentFailure = error instanceof DOMException && error.name === "NotSupportedError";
       return {
         translation: text,
         sourceLanguage: targetLanguage,
         success: false,
         errorMessage: message,
-        retryable: true
+        retryable: !isPermanentFailure
       };
     }
   }
@@ -1802,9 +1814,93 @@ var AITranslateText = ({
   ] });
 };
 
+// src/components/CustomizableAITranslateText.tsx
+var import_react6 = __toESM(require("react"));
+var import_jsx_runtime4 = require("react/jsx-runtime");
+var CustomizableAITranslateText = ({
+  text,
+  shouldTranslate,
+  showHighlight = false,
+  segmenter,
+  translatedIconProps
+}) => {
+  const context = (0, import_react6.useContext)(AITranslationContext);
+  const ait = context?.ait;
+  const segments = (0, import_react6.useMemo)(
+    () => segmenter ? segmenter(text) : [{ text, translate: shouldTranslate }],
+    [segmenter, text, shouldTranslate]
+  );
+  const [displayTexts, setDisplayTexts] = (0, import_react6.useState)(
+    () => segments.map((s) => s.text)
+  );
+  const segmentsKey = JSON.stringify(segments);
+  (0, import_react6.useEffect)(() => {
+    setDisplayTexts(segments.map((s) => s.text));
+  }, [segmentsKey]);
+  (0, import_react6.useEffect)(() => {
+    if (!ait || !shouldTranslate) {
+      setDisplayTexts(segments.map((s) => s.text));
+      return;
+    }
+    let cancelled = false;
+    Promise.all(
+      segments.map((s) => s.translate ? ait(s.text) : Promise.resolve(s.text))
+    ).then((resolved) => {
+      if (cancelled) return;
+      setDisplayTexts(resolved);
+    }).catch(() => {
+      if (cancelled) return;
+      setDisplayTexts(segments.map((s) => s.text));
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [ait, shouldTranslate, segmentsKey]);
+  const eventHandlerRef = (0, import_react6.useRef)(null);
+  (0, import_react6.useEffect)(() => {
+    if (!context) return;
+    if (!eventHandlerRef.current) {
+      eventHandlerRef.current = new EventHandler(context.tool);
+    }
+    const unsubscribe = eventHandlerRef.current.subscribeToRerenderEvent(
+      async (sourceTexts) => {
+        if (!shouldTranslate) return;
+        if (!sourceTexts || sourceTexts.length === 0) return;
+        const sourceSet = new Set(sourceTexts);
+        const targets = segments.map((s, i) => ({ s, i })).filter(({ s }) => s.translate && sourceSet.has(s.text));
+        if (targets.length === 0) return;
+        const fresh = await Promise.all(
+          targets.map(({ s }) => context.ait(s.text))
+        );
+        setDisplayTexts((prev) => {
+          const next = [...prev];
+          targets.forEach(({ i }, j) => {
+            const value = fresh[j];
+            if (value !== void 0) next[i] = value;
+          });
+          return next;
+        });
+      }
+    );
+    return () => unsubscribe();
+  }, [context, shouldTranslate, segmentsKey]);
+  const changedFlags = segments.map(
+    (s, i) => s.translate && shouldTranslate && (displayTexts[i] ?? s.text) !== s.text
+  );
+  const anyChanged = changedFlags.some(Boolean);
+  const showCellIcon = showHighlight && anyChanged;
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(import_jsx_runtime4.Fragment, { children: [
+    showCellIcon && /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(TranslatedIcon, { ...translatedIconProps }),
+    segments.map((seg, i) => {
+      const display = displayTexts[i] ?? seg.text;
+      return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_react6.default.Fragment, { children: display }, `${i}-${seg.text}`);
+    })
+  ] });
+};
+
 // src/utils/featureFlag.ts
 var import_web_sdk_mfe_utils = require("@procore/web-sdk-mfe-utils");
-var AI_TRANSLATION_FEATURE_FLAG_KEY = "pe_ai_translations_web_program_visible";
+var AI_TRANSLATION_FEATURE_FLAG_KEY = "ai-translation";
 var getAITranslationLDId = (domain) => {
   const { environment, zone } = (0, import_web_sdk_mfe_utils.getProcoreZone)(domain);
   if ((0, import_web_sdk_mfe_utils.isFederalZone)(zone)) {
@@ -1827,6 +1923,7 @@ var getAITranslationLDId = (domain) => {
   AITranslationProvider,
   AI_TRANSLATION_FEATURE_FLAG_KEY,
   BUTTON_TYPE,
+  CustomizableAITranslateText,
   buildAnalyticEvent,
   buildEventKey,
   buildObject,

package/dist/modern/index.mjs

@@ -1201,12 +1201,13 @@ var ChromeTranslator = class _ChromeTranslator {
       };
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
+      const isPermanentFailure = error instanceof DOMException && error.name === "NotSupportedError";
       return {
         translation: text,
         sourceLanguage: targetLanguage,
         success: false,
         errorMessage: message,
-        retryable: true
+        retryable: !isPermanentFailure
       };
     }
   }
@@ -1776,9 +1777,93 @@ var AITranslateText = ({
   ] });
 };
 
+// src/components/CustomizableAITranslateText.tsx
+import React4, { useContext as useContext4, useEffect as useEffect3, useMemo, useRef as useRef3, useState as useState3 } from "react";
+import { Fragment as Fragment2, jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
+var CustomizableAITranslateText = ({
+  text,
+  shouldTranslate,
+  showHighlight = false,
+  segmenter,
+  translatedIconProps
+}) => {
+  const context = useContext4(AITranslationContext);
+  const ait = context?.ait;
+  const segments = useMemo(
+    () => segmenter ? segmenter(text) : [{ text, translate: shouldTranslate }],
+    [segmenter, text, shouldTranslate]
+  );
+  const [displayTexts, setDisplayTexts] = useState3(
+    () => segments.map((s) => s.text)
+  );
+  const segmentsKey = JSON.stringify(segments);
+  useEffect3(() => {
+    setDisplayTexts(segments.map((s) => s.text));
+  }, [segmentsKey]);
+  useEffect3(() => {
+    if (!ait || !shouldTranslate) {
+      setDisplayTexts(segments.map((s) => s.text));
+      return;
+    }
+    let cancelled = false;
+    Promise.all(
+      segments.map((s) => s.translate ? ait(s.text) : Promise.resolve(s.text))
+    ).then((resolved) => {
+      if (cancelled) return;
+      setDisplayTexts(resolved);
+    }).catch(() => {
+      if (cancelled) return;
+      setDisplayTexts(segments.map((s) => s.text));
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [ait, shouldTranslate, segmentsKey]);
+  const eventHandlerRef = useRef3(null);
+  useEffect3(() => {
+    if (!context) return;
+    if (!eventHandlerRef.current) {
+      eventHandlerRef.current = new EventHandler(context.tool);
+    }
+    const unsubscribe = eventHandlerRef.current.subscribeToRerenderEvent(
+      async (sourceTexts) => {
+        if (!shouldTranslate) return;
+        if (!sourceTexts || sourceTexts.length === 0) return;
+        const sourceSet = new Set(sourceTexts);
+        const targets = segments.map((s, i) => ({ s, i })).filter(({ s }) => s.translate && sourceSet.has(s.text));
+        if (targets.length === 0) return;
+        const fresh = await Promise.all(
+          targets.map(({ s }) => context.ait(s.text))
+        );
+        setDisplayTexts((prev) => {
+          const next = [...prev];
+          targets.forEach(({ i }, j) => {
+            const value = fresh[j];
+            if (value !== void 0) next[i] = value;
+          });
+          return next;
+        });
+      }
+    );
+    return () => unsubscribe();
+  }, [context, shouldTranslate, segmentsKey]);
+  const changedFlags = segments.map(
+    (s, i) => s.translate && shouldTranslate && (displayTexts[i] ?? s.text) !== s.text
+  );
+  const anyChanged = changedFlags.some(Boolean);
+  const showCellIcon = showHighlight && anyChanged;
+  return /* @__PURE__ */ jsxs2(Fragment2, { children: [
+    showCellIcon && /* @__PURE__ */ jsx4(TranslatedIcon, { ...translatedIconProps }),
+    segments.map((seg, i) => {
+      const display = displayTexts[i] ?? seg.text;
+      return /* @__PURE__ */ jsx4(React4.Fragment, { children: display }, `${i}-${seg.text}`);
+    })
+  ] });
+};
+
 // src/utils/featureFlag.ts
 import { isFederalZone, getProcoreZone } from "@procore/web-sdk-mfe-utils";
-var AI_TRANSLATION_FEATURE_FLAG_KEY = "pe_ai_translations_web_program_visible";
+var AI_TRANSLATION_FEATURE_FLAG_KEY = "ai-translation";
 var getAITranslationLDId = (domain) => {
   const { environment, zone } = getProcoreZone(domain);
   if (isFederalZone(zone)) {
@@ -1800,6 +1885,7 @@ export {
   AITranslationProvider,
   AI_TRANSLATION_FEATURE_FLAG_KEY,
   BUTTON_TYPE,
+  CustomizableAITranslateText,
   buildAnalyticEvent,
   buildEventKey,
   buildObject,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@procore/ai-translations",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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",