@willwade/aac-processors 0.0.13 → 0.0.14

package/dist/processors/gridsetProcessor.js

@@ -10,6 +10,7 @@ const adm_zip_1 = __importDefault(require("adm-zip"));
 const fs_1 = __importDefault(require("fs"));
 const fast_xml_parser_1 = require("fast-xml-parser");
 const resolver_1 = require("./gridset/resolver");
+const translationProcessor_1 = require("../utilities/translation/translationProcessor");
 const password_1 = require("./gridset/password");
 const crypto_1 = __importDefault(require("crypto"));
 const zlib_1 = __importDefault(require("zlib"));
@@ -19,7 +20,8 @@ const pluginTypes_1 = require("./gridset/pluginTypes");
 const commands_1 = require("./gridset/commands");
 const symbols_1 = require("./gridset/symbols");
 const resolver_2 = require("./gridset/resolver");
-const idGenerator_1 = require("../optional/analytics/utils/idGenerator");
+const idGenerator_1 = require("../utilities/analytics/utils/idGenerator");
+const symbolAlignment_1 = require("./gridset/symbolAlignment");
 class GridsetProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options) {
         super(options);
@@ -1084,17 +1086,51 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                 if (tPage)
                     page.name = tPage;
             }
-            // Translate button labels and messages
+            // Translate button labels and messages, preserving symbol positions
             page.buttons.forEach((button) => {
+                // Translate label
                 if (button.label && translations.has(button.label)) {
                     const tLabel = translations.get(button.label);
                     if (tLabel)
                         button.label = tLabel;
                 }
+                // Translate message with symbol preservation
                 if (button.message && translations.has(button.message)) {
-                    const tMsg = translations.get(button.message);
-                    if (tMsg)
-                        button.message = tMsg;
+                    const originalMessage = button.message;
+                    const translatedText = translations.get(originalMessage);
+                    if (translatedText) {
+                        // Extract symbols from the button (from richText or image fields)
+                        const symbols = (0, symbolAlignment_1.extractSymbolsFromButton)(button);
+                        if (symbols && symbols.length > 0) {
+                            // Use symbol-aware translation to preserve symbol positions
+                            const result = (0, symbolAlignment_1.translateWithSymbols)(originalMessage, translatedText, symbols);
+                            // Update the message
+                            button.message = result.text;
+                            // Update the rich text structure if it exists
+                            if (button.semanticAction?.richText) {
+                                button.semanticAction.richText.text = result.text;
+                                button.semanticAction.richText.symbols = result.richTextSymbols;
+                            }
+                            else if (result.richTextSymbols.length > 0) {
+                                // Create rich text structure if it doesn't exist but we have symbols
+                                if (!button.semanticAction) {
+                                    button.semanticAction = {
+                                        category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                        intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+                                        text: result.text,
+                                    };
+                                }
+                                button.semanticAction.richText = {
+                                    text: result.text,
+                                    symbols: result.richTextSymbols,
+                                };
+                            }
+                        }
+                        else {
+                            // No symbols to preserve, simple translation
+                            button.message = translatedText;
+                        }
+                    }
                 }
             });
         });
@@ -1102,6 +1138,86 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         this.saveFromTree(tree, outputPath);
         return fs_1.default.readFileSync(outputPath);
     }
