@procore/ai-translations

@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.

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

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

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

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:

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:

yarn build
yarn test
yarn lint
yarn storybook
yarn cypress:run