@procore/ai-translations 0.1.0

package/dist/legacy/index.d.ts

@@ -0,0 +1,367 @@
+interface AITranslationContextValue {
+    ait: (text: string) => string;
+    isShowingTranslations: boolean;
+    toggleTranslations: () => void;
+    locale: string;
+    isTranslating: boolean;
+    renderVersion?: number;
+    initializeTranslators: (targetLanguages?: string[], sourceLanguages?: string[]) => Promise<void>;
+    isInitialized: boolean;
+}
+
+/**
+ * useAITranslation Hook
+ *
+ * Custom React hook to access the AI translation context and manage translation state.
+ * This hook provides access to translation functions, state, and utilities for
+ * managing translations in your React components.
+ *
+ * Key Features:
+ * - Access to `ait()` function for registering translatable strings
+ * - Toggle translations on/off
+ * - Check translation state (isShowingTranslations, isTranslating)
+ * - Initialize translators (required for first use)
+ * - Automatic re-rendering when translations update
+ *
+ * Usage:
+ * ```typescript
+ * function MyComponent() {
+ *   const { ait, isShowingTranslations, toggleTranslations } = useAITranslation();
+ *
+ *   return (
+ *     <div>
+ *       <h1>{ait("Welcome to our app")}</h1>
+ *       <button onClick={toggleTranslations}>
+ *         {isShowingTranslations ? 'Show Original' : 'Translate'}
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * Initialization Example:
+ * ```typescript
+ * function TranslateButton() {
+ *   const { initializeTranslators, isInitialized } = useAITranslation();
+ *
+ *   const handleClick = async () => {
+ *     if (!isInitialized) {
+ *       await initializeTranslators(['es', 'fr'], ['en']);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleClick}>Enable Translation</button>;
+ * }
+ * ```
+ *
+ * @throws {Error} If used outside of AITranslationProvider
+ * @returns {AITranslationContextValue} The translation context value with reactive render version
+ */
+declare function useAITranslation(): AITranslationContextValue;
+
+/**
+ * DataTable Translation Hook
+ *
+ * @module useDataTableAITranslation
+ * @description
+ * Specialized React hook for translating table data (AG Grid) with Chrome AI.
+ * Handles the complexity of translating dynamic table content, managing pagination,
+ * data changes, and field-level exclusions while maintaining optimal performance.
+ *
+ * ## Problem Solved
+ *
+ * Tables present unique translation challenges:
+ * - Data loads asynchronously (pagination, sorting, filtering)
+ * - New content appears without component remounts
+ * - Some fields shouldn't be translated (dates, IDs, technical fields)
+ * - Translation must not break table rendering or performance
+ * - Memory leaks from event listeners must be prevented
+ *
+ * This hook solves all these challenges with an intelligent translation system
+ * that automatically detects, translates, and applies translations to table data.
+ *
+ * ## Key Features
+ *
+ * 1. **Automatic String Registration**: All table cell text is registered for translation
+ * 2. **Field Exclusion**: Skip translation for datetime, ID, or custom fields
+ * 3. **Pagination Support**: Automatically translates new pages as they load
+ * 4. **Data Source Integration**: Listens to data events (loaded, changed)
+ * 5. **Progress Reporting**: Access global translation progress directly from the hook
+ * 6. **Memory Safe**: Prevents leaks with proper cleanup on unmount
+ * 7. **AG Grid Integration**: Direct integration with AG Grid's API
+ * 8. **Batch Translation**: Parallel translation for optimal performance
+ * 9. **Microtask Batching**: Catches late-loading rows with RAF timing
+ *
+ * ## Architecture
+ *
+ * The hook operates in phases:
+ *
+ * ### Registration Phase (Always Active)
+ * - As table renders, `ait()` is called on each cell value
+ * - Strings are registered in the string registry
+ * - Original values are preserved in `_originalLabel` properties
+ *
+ * ### Translation Phase (When Toggled ON)
+ * 1. Detect source language for each registered string
+ * 2. Filter out strings already in target language
+ * 3. Translate all strings in parallel batches
+ * 4. Update string registry with translations
+ * 5. Force table refresh to display translated content
+ *
+ * ### Update Phase (During Pagination/Data Changes)
+ * - New data triggers registration of new strings
+ * - If translations are active, automatically translates new strings
+ * - Applies translations and refreshes only affected cells
+ *
+ * ## Usage
+ *
+ * ### Basic Usage
+ * ```tsx
+ * import { useTableTranslation } from './ai-translations-package';
+ *
+ * function MyTable() {
+ *   const tableApi = useTableApi();
+ *   const fields = useFields();
+ *
+ *   const {
+ *     isShowingTranslations,
+ *     toggleTranslations,
+ *     isTranslating,
+ *     translationProgress
+ *   } = useTableTranslation({
+ *     tableApi,
+ *     fieldsIndex: fields,
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <Button onClick={toggleTranslations} loading={isTranslating}>
+ *         {isShowingTranslations ? 'Show Original' : 'Translate'}
+ *       </Button>
+ *       {translationProgress && (
+ *         <span>Progress: {translationProgress.progress}%</span>
+ *       )}
+ *       <Table api={tableApi} />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * ### With Field Exclusions
+ * ```tsx
+ * const { toggleTranslations } = useTableTranslation({
+ *   tableApi,
+ *   fieldsIndex: fields,
+ *   excludeFields: ['created_at', 'updated_at', 'id', 'code'],
+ *   shouldExcludeField: (field) => field.type === 'datetime' || field.technical
+ * });
+ * ```
+ *
+ * ### With Progress Reporting
+ * ```tsx
+ * const {
+ *   toggleTranslations,
+ *   translationProgress
+ * } = useTableTranslation({
+ *   tableApi,
+ *   fieldsIndex: fields,
+ * });
+ *
+ * // Display global progress (no need to call useAITranslation separately!)
+ * {translationProgress && (
+ *   <ProgressBar
+ *     progress={translationProgress.progress}
+ *     current={translationProgress.current}
+ *     total={translationProgress.total}
+ *   />
+ * )}
+ * ```
+ *
+ * ### With Data Source Integration
+ * ```tsx
+ * const dataSource = useDataSource();
+ *
+ * const { toggleTranslations } = useTableTranslation({
+ *   tableApi,
+ *   fieldsIndex: fields,
+ *   dataSource, // Automatically handles pagination and view changes
+ * });
+ * ```
+ *
+ * ### Manual Data Loading
+ * ```tsx
+ * const { applyTranslationsToNewData } = useTableTranslation({
+ *   tableApi,
+ *   fieldsIndex: fields,
+ * });
+ *
+ * // Call when new data loads
+ * const handleDataLoaded = async () => {
+ *   await applyTranslationsToNewData();
+ * };
+ * ```
+ *
+ * ## Field Exclusion
+ *
+ * By default, these fields are excluded from translation:
+ * - `created_at`, `updated_at`, `deleted_at`
+ * - `workflow_completion_date`, `workflow_step_due_date`
+ * - `received_date`, `date_required`, `private_at`
+ *
+ * ## Performance Considerations
+ *
+ * - **Parallel Translation**: All strings translate simultaneously
+ * - **Smart Caching**: Translations are cached in the string registry
+ * - **Incremental Updates**: Only new strings are translated on pagination
+ * - **Microtask Batching**: Multiple refreshes batched with RAF timing
+ * - **Memory Safe**: Cleanup prevents leaks from event listeners
+ *
+ * ## Integration with AG Grid
+ *
+ * The hook integrates directly with AG Grid's API:
+ * - `getRowData()`: Reads current row data for translation
+ * - `refreshCells()`: Forces cell updates after translation
+ * - `modelUpdated` event: Catches pagination/sorting/filtering
+ *
+ * It modifies row data in-place by:
+ * 1. Storing original values in `_originalLabel` properties
+ * 2. Updating `label` properties with translated text
+ * 3. Updating both `field.values` and `row[fieldId]` arrays
+ *
+ * ## Requirements
+ *
+ * - AG Grid table with `innerTableApi` property
+ * - Fields index with `byId` Map structure
+ * - Chrome browser with AI translation support
+ * - User gesture required for first translation
+ *
+ * @example
+ * // Complete example with all features
+ * const {
+ *   isShowingTranslations,
+ *   isTranslating,
+ *   toggleTranslations,
+ *   applyTranslationsToNewData,
+ *   translationProgress
+ * } = useTableTranslation({
+ *   tableApi,
+ *   fieldsIndex: fields,
+ *   excludeFields: ['created_at', 'id'],
+ *   shouldExcludeField: (field) => field.type === 'datetime',
+ *   dataSource: myDataSource,
+ * });
+ *
+ * // Display global translation progress directly from the hook
+ * {translationProgress && (
+ *   <div>
+ *     Progress: {translationProgress.progress}%
+ *     ({translationProgress.current}/{translationProgress.total})
+ *   </div>
+ * )}
+ */
+declare function useDataTableAITranslation(): void;
+
+/**
+ * AI Translation Provider
+ *
+ * @module AITranslationProvider
+ * @description
+ * Core provider component for Chrome AI-powered translations in React applications.
+ * Manages translation state, string registration, language detection, and translation execution.
+ *
+ * ## Architecture Overview
+ *
+ * This provider orchestrates several key components:
+ * - **String Registry**: Tracks all translatable strings and their states
+ * - **Chrome AI Client**: Interfaces with Chrome's built-in AI translation API
+ * - **Translation Service**: Handles translation requests with batching and caching
+ * - **Render Version Manager**: Forces component re-renders when translations update
+ *
+ * ## Key Features
+ *
+ * 1. **Automatic String Registration**: All strings passed through `ait()` are registered
+ * 2. **Language Detection**: Automatically detects source language using Chrome AI
+ * 3. **Batched Translation**: Efficiently translates multiple strings in parallel
+ * 4. **Toggle Mechanism**: Switch between original and translated content on-demand
+ * 5. **User Gesture Required**: Chrome AI initialization requires user interaction
+ * 6. **Pagination Support**: New content is automatically registered and translated
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * import { AITranslationProvider } from './ai-translations-package';
+ *
+ * function App() {
+ *   const handleProgress = (progress, current, total) => {
+ *     console.log(`Translation progress: ${progress}% (${current}/${total})`);
+ *   };
+ *
+ *   return (
+ *     <AITranslationProvider locale="es" onProgressChange={handleProgress}>
+ *       <YourApp />
+ *     </AITranslationProvider>
+ *   );
+ * }
+ * ```
+ *
+ * ## Translation Workflow
+ *
+ * 1. **Registration Phase**: Strings are registered via `ait(text)` calls
+ * 2. **Initialization**: User clicks toggle (user gesture required for Chrome AI)
+ * 3. **Detection Phase**: Source languages are detected for all registered strings
+ * 4. **Translation Phase**: Strings are translated to target locale
+ * 5. **Display Phase**: Translations are displayed, original text on toggle off
+ *
+ * ## Context Value
+ *
+ * The provider exposes:
+ * - `ait`: Translation function - wrap strings with this
+ * - `isShowingTranslations`: Current display state
+ * - `toggleTranslations`: Toggle between original and translated content
+ * - `isTranslating`: Whether translations are in progress
+ * - `initializeTranslators`: Manual initialization for specific languages
+ * - `isInitialized`: Whether Chrome AI translators are ready
+ * - `locale`: Current target language
+ * - `translationProgress`: Global translation progress (progress %, current count, total count)
+ *
+ * ## Requirements
+ *
+ * - Chrome browser with AI translation API support
+ * - User gesture required for initial translator creation
+ * - Network connection for AI model downloads (first use)
+ *
+ * @example
+ * // Using the ait function in a component
+ * const { ait } = useAITranslation();
+ * return <h1>{ait('Hello World')}</h1>;
+ *
+ * @example
+ * // Displaying global translation progress
+ * const { translationProgress, toggleTranslations } = useAITranslation();
+ *
+ * return (
+ *   <div>
+ *     <button onClick={toggleTranslations}>Translate</button>
+ *     {translationProgress && (
+ *       <div>
+ *         Translating: {translationProgress.current}/{translationProgress.total}
+ *         ({translationProgress.progress}%)
+ *       </div>
+ *     )}
+ *   </div>
+ * );
+ *
+ * @example
+ * // Manual initialization with specific languages
+ * const { initializeTranslators, toggleTranslations } = useAITranslation();
+ *
+ * <button onClick={async () => {
+ *   await initializeTranslators(['es', 'fr'], ['en', 'de']);
+ *   await toggleTranslations();
+ * }}>
+ *   Translate to Spanish/French
+ * </button>
+ */
+declare function AITranslationProvider(): void;
+
+export { AITranslationProvider, useAITranslation, useDataTableAITranslation };