+    /**
+     * Extract symbol information from a gridset for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to gridset file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Collect all buttons from all pages
+        const allButtons = [];
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                // Add page context to each button
+                button.pageId = page.id;
+                button.pageName = page.name || page.id;
+                allButtons.push(button);
+            });
+        });
+        // Use shared utility to extract buttons with translation context
+        return (0, translationProcessor_1.extractAllButtonsForTranslation)(allButtons, (button) => ({
+            pageId: button.pageId,
+            pageName: button.pageName,
+        }));
+    }
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to gridset file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated gridset
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated gridset
+     */
+    processLLMTranslations(filePathOrBuffer, llmTranslations, outputPath, options) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Validate translations using shared utility
+        const buttonIds = Object.values(tree.pages).flatMap((page) => page.buttons.map((b) => b.id));
+        (0, translationProcessor_1.validateTranslationResults)(llmTranslations, buttonIds, options);
+        // Create a map for quick lookup
+        const translationMap = new Map(llmTranslations.map((t) => [t.buttonId, t]));
+        // Apply translations
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                const translation = translationMap.get(button.id);
+                if (!translation)
+                    return;
+                // Apply label translation
+                if (translation.translatedLabel) {
+                    button.label = translation.translatedLabel;
+                }
+                // Apply message translation
+                if (translation.translatedMessage) {
+                    button.message = translation.translatedMessage;
+                    // Update rich text if symbols provided
+                    if (translation.symbols && translation.symbols.length > 0) {
+                        if (!button.semanticAction) {
+                            button.semanticAction = {
+                                category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+                                text: translation.translatedMessage,
+                            };
+                        }
+                        button.semanticAction.richText = {
+                            text: translation.translatedMessage,
+                            symbols: translation.symbols,
+                        };
+                    }
+                }
+            });
+        });
+        // Save and return
+        this.saveFromTree(tree, outputPath);
+        return fs_1.default.readFileSync(outputPath);
+    }
     saveFromTree(tree, outputPath) {
         const zip = new adm_zip_1.default();
         if (Object.keys(tree.pages).length === 0) {

package/dist/processors/obfProcessor.d.ts

@@ -1,6 +1,7 @@
 import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString, SourceString } from '../core/baseProcessor';
 import { AACTree } from '../core/treeStructure';
 import { ValidationResult } from '../validation/validationTypes';
+import { type ButtonForTranslation, type LLMLTranslationResult } from '../utilities/translation/translationProcessor';
 declare class ObfProcessor extends BaseProcessor {
     constructor(options?: ProcessorOptions);
     private processBoard;
@@ -26,5 +27,30 @@ declare class ObfProcessor extends BaseProcessor {
      * @returns Promise with validation result
      */
     validate(filePath: string): Promise<ValidationResult>;
+    /**
+     * Extract symbol information from an OBF/OBZ file for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to OBF/OBZ file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer: string | Buffer): ButtonForTranslation[];
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to OBF/OBZ file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated OBF/OBZ file
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated OBF/OBZ file
+     */
+    processLLMTranslations(filePathOrBuffer: string | Buffer, llmTranslations: LLMLTranslationResult[], outputPath: string, options?: {
+        allowPartial?: boolean;
+    }): Buffer;
 }
 export { ObfProcessor };

package/dist/processors/obfProcessor.js

@@ -6,10 +6,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObfProcessor = void 0;
 const baseProcessor_1 = require("../core/baseProcessor");
 const treeStructure_1 = require("../core/treeStructure");
-const idGenerator_1 = require("../optional/analytics/utils/idGenerator");
+const idGenerator_1 = require("../utilities/analytics/utils/idGenerator");
 const adm_zip_1 = __importDefault(require("adm-zip"));
 const fs_1 = __importDefault(require("fs"));
 const obfValidator_1 = require("../validation/obfValidator");
+const translationProcessor_1 = require("../utilities/translation/translationProcessor");
 const OBF_FORMAT_VERSION = 'open-board-0.1';
 /**
  * Map OBF hidden value to AAC standard visibility
@@ -403,5 +404,85 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
     async validate(filePath) {
         return obfValidator_1.ObfValidator.validateFile(filePath);
     }
+    /**
+     * Extract symbol information from an OBF/OBZ file for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to OBF/OBZ file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Collect all buttons from all pages
+        const allButtons = [];
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                // Add page context to each button
+                button.pageId = page.id;
+                button.pageName = page.name || page.id;
+                allButtons.push(button);
+            });
+        });
+        // Use shared utility to extract buttons with translation context
+        return (0, translationProcessor_1.extractAllButtonsForTranslation)(allButtons, (button) => ({
+            pageId: button.pageId,
+            pageName: button.pageName,
+        }));
+    }
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to OBF/OBZ file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated OBF/OBZ file
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated OBF/OBZ file
+     */
+    processLLMTranslations(filePathOrBuffer, llmTranslations, outputPath, options) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Validate translations using shared utility
+        const buttonIds = Object.values(tree.pages).flatMap((page) => page.buttons.map((b) => b.id));
+        (0, translationProcessor_1.validateTranslationResults)(llmTranslations, buttonIds, options);
+        // Create a map for quick lookup
+        const translationMap = new Map(llmTranslations.map((t) => [t.buttonId, t]));
+        // Apply translations
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                const translation = translationMap.get(button.id);
+                if (!translation)
+                    return;
+                // Apply label translation
+                if (translation.translatedLabel) {
+                    button.label = translation.translatedLabel;
+                }
+                // Apply message translation (vocalization in OBF)
+                if (translation.translatedMessage) {
+                    button.message = translation.translatedMessage;
+                    // Update semantic action if symbols provided
+                    if (translation.symbols && translation.symbols.length > 0) {
+                        if (!button.semanticAction) {
+                            button.semanticAction = {
+                                category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+                                text: translation.translatedMessage,
+                            };
+                        }
+                        button.semanticAction.richText = {
+                            text: translation.translatedMessage,
+                            symbols: translation.symbols,
+                        };
+                    }
+                }
+            });
+        });
+        // Save and return
+        this.saveFromTree(tree, outputPath);
+        return fs_1.default.readFileSync(outputPath);
+    }
 }
 exports.ObfProcessor = ObfProcessor;

