@ai/translate-core

A production-grade, framework-agnostic TypeScript library for AI-powered translation. Designed to be consumed by CLI tools, VS Code extensions, web backends, and other applications.

Features

• 🤖 AI Provider Abstraction - Works with any AI provider (OpenAI, Claude, Gemini, etc.)
• 📝 Multiple Translation Modes - Text, code, files, and batch processing
• 🧠 Translation Memory - Fuzzy matching for reusing previous translations
• ⚡ Smart Caching - LRU cache for improved performance
• 🔧 Code-Aware - Preserves code structure, indentation, and comments
• 📦 Batch Processing - Concurrent translation with progress tracking
• 🎯 Type-Safe - 100% TypeScript with comprehensive type definitions
• 🔌 Framework-Agnostic - Pure TypeScript, no framework dependencies

Installation

npm install @ai/translate-core
# or
yarn add @ai/translate-core
# or
pnpm add @ai/translate-core

Quick Start

1. Implement an AI Provider

First, create a provider that implements the AIProvider interface:

import { AIProvider, TranslationOptions, LanguageDetectionResult } from '@ai/translate-core';

class OpenAIProvider implements AIProvider {
  readonly name = 'openai';
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async translate(
    text: string,
    targetLanguage: string,
    options?: TranslationOptions
  ): Promise<string> {
    // Call OpenAI API
    const response = await fetch('https://api.openai.com/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'gpt-4',
        messages: [
          {
            role: 'system',
            content: `Translate the following text to ${targetLanguage}. ${options?.context || ''}`,
          },
          {
            role: 'user',
            content: text,
          },
        ],
      }),
    });

    const data = await response.json();
    return data.choices[0].message.content;
  }

  async detectLanguage(text: string): Promise<LanguageDetectionResult> {
    // Implement language detection
    // ...
    return { language: 'en', confidence: 0.95 };
  }
}

2. Use the Unified Translator

import { Translator } from '@ai/translate-core';

// Create provider
const provider = new OpenAIProvider('your-api-key');

// Create translator
const translator = new Translator({
  provider,
  useTranslationMemory: true,
  useCache: true,
});

// Translate text
const result = await translator.translateText(
  'Hello, world!',
  'es', // Spanish
  { sourceLanguage: 'en' }
);

console.log(result); // "¡Hola, mundo!"

Usage Examples

Text Translation

import { TextTranslator } from '@ai/translate-core';

const textTranslator = new TextTranslator(provider, {
  maxTextSize: 10000,
  chunkSize: 5000,
  autoDetectLanguage: true,
});

const translated = await textTranslator.translate(
  'This is a long text...',
  'fr' // French
);

Code Translation

import { CodeTranslator } from '@ai/translate-core';

const codeTranslator = new CodeTranslator(provider, {
  preserveIndentation: true,
  preserveComments: true,
  translateVariableNames: false,
});

const code = `
// This is a comment
function greet(name: string) {
  return \`Hello, \${name}!\`;
}
`;

const translatedCode = await codeTranslator.translate(
  code,
  'es',
  'typescript'
);

File Translation

import { FileTranslator } from '@ai/translate-core';

const fileTranslator = new FileTranslator(provider);

const result = await fileTranslator.translateFile(
  './src/messages.ts',
  'de' // German
);

console.log(result.content);
console.log(result.fileType); // 'code'

Batch Translation

import { BatchTranslator } from '@ai/translate-core';

const batchTranslator = new BatchTranslator(provider, {
  concurrency: 3,
  continueOnError: true,
  onProgress: (event) => {
    console.log(`Progress: ${event.percentage}% (${event.completed}/${event.total})`);
  },
});

const result = await batchTranslator.translateFiles(
  ['file1.ts', 'file2.ts', 'file3.md'],
  'ja' // Japanese
);

console.log(`Success: ${result.successCount}, Failed: ${result.failureCount}`);

Provider Registry

import { ProviderRegistry } from '@ai/translate-core';

const registry = new ProviderRegistry();

// Register multiple providers
registry.register('openai', new OpenAIProvider('key1'), true); // Set as default
registry.register('claude', new ClaudeProvider('key2'));
registry.register('gemini', new GeminiProvider('key3'));

// Use with translator
const translator = new Translator({
  provider: 'openai', // Use by name
  providerRegistry: registry,
});

