@procore/ai-translations 0.6.0 → 0.6.1

package/README.internal.md

@@ -0,0 +1,257 @@
+# `@procore/ai-translations` Internal Guide
+
+Internal engineering reference for operating and evolving this package in Procore environments.
+
+Public consumer docs live in `README.md`.
+
+## Package Purpose
+
+`@procore/ai-translations` provides a shared translation runtime for MFEs:
+
+- context-based API (`AITranslationProvider`, `useAITranslation`)
+- component-level translation (`AITranslateText`)
+- strategy switching via remote config (`frontend_translations` / `backend_translations`)
+- queue, batching, cache persistence, and cross-component rerender events
+
+## Internal Architecture
+
+```mermaid
+flowchart LR
+consumerComponent[ConsumerComponent] --> aiTranslateText[AITranslateText]
+consumerComponent --> useHook[useAITranslation]
+aiTranslateText --> providerContext[AITranslationProviderContext]
+useHook --> providerContext
+providerContext --> aitFn["ait(text)"]
+providerContext --> configHook[useConfig]
+aitFn --> registry[TranslationRegistry]
+aitFn --> queue[queueManager]
+queue --> manager[TranslationManager]
+manager --> translatorFactory[TranslatorFactory]
+translatorFactory --> frontendClient[FrontendChromeClient]
+translatorFactory --> backendClient[BackendApiClient]
+manager --> storage[IndexedDBStorage]
+manager --> events[EventHandler]
+events --> aiTranslateText
+```
+
+Key files:
+
+- `src/Provider.tsx`: context lifecycle, progress subscriptions, config update wiring
+- `src/utils/core.ts`: `aitFunction` orchestration and registration flow
+- `src/utils/translationManager.ts`: queue drain + batch translation + persistence
+- `src/utils/translationRegistry.ts`: memory/DB-backed translation registry
+- `src/utils/eventHandler.ts`: tool-scoped publish/subscribe events
+- `src/configuration/configurationClient.ts`: config API client
+- `src/translators/*`: frontend and backend translation clients
+
+## Detailed Runtime Flow
+
+This package is intentionally asynchronous and eventual-consistency based for UI safety and throughput:
+
+1. `AITranslateText` calls `context.ait(text)`.
+2. `aitFunction` (`src/utils/core.ts`) checks:
+   - empty input
+   - non-retryable text set
+   - in-memory/IndexedDB registry hit
+3. On cache miss:
+   - creates entry ID (`Storage.generateId`)
+   - deduplicates with `enqueuedItems`
+   - appends to strategy-specific global queue (`queueManager`)
+   - schedules `TranslationManager.translate()` on microtask
+4. `TranslationManager`:
+   - guards against concurrent runs via global in-progress flags
+   - drains queue in batches based on active `ToolConfig`
+   - delegates translation to `Translator` (frontend/backend strategy)
+   - persists translated entries (`Storage.saveTranslation`)
+   - emits translation-complete and progress events
+5. Provider listens for complete events, repopulates registry, and triggers rerender event.
+6. `AITranslateText` receives rerender event and re-calls `ait(text)` to display translated output.
+
+```mermaid
+sequenceDiagram
+participant ui as UIComponent
+participant textComp as AITranslateText
+participant provider as AITranslationProvider
+participant core as aitFunction
+participant queue as queueManager
+participant mgr as TranslationManager
+participant tr as Translator
+participant db as StorageIndexedDB
+participant evt as EventHandler
+
+ui->>textComp: render text
+textComp->>provider: get context
+textComp->>core: ait(text)
+core->>db: lookup by key
+alt cache hit
+  core-->>textComp: translated text
+else cache miss
+  core->>queue: enqueue entry
+  core->>mgr: schedule translate()
+  core-->>textComp: original text
+  mgr->>tr: processTranslations(batch)
+  tr-->>mgr: translation results
+  mgr->>db: persist results
+  mgr->>evt: publish translation complete
+  evt-->>textComp: rerender event
+  textComp->>core: ait(text) again
+  core-->>textComp: translated text
+end
+```
+
+## API Surface (Current Exports)
+
+From `src/index.ts`:
+
+- `AITranslationProvider`
+- `AITranslateText`
+- hooks from `src/hooks`
+- `AITranslateTextProps`
+- `TranslatedIconProps`
+- `getAITranslationLDId`
+- `AI_TRANSLATION_FEATURE_FLAG_KEY`
+
+Not exported from root:
+
+- `AITranslate` component (`src/components/AITranslate.tsx`) is internal-only unless imported by path
+- `TranslatedIcon` component itself is not root-exported
+
+## Runtime Configuration
+
+Config fetch:
+
+- Base URL: `${window.location.origin}/rest/v1.0/`
+- Endpoint path: `configuration?toolName=...&companyId=...&projectId=...&userId=...`
+- Polling interval: every 30 minutes (`useConfig`)
+
+Tool config shape:
+
+```ts
+type ToolConfig = {
+  strategy: 'frontend_translations' | 'backend_translations';
+  supportedLocales: string[];
+  translationBatchSize: number;
+  renderingBatchSize: number;
+  apiTimeout: number;
+  apiVersion: string;
+};
+```
+
+Behavioral notes:
+
+- The provider applies remote tool config and locale to the active translator config.
+- Strategy changes may invalidate in-memory queue/registry assumptions between cycles.
+- Invalid ID values in config fetch options throw validation errors in `ConfigurationClient`.
+
+## Data Model and Storage Semantics
+
+- Registry keying uses hashed tuple: `sourceText + targetLanguage + tool`.
+- Queue entries are tracked per strategy (`frontend_translations` / `backend_translations`).
+- Enqueued dedupe key: `${id}:${strategy}`.
+- Persistent storage uses IndexedDB via `src/utils/storage.ts`.
+- Cache invalidation behavior:
+  - frontend-translated entries are removed if runtime switches to backend strategy
+  - tool/strategy-level deletes clear memory indexes and queue markers
+
+## Patterns Used
+
+- **Provider + Context pattern**: `AITranslationProvider` exposes translation API and state.
+- **Facade pattern**: `aitFunction` hides queueing, dedupe, cache, persistence, and scheduling details behind `ait(text)`.
+- **Factory pattern**: `Translator` chooses strategy-specific client from config.
+- **Adapter pattern**: frontend and backend clients implement the shared translator client contract.
+- **Pub/Sub pattern**: `EventHandler` dispatches translation-complete, rerender, progress, and model-download events.
+- **Repository/Registry pattern**: `TranslationRegistry` provides unified access over in-memory + IndexedDB states.
+- **Batch processing pattern**: `TranslationManager` drains queue incrementally and emits progress snapshots.
+- **Idempotent enqueue pattern**: enqueued set prevents duplicate work for the same text/strategy.
+
+## Translation Strategies
+
+### Frontend strategy
+
+- Uses Chromium AI APIs through `ChromeTranslator`
+- Supported browser list is currently in `src/translators/frontend_translators/chrome/client.ts`
+- Intended for Chrome-family browsers
+- Individual source texts are normalized to single-text requests before translation (`normalizeFrontendRequests`)
+
+### Backend strategy
+
+- Uses `@procore/core-http` client
+- Translation endpoint: `POST /translations` on configured API base URL
+- Returns grouped translation records with retry metadata normalization
+- Failed network/API responses are transformed into retryable structured translation failures
+
+## Feature Flag Utilities
+
+`src/utils/featureFlag.ts`:
+
+- storage key: `AI_TRANSLATION_FEATURE_FLAG_KEY` (`ai-translation`)
+- `getAITranslationLDId(domain)` maps by zone/environment and federal partition behavior
+
+## Concurrency and Progress Model
+
+Concurrency control:
+
+- `globalThis._FRONTEND_AI_TRANSLATION_IN_PROGRESS_`
+- `globalThis._BACKEND_AI_TRANSLATION_IN_PROGRESS_`
+
+Progress behavior:
+
+- progress starts from queue size snapshot at translation start
+- if queue grows during a run, total is expanded so percent stays monotonic and <= 100
+- completion publishes reset event (`total = 0`) to clear UI progress bars
+
+```mermaid
+flowchart TD
+startRun[StartTranslationRun] --> strategyCheck[CheckStrategyFlag]
+strategyCheck --> lockFlag[SetInProgressFlag]
+lockFlag --> initTotal[InitializeProgressTotal]
+initTotal --> processBatch[ProcessBatch]
+processBatch --> updateProgress[UpdateProgress]
+updateProgress --> hasMore{QueueHasMore}
+hasMore -->|yes| processBatch
+hasMore -->|no| resetProgress[ResetProgressToZero]
+resetProgress --> releaseFlag[ClearInProgressFlag]
+```
+
+## Local Development
+
+From package root:
+
+```bash
+yarn build
+yarn test
+yarn test:integration
+yarn lint
+yarn storybook
+yarn cypress:run
+```
+
+Helpful variants:
+
+- `yarn cypress:run:integration`
+- `yarn cypress:run:component`
+- `yarn cypress:run:headed`
+
+## CI and Quality Gates
+
+- CircleCI job coverage includes package tests and Cypress execution
+- Sonar config exists at `sonar-project.properties`
+- `prepublishOnly` runs `yarn build`
+
+## Internal Troubleshooting
+
+- If translations do not appear, verify:
+  - provider wrapper exists at app root
+  - config endpoint returns expected `ToolConfig`
+  - chosen strategy is supported in current browser/runtime
+- If progress is stuck:
+  - inspect queue/manager integration tests in `src/__integration__`
+  - verify translation completion events are being published and subscribed
+- If highlight/rerender behavior is inconsistent:
+  - validate tool names are consistent across provider and subscribers
+  - check `EventHandler` topic scoping and rerender subscription lifecycle
+- If translation requests do not leave queue:
+  - verify in-progress flags were reset (no stale global lock)
+  - verify strategy-specific queue contains entries matching active strategy
+- If stale translations appear after strategy switch:
+  - confirm registry/storage cleanup path for frontend-to-backend switch is executed