package/dist/processors/snapProcessor.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SnapProcessor = void 0;
 const baseProcessor_1 = require("../core/baseProcessor");
 const treeStructure_1 = require("../core/treeStructure");
-const idGenerator_1 = require("../optional/analytics/utils/idGenerator");
+const idGenerator_1 = require("../utilities/analytics/utils/idGenerator");
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));

package/dist/processors/touchchatProcessor.d.ts

@@ -1,6 +1,7 @@
 import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString, SourceString } from '../core/baseProcessor';
 import { AACTree } from '../core/treeStructure';
 import { ValidationResult } from '../validation/validationTypes';
+import { type ButtonForTranslation, type LLMLTranslationResult } from '../utilities/translation/translationProcessor';
 declare class TouchChatProcessor extends BaseProcessor {
     private tree;
     private sourceFile;
@@ -30,5 +31,30 @@ declare class TouchChatProcessor extends BaseProcessor {
      * @returns Promise with validation result
      */
     validate(filePath: string): Promise<ValidationResult>;
+    /**
+     * Extract symbol information from a TouchChat file for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to TouchChat .ce file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer: string | Buffer): ButtonForTranslation[];
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to TouchChat .ce file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated TouchChat file
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated TouchChat file
+     */
+    processLLMTranslations(filePathOrBuffer: string | Buffer, llmTranslations: LLMLTranslationResult[], outputPath: string, options?: {
+        allowPartial?: boolean;
+    }): Buffer;
 }
 export { TouchChatProcessor };

package/dist/processors/touchchatProcessor.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TouchChatProcessor = void 0;
 const baseProcessor_1 = require("../core/baseProcessor");
 const treeStructure_1 = require("../core/treeStructure");
-const idGenerator_1 = require("../optional/analytics/utils/idGenerator");
+const idGenerator_1 = require("../utilities/analytics/utils/idGenerator");
 const stringCasing_1 = require("../core/stringCasing");
 const adm_zip_1 = __importDefault(require("adm-zip"));
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
@@ -14,6 +14,7 @@ const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const touchChatValidator_1 = require("../validation/touchChatValidator");
+const translationProcessor_1 = require("../utilities/translation/translationProcessor");
 const toNumberOrUndefined = (value) => typeof value === 'number' ? value : undefined;
 const toStringOrUndefined = (value) => typeof value === 'string' && value.length > 0 ? value : undefined;
 const toBooleanOrUndefined = (value) => typeof value === 'number' ? value !== 0 : undefined;
@@ -842,5 +843,85 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
     async validate(filePath) {
         return touchChatValidator_1.TouchChatValidator.validateFile(filePath);
     }
+    /**
+     * Extract symbol information from a TouchChat file for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to TouchChat .ce file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Collect all buttons from all pages
+        const allButtons = [];
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                // Add page context to each button
+                button.pageId = page.id;
+                button.pageName = page.name || page.id;
+                allButtons.push(button);
+            });
+        });
+        // Use shared utility to extract buttons with translation context
+        return (0, translationProcessor_1.extractAllButtonsForTranslation)(allButtons, (button) => ({
+            pageId: button.pageId,
+            pageName: button.pageName,
+        }));
+    }
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to TouchChat .ce file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated TouchChat file
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated TouchChat file
+     */
+    processLLMTranslations(filePathOrBuffer, llmTranslations, outputPath, options) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Validate translations using shared utility
+        const buttonIds = Object.values(tree.pages).flatMap((page) => page.buttons.map((b) => b.id));
+        (0, translationProcessor_1.validateTranslationResults)(llmTranslations, buttonIds, options);
+        // Create a map for quick lookup
+        const translationMap = new Map(llmTranslations.map((t) => [t.buttonId, t]));
+        // Apply translations
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                const translation = translationMap.get(button.id);
+                if (!translation)
+                    return;
+                // Apply label translation
+                if (translation.translatedLabel) {
+                    button.label = translation.translatedLabel;
+                }
+                // Apply message translation
+                if (translation.translatedMessage) {
+                    button.message = translation.translatedMessage;
+                    // Update semantic action if symbols provided
+                    if (translation.symbols && translation.symbols.length > 0) {
+                        if (!button.semanticAction) {
+                            button.semanticAction = {
+                                category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+                                text: translation.translatedMessage,
+                            };
+                        }
+                        button.semanticAction.richText = {
+                            text: translation.translatedMessage,
+                            symbols: translation.symbols,
+                        };
+                    }
+                }
+            });
+        });
+        // Save and return
+        this.saveFromTree(tree, outputPath);
+        return fs_1.default.readFileSync(outputPath);
+    }
 }
 exports.TouchChatProcessor = TouchChatProcessor;

