Package Exports
- ai-localize
- ai-localize/dist/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ai-localize) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
AI Localize
A powerful Node.js package for translating documents and text from English (or any source language) to any target language using AI services like OpenAI, Google Translate, or Azure Translator. Features intelligent Redis caching to reduce API costs and improve performance.
π Features
- π€ AI-Powered Translation: Support for OpenAI GPT, Google Translate, Google gemini, and Azure Translator
- β‘ Redis Caching: Intelligent caching to reduce API calls and costs
- π Document Translation: Translate entire documents or specific fields
- π Batch Processing: Efficient batch translation with progress tracking
- π― Field Selection: Choose which fields to translate or exclude
- ποΈ Flexible Integration: Works with any JavaScript objects and documents
- π Cache Management: Built-in cache statistics and management
- π§ TypeScript Support: Full TypeScript definitions included
- π Multi-language Support: Translate to any language supported by AI providers
π¦ Installation
npm install ai-localizeπ Quick Start
import { LocalizationService } from 'ai-localize';
// Configuration
const config = {
redisUrl: 'redis://localhost:6379', // Your Redis URL
aiApiKey: 'your-openai-api-key', // Your AI API key
aiProvider: 'openai', // 'openai', 'google' 'azure' or 'gemini'
sourceLanguage: 'en', // Source language (default: 'en')
cacheExpiration: 86400, // Cache expiration in seconds (24 hours)
batchSize: 10, // Batch size for translations
};
// Create service instance
const localizationService = new LocalizationService({ config });
// Initialize (connects to Redis)
await localizationService.initialize();
// Example document
const product = {
name: 'Wireless Headphones',
description: 'High-quality wireless headphones with noise cancellation.',
category: 'Electronics',
price: 199.99,
tags: ['wireless', 'bluetooth', 'premium'],
};
// Translate to Spanish
const translatedProduct = await localizationService.translateDocument(
product,
'es'
);
console.log(translatedProduct);
// Output: { name: 'Auriculares InalΓ‘mbricos', description: 'Auriculares inalΓ‘mbricos de alta calidad con cancelaciΓ³n de ruido.', ... }
// Close connections
await localizationService.close();βοΈ Configuration
Required Configuration
interface LocalizationConfig {
redisUrl: string; // Redis connection URL
aiApiKey: string; // AI service API key
aiProvider: 'openai' | 'google' | 'azure'; // AI provider
}Optional Configuration
interface LocalizationConfig {
sourceLanguage?: string; // Source language (default: 'en')
cacheExpiration?: number; // Cache expiration in seconds (default: 86400)
batchSize?: number; // Batch size for translations (default: 10)
}π AI Provider Setup
OpenAI (Recommended)
const config = {
redisUrl: 'redis://localhost:6379',
aiApiKey: 'sk-your-openai-api-key',
aiProvider: 'openai',
};Get API Key: Visit OpenAI API to get your API key.
Google Translate
const config = {
redisUrl: 'redis://localhost:6379',
aiApiKey: 'your-google-translate-api-key',
aiProvider: 'google',
};Get API Key: Visit Google Cloud Console and enable the Translate API.
Azure Translator
const config = {
redisUrl: 'redis://localhost:6379',
aiApiKey: 'your-azure-translator-api-key',
aiProvider: 'azure',
};Get API Key: Visit Azure Portal and create a Translator resource.
Google Gemini
const config = {
redisUrl: 'redis://localhost:6379',
aiApiKey: 'your-google-gemini-api-key',
aiProvider: 'gemini',
};Get API Key: Visit Google Gemini and create a gemini.
π API Reference
LocalizationService
Constructor
new LocalizationService(options: LocalizationServiceOptions)Parameters:
options.config: LocalizationConfig object with required settings
Methods
initialize(): Promise<void>
Initialize the service and connect to Redis.
await localizationService.initialize();close(): Promise<void>
Close Redis connection.
await localizationService.close();translateDocument(document, targetLanguage, options?): Promise<any>
Translates a document to the target language.
Parameters:
document: Document object to translatetargetLanguage: Target language code (e.g., 'es', 'fr', 'de', 'hi', 'ja', 'ru')options: Optional DocumentTranslationOptions
Options:
interface DocumentTranslationOptions {
fields?: string[]; // Only translate these fields
excludeFields?: string[]; // Exclude these fields from translation
preserveStructure?: boolean; // Maintain document structure (default: true)
batchSize?: number; // Override default batch size
}Example:
const translatedDoc = await localizationService.translateDocument(
document,
'es', // Spanish
{
fields: ['name', 'description'], // Only translate these fields
excludeFields: ['_id', 'price'], // Exclude these fields
}
);translateText(text, targetLanguage, sourceLanguage?): Promise<TranslationResponse>
Translates a single text string.
Parameters:
text: Text string to translatetargetLanguage: Target language codesourceLanguage: Source language code (optional, uses config default)
Returns:
interface TranslationResponse {
translatedText: string;
sourceLanguage: string;
targetLanguage: string;
cached: boolean;
}Example:
const result = await localizationService.translateText(
'Hello, world!',
'es'
);
console.log(result.translatedText); // "Β‘Hola, mundo!"
console.log(result.cached); // false (first time)translateWithFieldMapping(document, targetLanguage, fieldMapping, options?): Promise<any>
Translates with custom field name mapping.
Parameters:
document: Document to translatetargetLanguage: Target language codefieldMapping: Object mapping original fields to new field namesoptions: Translation options
Example:
const fieldMapping = {
'name': 'nombre',
'description': 'descripcion',
};
const result = await localizationService.translateWithFieldMapping(
document,
'es',
fieldMapping
);translateNestedDocument(document, targetLanguage, nestedFields, options?): Promise<any>
Translates nested objects and arrays.
Parameters:
document: Document to translatetargetLanguage: Target language codenestedFields: Array of field names containing nested documentsoptions: Translation options
Example:
const result = await localizationService.translateNestedDocument(
document,
'it',
['comments', 'reviews'], // fields containing nested documents
{
fields: ['text', 'content'], // fields to translate in nested docs
}
);translateWithProgress(documents, targetLanguage, options?): Promise<any[]>
Batch translation with progress tracking.
Parameters:
documents: Array of documents to translatetargetLanguage: Target language codeoptions: Translation options with progress callback
Example:
const results = await localizationService.translateWithProgress(
documents,
'pt',
{
onProgress: (completed, total) => {
console.log(`Progress: ${completed}/${total}`);
},
}
);Cache Management
getCacheStats(): Promise<CacheStats>
Get cache statistics.
Returns:
interface CacheStats {
totalKeys: number;
memoryUsage: string;
connected: boolean;
}Example:
const stats = await localizationService.getCacheStats();
console.log(stats);
// { totalKeys: 150, memoryUsage: '2.5MB', connected: true }clearCache(sourceLanguage?, targetLanguage?): Promise<void>
Clear cache for specific language pairs.
Parameters:
sourceLanguage: Source language code (optional, uses config default)targetLanguage: Target language code (required)
Example:
// Clear cache for English to Spanish translations
await localizationService.clearCache('en', 'es');π Supported Languages
The package supports all languages supported by your chosen AI provider:
Common Language Codes
en- Englishes- Spanishfr- Frenchde- Germanit- Italianpt- Portugueseru- Russianja- Japaneseko- Koreanzh- Chinesehi- Hindiar- Arabicth- Thaivi- Vietnamesetr- Turkishpl- Polishnl- Dutchsv- Swedishda- Danishno- Norwegian
π‘ Usage Examples
Basic Document Translation
const product = {
name: 'Wireless Headphones',
description: 'High-quality wireless headphones with noise cancellation.',
category: 'Electronics',
price: 199.99,
tags: ['wireless', 'bluetooth', 'premium'],
};
const spanishProduct = await localizationService.translateDocument(product, 'es');
const frenchProduct = await localizationService.translateDocument(product, 'fr');
const hindiProduct = await localizationService.translateDocument(product, 'hi');Working with Arrays of Documents
// Example: Working with an array of products
const products = [
{
name: 'Wireless Headphones',
description: 'High-quality wireless headphones',
category: 'Electronics',
price: 199.99,
},
{
name: 'Smart Watch',
description: 'Fitness tracking smart watch',
category: 'Electronics',
price: 299.99,
},
];
// Translate all products
const translatedProducts = await localizationService.translateDocuments(
products,
'ja'
);
// Translate with field selection
const techProducts = await localizationService.translateDocuments(
products,
'de',
{ fields: ['name', 'description'] }
);Fetch all translation as json format
const allTranslationsJson = await localizationService.fetchAllKeysAsJson();Field Selection
// Translate only specific fields
const result = await localizationService.translateDocument(
document,
'ko',
{
fields: ['title', 'description', 'tags'],
}
);
// Exclude specific fields
const result = await localizationService.translateDocument(
document,
'zh',
{
excludeFields: ['_id', 'price', 'createdAt'],
}
);Batch Processing with Progress
// Example: Processing a large array of documents
const documents = [/* your array of documents */];
const translatedDocs = await localizationService.translateWithProgress(
documents,
'ar',
{
batchSize: 50,
onProgress: (completed, total) => {
const percentage = Math.round((completed / total) * 100);
console.log(`Translation progress: ${percentage}%`);
},
}
);π Performance Tips
- Use Redis Caching: Always use Redis to cache translations and avoid redundant API calls
- Batch Processing: Use batch methods for multiple documents
- Field Selection: Only translate necessary fields to reduce API usage
- Cache Management: Monitor cache usage and clear when needed
- Rate Limiting: Respect AI provider rate limits by adjusting batch sizes
- Connection Pooling: Reuse service instances when possible
π Prerequisites
- Node.js 16+
- Redis server
- AI API key (OpenAI, Google Translate, or Azure Translator)
π License
MIT
π€ Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
π Support
For issues and questions, please open an issue on GitHub.
π Changelog
v1.0.0
- Initial release
- Support for OpenAI, Google Translate, and Azure Translator
- Redis caching implementation
- Flexible document processing
- TypeScript support
- Batch processing with progress tracking
v1.0.2
- Added Google Gemini integration
- Fetch all cached key in json based on provided source and destination keys