package/dist/legacy/index.js

@@ -0,0 +1,57 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AITranslationProvider: () => AITranslationProvider,
+  useAITranslation: () => useAITranslation,
+  useDataTableAITranslation: () => useDataTableAITranslation
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/hooks/useAiTranslation.tsx
+function useAITranslation() {
+  return {
+    ait: () => "",
+    isShowingTranslations: false,
+    toggleTranslations: () => {
+    },
+    locale: "",
+    isTranslating: false,
+    renderVersion: void 0,
+    initializeTranslators: async () => {
+    },
+    isInitialized: false
+  };
+}
+
+// src/hooks/useDataTableAITranslation.tsx
+function useDataTableAITranslation() {
+}
+
+// src/Provider.tsx
+function AITranslationProvider() {
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AITranslationProvider,
+  useAITranslation,
+  useDataTableAITranslation
+});

package/dist/legacy/index.mjs

@@ -0,0 +1,28 @@
+// src/hooks/useAiTranslation.tsx
+function useAITranslation() {
+  return {
+    ait: () => "",
+    isShowingTranslations: false,
+    toggleTranslations: () => {
+    },
+    locale: "",
+    isTranslating: false,
+    renderVersion: void 0,
+    initializeTranslators: async () => {
+    },
+    isInitialized: false
+  };
+}
+
+// src/hooks/useDataTableAITranslation.tsx
+function useDataTableAITranslation() {
+}
+
+// src/Provider.tsx
+function AITranslationProvider() {
+}
+export {
+  AITranslationProvider,
+  useAITranslation,
+  useDataTableAITranslation
+};