package/README.md

@@ -1 +1,158 @@
-### AI Translation Package
+# `@procore/ai-translations`
+
+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
+
+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
+
+For Procore-specific operational details, see `README.internal.md`.
+
+## Installation
+
+```bash
+yarn add @procore/ai-translations
+```
+
+Peer dependencies:
+
+- `react` `>= 16 < 19`
+- `react-dom` `>= 16 < 19`
+- `@procore/web-sdk-mfe-utils` `> 1.0.0 < 2`
+
+## Quick Start
+
+```tsx
+import React from 'react';
+import {
+  AITranslationProvider,
+  AITranslateText,
+} from '@procore/ai-translations';
+
+export function AppRoot() {
+  return (
+    <AITranslationProvider
+      tool="timecard"
+      companyId={1}
+      projectId={10}
+      userId={42}
+      locale="es"
+      enableAIT={true}
+      companyLocale="de-DE"
+      projectLocale="fr-CA"
+    >
+      <AITranslateText text="Hello world" shouldTranslate={true} />
+    </AITranslationProvider>
+  );
+}
+```
+
+## Public API
+
+### `AITranslationProvider`
+
+Required props:
+
+- `locale: string` - target locale (BCP-47, for example `es`, `fr`, `de`)
+- `tool: string` - tool/MFE identifier used to scope translation events
+- `companyId: number`
+- `projectId: number`
+- `userId: number`
+
+Optional props:
+
+- `enableAIT?: boolean` (default `true`) - when `false`, returns source text without translation
+- `companyLocale?: string` - company-level locale from environment metadata (e.g. `"de-DE"`); passed through to context for downstream consumers such as Amplitude
+- `projectLocale?: string` - project-level locale from environment metadata (e.g. `"fr-CA"`); passed through to context for downstream consumers such as Amplitude
+
+### `AITranslateText`
+
+Props:
+
+- `text: string`
+- `shouldTranslate: boolean`
+- `showHighlight?: boolean` (default `false`)
+- `translatedIconProps?: TranslatedIconProps`
+
+### `useAITranslation()`
+
+Returns:
+
+- `ait(text: string): Promise<string>` - translates text or returns cached value
+- `locale: string`
+- `companyLocale: string | undefined` - company-level locale from environment metadata
+- `projectLocale: string | undefined` - project-level locale from environment metadata
+- `tool: string`
+- `translationProgress: { progress: number; current: number; total: number } | null`
+- `modelDownloadProgress: ModelDownloadProgress | null`
+- `renderVersion: number | undefined`
+
+### Feature flag helpers
+
+- `AI_TRANSLATION_FEATURE_FLAG_KEY`
+- `getAITranslationLDId(domain: string)`
+
+## How It Works
+
+```mermaid
+flowchart LR
+consumerApp[ConsumerApp] --> provider[AITranslationProvider]
+provider --> aitCall["ait(text)"]
+aitCall --> registryCheck[TranslationRegistryCheck]
+registryCheck --> returnCached[ReturnCachedText]
+registryCheck --> queueText[QueueText]
+queueText --> manager[TranslationManager]
+manager --> strategy[TranslatorStrategy]
+strategy --> frontendClient[ChromeFrontendClient]
+strategy --> backendClient[BackendApiClient]
+frontendClient --> 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.
+
+## Configuration
+
+The provider uses `useConfig` (React Query) to fetch translation config and refetch every 30 minutes.
+
+Expected remote config shape:
+
+```ts
+type ToolConfig = {
+  strategy: 'frontend_translations' | 'backend_translations';
+  supportedLocales: string[];
+  translationBatchSize: number;
+  renderingBatchSize: number;
+  apiTimeout: number;
+  apiVersion: string;
+};
+```
+
+## Operational Notes
+
+- `AITranslateText` and `useAITranslation` must be used inside `AITranslationProvider`.
+- Frontend strategy depends on Chrome-family AI support; behavior differs by browser support.
+- Backend/config endpoints are resolved from `window.location.origin` under `/rest/`.
+- Translation cache uses IndexedDB; some restricted browser environments may limit persistence.
+
+## Development
+
+From `packages/ai-translations`:
+
+```bash
+yarn build
+yarn test
+yarn lint
+yarn storybook
+yarn cypress:run
+```

package/dist/legacy/index.d.mts

@@ -2,6 +2,35 @@ import * as _tanstack_react_query from '@tanstack/react-query';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
+/** Shape of an analytic event passed to the MFE's `onTrackAnalyticsEvent` callback. */
+interface AnalyticEvent {
+    key: string;
+    properties: Record<string, unknown>;
+}
+/** Function provided by the MFE that sends the event to the analytics destination. */
+type AIAnalyticsTracker = (event: AnalyticEvent) => void;
+/** Feature scope: `'project'` for project-level tools, `'company'` for company-level tools. */
+type Scope = 'project' | 'company';
+/**
+ * Parts needed to build an event key following the pattern:
+ * `ux.web.feature.{scope}.{tool}.{object}.{action}`
+ */
+interface EventKeyParts {
+    scope: Scope;
+    tool: string;
+    object: string;
+    action: string;
+}
+/** Standard properties included in every AI analytics event. */
+interface AIAnalyticsEventProperties {
+    user_locale: string;
+    project_locale?: string;
+    company_locale?: string;
+    tool: string;
+    page: string;
+    [key: string]: unknown;
+}
+
 interface TranslationProgress {
     /**
      * Progress percentage (0-100)
@@ -39,12 +68,22 @@ interface ModelDownloadProgress {
 interface AITranslationContextValue {
     ait: (text: string) => Promise<string>;
     locale: string;
+    /** Company-level locale from environment metadata (e.g. `"de-DE"`). */
+    companyLocale?: string;
+    /** Project-level locale from environment metadata (e.g. `"fr-CA"`). */
+    projectLocale?: string;
     renderVersion?: number;
     /** Batch-translation progress; `null` while the queue is idle. */
     translationProgress: TranslationProgress | null;
     /** Chrome AI model download progress; `null` until a download begins. */
     modelDownloadProgress: ModelDownloadProgress | null;
     tool: string;
+    /** Called by `useAIAnalytics` with a fully assembled event. The MFE is responsible for sending it. */
+    onTrackAnalyticsEvent?: AIAnalyticsTracker;
+    /** Page context used to build the event key object segment (e.g. `'view'`, `'list_column_description'`). */
+    page?: string;
+    /** Feature scope: `'project'` or `'company'`. */
+    scope?: Scope;
 }
 
 interface ConfigurationResponse {
@@ -117,6 +156,59 @@ declare function useConfig(toolName: string, options?: UseConfigOptions): _tanst
  */
 declare function useAITranslation(): AITranslationContextValue;
 
+/** Button type identifiers for the event key `object` segment. */
+declare const BUTTON_TYPE: {
+    readonly TRANSLATE: "translate";
+    readonly HIGHLIGHT: "highlight";
+};
+type ButtonType = (typeof BUTTON_TYPE)[keyof typeof BUTTON_TYPE];
+/** Action identifiers for the event key `action` segment. */
+declare const ACTION: {
+    readonly CLICKED: "clicked";
+};
+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;
+/**
+ * Builds a fully-qualified event key:
+ * `ux.web.feature.{scope}.{tool}.{object}.{action}`
+ */
+declare function buildEventKey(parts: EventKeyParts): string;
+interface BuildAnalyticEventParams {
+    scope: Scope;
+    tool: string;
+    /** Prefix for the object segment, matches the Provider `page` prop (e.g. `'view'`). */
+    pageContext: string;
+    buttonType: ButtonType;
+    baseProperties: AIAnalyticsEventProperties;
+    /** Defaults to `'clicked'` if omitted. */
+    action?: Action;
+    additionalProperties?: Record<string, unknown>;
+}
+/** Assembles a complete `AnalyticEvent` (key + merged properties) ready for `onTrackAnalyticsEvent`. */
+declare function buildAnalyticEvent(params: BuildAnalyticEventParams): AnalyticEvent;
+
+interface UseAIAnalyticsReturn {
+    /** Fires `ux.web.feature.{scope}.{tool}.{page}_translate_button.clicked`. */
+    trackTranslateButtonClicked: (additionalProperties?: Record<string, unknown>) => void;
+    /** Fires `ux.web.feature.{scope}.{tool}.{page}_highlight_button.clicked`. */
+    trackHighlightButtonClicked: (additionalProperties?: Record<string, unknown>) => void;
+    /** Generic tracking for custom button types or actions. */
+    trackCustomEvent: (buttonType: ButtonType | string, action?: Action | string, additionalProperties?: Record<string, unknown>) => void;
+    /** `true` when `onTrackAnalyticsEvent` was provided to `AITranslationProvider`. */
+    isTrackingEnabled: boolean;
+}
+/**
+ * Returns analytics tracking helpers pre-wired to the Provider context.
+ * All functions no-op if `onTrackAnalyticsEvent` was not supplied.
+ *
+ * @throws if called outside of an `AITranslationProvider`.
+ */
+declare function useAIAnalytics(): UseAIAnalyticsReturn;
+
 interface AITranslationProviderProps {
     children: ReactNode;
     locale: string;
@@ -125,6 +217,16 @@ interface AITranslationProviderProps {
     userId: number;
     projectId: number;
     enableAIT?: boolean;
+    /** Company-level locale from environment metadata (e.g. `"de-DE"`). Passed through to context for downstream consumers such as Amplitude. */
+    companyLocale?: string;
+    /** Project-level locale from environment metadata (e.g. `"fr-CA"`). Passed through to context for downstream consumers such as Amplitude. */
+    projectLocale?: string;
+    /** Called by `useAIAnalytics` with a pre-assembled event. The MFE sends it to the analytics API. */
+    onTrackAnalyticsEvent?: AIAnalyticsTracker;
+    /** Page context for the event key object segment (e.g. `'view'`, `'list_column_description'`). */
+    page?: string;
+    /** Feature scope: `'project'` or `'company'`. */
+    scope?: Scope;
 }
 declare function AITranslationProvider(props: AITranslationProviderProps): react_jsx_runtime.JSX.Element;
 
@@ -177,4 +279,4 @@ declare global {
     var _BACKEND_AI_TRANSLATION_IN_PROGRESS_: boolean;
 }
 
-export { AITranslateText, type AITranslateTextProps, AITranslationProvider, AI_TRANSLATION_FEATURE_FLAG_KEY, type TranslatedIconProps, type UseConfigOptions, getAITranslationLDId, 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, type EventKeyParts, type Scope, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, useAIAnalytics, useAITranslation, useConfig };

package/dist/legacy/index.d.ts

@@ -2,6 +2,35 @@ import * as _tanstack_react_query from '@tanstack/react-query';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
+/** Shape of an analytic event passed to the MFE's `onTrackAnalyticsEvent` callback. */
+interface AnalyticEvent {
+    key: string;
+    properties: Record<string, unknown>;
+}
+/** Function provided by the MFE that sends the event to the analytics destination. */
+type AIAnalyticsTracker = (event: AnalyticEvent) => void;
+/** Feature scope: `'project'` for project-level tools, `'company'` for company-level tools. */
+type Scope = 'project' | 'company';
+/**
+ * Parts needed to build an event key following the pattern:
+ * `ux.web.feature.{scope}.{tool}.{object}.{action}`
+ */
+interface EventKeyParts {
+    scope: Scope;
+    tool: string;
+    object: string;
+    action: string;
+}
+/** Standard properties included in every AI analytics event. */
+interface AIAnalyticsEventProperties {
+    user_locale: string;
+    project_locale?: string;
+    company_locale?: string;
+    tool: string;
+    page: string;
+    [key: string]: unknown;
+}
+
 interface TranslationProgress {
     /**
      * Progress percentage (0-100)
@@ -39,12 +68,22 @@ interface ModelDownloadProgress {
 interface AITranslationContextValue {
     ait: (text: string) => Promise<string>;
     locale: string;
+    /** Company-level locale from environment metadata (e.g. `"de-DE"`). */
+    companyLocale?: string;
+    /** Project-level locale from environment metadata (e.g. `"fr-CA"`). */
+    projectLocale?: string;
     renderVersion?: number;
     /** Batch-translation progress; `null` while the queue is idle. */
     translationProgress: TranslationProgress | null;
     /** Chrome AI model download progress; `null` until a download begins. */
     modelDownloadProgress: ModelDownloadProgress | null;
     tool: string;
+    /** Called by `useAIAnalytics` with a fully assembled event. The MFE is responsible for sending it. */
+    onTrackAnalyticsEvent?: AIAnalyticsTracker;
+    /** Page context used to build the event key object segment (e.g. `'view'`, `'list_column_description'`). */
+    page?: string;
+    /** Feature scope: `'project'` or `'company'`. */
+    scope?: Scope;
 }
 
 interface ConfigurationResponse {
@@ -117,6 +156,59 @@ declare function useConfig(toolName: string, options?: UseConfigOptions): _tanst
  */
 declare function useAITranslation(): AITranslationContextValue;
 
+/** Button type identifiers for the event key `object` segment. */
+declare const BUTTON_TYPE: {
+    readonly TRANSLATE: "translate";
+    readonly HIGHLIGHT: "highlight";
+};
+type ButtonType = (typeof BUTTON_TYPE)[keyof typeof BUTTON_TYPE];
+/** Action identifiers for the event key `action` segment. */
+declare const ACTION: {
+    readonly CLICKED: "clicked";
+};
+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;
+/**
+ * Builds a fully-qualified event key:
+ * `ux.web.feature.{scope}.{tool}.{object}.{action}`
+ */
+declare function buildEventKey(parts: EventKeyParts): string;
+interface BuildAnalyticEventParams {
+    scope: Scope;
+    tool: string;
+    /** Prefix for the object segment, matches the Provider `page` prop (e.g. `'view'`). */
+    pageContext: string;
+    buttonType: ButtonType;
+    baseProperties: AIAnalyticsEventProperties;
+    /** Defaults to `'clicked'` if omitted. */
+    action?: Action;
+    additionalProperties?: Record<string, unknown>;
+}
+/** Assembles a complete `AnalyticEvent` (key + merged properties) ready for `onTrackAnalyticsEvent`. */
+declare function buildAnalyticEvent(params: BuildAnalyticEventParams): AnalyticEvent;
+
+interface UseAIAnalyticsReturn {
+    /** Fires `ux.web.feature.{scope}.{tool}.{page}_translate_button.clicked`. */
+    trackTranslateButtonClicked: (additionalProperties?: Record<string, unknown>) => void;
+    /** Fires `ux.web.feature.{scope}.{tool}.{page}_highlight_button.clicked`. */
+    trackHighlightButtonClicked: (additionalProperties?: Record<string, unknown>) => void;
+    /** Generic tracking for custom button types or actions. */
+    trackCustomEvent: (buttonType: ButtonType | string, action?: Action | string, additionalProperties?: Record<string, unknown>) => void;
+    /** `true` when `onTrackAnalyticsEvent` was provided to `AITranslationProvider`. */
+    isTrackingEnabled: boolean;
+}
+/**
+ * Returns analytics tracking helpers pre-wired to the Provider context.
+ * All functions no-op if `onTrackAnalyticsEvent` was not supplied.
+ *
+ * @throws if called outside of an `AITranslationProvider`.
+ */
+declare function useAIAnalytics(): UseAIAnalyticsReturn;
+
 interface AITranslationProviderProps {
     children: ReactNode;
     locale: string;
@@ -125,6 +217,16 @@ interface AITranslationProviderProps {
     userId: number;
     projectId: number;
     enableAIT?: boolean;
+    /** Company-level locale from environment metadata (e.g. `"de-DE"`). Passed through to context for downstream consumers such as Amplitude. */
+    companyLocale?: string;
+    /** Project-level locale from environment metadata (e.g. `"fr-CA"`). Passed through to context for downstream consumers such as Amplitude. */
+    projectLocale?: string;
+    /** Called by `useAIAnalytics` with a pre-assembled event. The MFE sends it to the analytics API. */
+    onTrackAnalyticsEvent?: AIAnalyticsTracker;
+    /** Page context for the event key object segment (e.g. `'view'`, `'list_column_description'`). */
+    page?: string;
+    /** Feature scope: `'project'` or `'company'`. */
+    scope?: Scope;
 }
 declare function AITranslationProvider(props: AITranslationProviderProps): react_jsx_runtime.JSX.Element;
 
@@ -177,4 +279,4 @@ declare global {
     var _BACKEND_AI_TRANSLATION_IN_PROGRESS_: boolean;
 }
 
-export { AITranslateText, type AITranslateTextProps, AITranslationProvider, AI_TRANSLATION_FEATURE_FLAG_KEY, type TranslatedIconProps, type UseConfigOptions, getAITranslationLDId, 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, type EventKeyParts, type Scope, type TranslatedIconProps, type UseAIAnalyticsReturn, type UseConfigOptions, buildAnalyticEvent, buildEventKey, buildObject, getAITranslationLDId, useAIAnalytics, useAITranslation, useConfig };