package/dist/utilities/translation/translationProcessor.d.ts

@@ -0,0 +1,119 @@
+/**
+ * LLM-Based Translation with Symbol Preservation
+ *
+ * This module provides utilities for translating AAC files while preserving
+ * symbol-to-word associations across different formats (gridset, OBF, Snap, etc.).
+ *
+ * The key insight: Different AAC formats have different internal structures,
+ * but they all share common concepts:
+ * - Buttons with labels and messages
+ * - Symbols attached to specific words
+ * - Need to preserve symbol positions during translation
+ *
+ * This module provides a format-agnostic way to:
+ * 1. Extract symbol information for LLM processing
+ * 2. Apply LLM translations with preserved symbols
+ *
+ * Usage:
+ * 1. Processor extracts buttons and calls extractSymbolsForLLM()
+ * 2. LLM translates and returns aligned symbols
+ * 3. Processor calls processLLMTranslations() to apply results
+ */
+/**
+ * Represents a symbol attached to text in a format-agnostic way
+ */
+export interface SymbolInfo {
+    text: string;
+    image?: string;
+    symbolLibrary?: string;
+    symbolPath?: string;
+}
+/**
+ * Button data extracted for translation (format-agnostic)
+ */
+export interface ButtonForTranslation {
+    buttonId: string;
+    pageId?: string;
+    pageName?: string;
+    label: string;
+    message: string;
+    textToTranslate: string;
+    symbols: SymbolInfo[];
+}
+/**
+ * LLM translation result with symbol mappings
+ */
+export interface LLMLTranslationResult {
+    buttonId: string;
+    translatedLabel?: string;
+    translatedMessage?: string;
+    symbols?: Array<{
+        text: string;
+        image?: string;
+    }>;
+}
+/**
+ * Extract symbols from a button for LLM-based translation.
+ *
+ * This is a format-agnostic helper that processors can use to normalize
+ * their button data into a common format for LLM processing.
+ *
+ * @param buttonId - Unique identifier for the button
+ * @param label - Button label text
+ * @param message - Button message/speak text
+ * @param symbols - Array of symbols from the button
+ * @param context - Optional page context
+ * @returns Normalized button data for translation
+ */
+export declare function normalizeButtonForTranslation(buttonId: string, label: string, message: string, symbols: SymbolInfo[], context?: {
+    pageId?: string;
+    pageName?: string;
+}): ButtonForTranslation;
+/**
+ * Extract symbols from various button formats.
+ *
+ * This helper handles different ways symbols might be stored in button data:
+ * - semanticAction.richText.symbols (gridset format)
+ * - symbolLibrary + symbolPath fields
+ * - image field with [library]path format
+ *
+ * @param button - Button object from any AAC format
+ * @returns Array of symbol info, or undefined if no symbols
+ */
+export declare function extractSymbolsFromButton(button: any): SymbolInfo[] | undefined;
+/**
+ * Extract all buttons from a file for LLM translation.
+ *
+ * This is a convenience method that processors can use to extract all
+ * translatable buttons with their symbols in a format-agnostic way.
+ *
+ * @param buttons - Array of button objects from any AAC format
+ * @param contextFn - Optional function to provide page context for each button
+ * @returns Array of normalized button data ready for LLM translation
+ */
+export declare function extractAllButtonsForTranslation(buttons: any[], contextFn?: (button: any) => {
+    pageId?: string;
+    pageName?: string;
+}): ButtonForTranslation[];
+/**
+ * Create a prompt for LLM translation with symbol preservation.
+ *
+ * This generates a structured prompt that instructs the LLM to translate
+ * while preserving symbol-to-word associations.
+ *
+ * @param buttons - Buttons to translate
+ * @param targetLanguage - Target language for translation
+ * @returns Prompt string for LLM
+ */
+export declare function createTranslationPrompt(buttons: ButtonForTranslation[], targetLanguage: string): string;
+/**
+ * Validate LLM translation results before applying.
+ *
+ * @param translations - LLM translation results
+ * @param originalButtonIds - Expected button IDs (optional, for validation)
+ * @param options - Validation options
+ * @throws Error if validation fails
+ */
+export declare function validateTranslationResults(translations: LLMLTranslationResult[], originalButtonIds?: string[], options?: {
+    allowPartial?: boolean;
+}): void;