// Switch providers
translator.setProvider('claude');

// List available providers
console.log(registry.list()); // ['openai', 'claude', 'gemini']

Translation Memory

import { TranslationMemory } from '@ai/translate-core';

const memory = new TranslationMemory(0.8); // 80% similarity threshold

// Store translations
memory.store('Hello', 'Hola', 'en', 'es');
memory.store('Goodbye', 'Adiós', 'en', 'es');

// Lookup exact match
const match = memory.lookup('Hello', 'en', 'es');
if (match?.isExact) {
  console.log(match.entry.translated); // 'Hola'
}

// Fuzzy matching
const fuzzy = memory.lookup('Helo', 'en', 'es'); // Typo
if (fuzzy && fuzzy.score > 0.8) {
  console.log(`Found match with ${fuzzy.score} similarity`);
}

// Export/Import
const entries = memory.export();
// Save to file...
memory.import(entries);

Caching

import { Cache } from '@ai/translate-core';

const cache = new Cache<string>(1000); // Max 1000 entries

cache.set('key1', 'value1');
const value = cache.get('key1');

console.log(cache.size()); // 1
console.log(cache.has('key1')); // true

cache.clear();

Language Detection

import { LanguageDetector } from '@ai/translate-core';

const detector = new LanguageDetector(provider);

const result = await detector.detect('Bonjour le monde');
console.log(result.language); // 'fr'
console.log(result.confidence); // 0.95

Advanced Usage

Custom Error Handling

import {
  FileNotSupportedError,
  InvalidLanguageError,
  TranslationTooLargeError,
  ProviderNotFoundError,
} from '@ai/translate-core';

try {
  await translator.translateFile('document.pdf', 'es');
} catch (error) {
  if (error instanceof FileNotSupportedError) {
    console.error(`File type ${error.extension} not supported`);
  } else if (error instanceof InvalidLanguageError) {
    console.error(`Invalid language: ${error.languageCode}`);
  } else if (error instanceof TranslationTooLargeError) {
    console.error(`Text too large: ${error.actualSize}/${error.maxSize}`);
  }
}

Custom Logger

import { Logger, LogLevel } from '@ai/translate-core';

const logger = new Logger({
  level: LogLevel.DEBUG,
  timestamps: true,
  handler: (level, message, data) => {
    // Custom logging logic
    console.log(`[${level}] ${message}`, data);
  },
});

logger.info('Translation started');
logger.debug('Processing chunk 1/5');
logger.error('Translation failed', error);

File Utilities

import { listFilesRecursively, readFile, writeFile } from '@ai/translate-core';

// List all TypeScript files
const files = await listFilesRecursively('./src', ['.ts', '.tsx']);

for (const file of files) {
  console.log(file.path, file.size);
}

// Read and write files
const content = await readFile('./input.txt');
await writeFile('./output.txt', translatedContent);

API Reference

Core Classes

• Translator - Unified translation API with all features
• TextTranslator - Plain text translation with chunking
• CodeTranslator - Code-aware translation
• FileTranslator - File-based translation
• BatchTranslator - Batch processing with concurrency
• ProviderRegistry - Manage multiple AI providers
• TranslationMemory - Fuzzy translation memory
• Cache - LRU cache implementation
• LanguageDetector - Language detection service

Interfaces

• AIProvider - Interface for AI provider implementations
• TranslationOptions - Options for translation requests
• FileTranslationResult - Result of file translation
• BatchTranslationResult - Result of batch translation

Error Classes

• FileNotSupportedError - Unsupported file type
• InvalidLanguageError - Invalid language code
• TranslationTooLargeError - Text exceeds size limit
• ProviderNotFoundError - Provider not in registry

Architecture

@ai/translate-core
├── providers/          # AI provider abstraction
│   ├── AIProvider.ts
│   └── ProviderRegistry.ts
├── translation/        # Translation engines
│   ├── Translator.ts
│   ├── TextTranslator.ts
│   ├── CodeTranslator.ts
│   ├── FileTranslator.ts
│   └── BatchTranslator.ts
├── memory/            # Memory and caching
│   ├── TranslationMemory.ts
│   └── Cache.ts
├── utils/             # Utilities
│   ├── fileIO.ts
│   ├── logger.ts
│   └── similarity.ts
└── errors/            # Error classes

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.