@breadstone/ziegel-platform-translation

A powerful translation service framework for TypeScript applications that provides AI-powered translation capabilities, multiple translation modes, and extensible provider architecture.

Features

• AI-Powered Translation: Integration with OpenAI GPT models for high-quality translations
• Multiple Translation Modes: Support for translate, polishing, summarization, and code explanation
• Extensible Architecture: Provider-based system for integrating different translation services
• Language Detection: Automatic source and target language detection
• Async/Promise-based: Modern async/await support for all translation operations
• Type Safety: Fully typed interfaces for queries, results, and configurations
• Request Factory Pattern: Flexible HTTP request handling with custom factory functions
• Configuration Management: Comprehensive configuration system for provider settings

Architecture

The translation system is built around several key components:

• ITranslationProvider: Interface for translation service providers
• TranslationProviderBase: Abstract base class for implementing custom providers
• OpenAiTranslationProvider: Ready-to-use OpenAI GPT integration
• ITranslateQuery: Interface defining translation request parameters
• ITranslateResult: Interface for translation response data
• IRequestFactoryFn: Factory function for HTTP request handling

Installation

npm install @breadstone/ziegel-platform-translation

Usage

OpenAI Translation Setup

import {
    OpenAiTranslationProvider,
    IOpenAiTranslationProviderConfig,
    FETCH_REQUEST_FACTORY_FN
} from '@breadstone/ziegel-platform-translation';

// Configure OpenAI provider
const config: IOpenAiTranslationProviderConfig = {
    apiUrl: 'https://api.openai.com',
    apiKey: 'your-openai-api-key',
    model: 'gpt-4',
    temperature: 0.3,
    maxTokens: 2000,
    topP: 1,
    frequencyPenalty: 0,
    presencePenalty: 0
};

// Create translation provider
const translationProvider = new OpenAiTranslationProvider(
    config,
    FETCH_REQUEST_FACTORY_FN
);

Basic Translation

import {
    ITranslateQuery,
    TranslateMode
} from '@breadstone/ziegel-platform-translation';

// Create translation query
const query: ITranslateQuery = {
    text: 'Hello, how are you today?',
    detectFrom: 'en',
    detectTo: 'de',
    mode: 'translate'
};

// Perform translation
const result = await translationProvider.translate(query);
console.log(result); // German translation

Different Translation Modes

// Standard translation
const translateQuery: ITranslateQuery = {
    text: 'This is a sample text for translation.',
    detectFrom: 'en',
    detectTo: 'fr',
    mode: 'translate'
};

// Text polishing/improvement
const polishQuery: ITranslateQuery = {
    text: 'This text needs some polishing and refinement.',
    detectFrom: 'en',
    detectTo: 'en',
    mode: 'polishing'
};

// Text summarization
const summarizeQuery: ITranslateQuery = {
    text: 'Long article text that needs to be summarized...',
    detectFrom: 'en',
    detectTo: 'en',
    mode: 'summarize'
};

// Code explanation
const explainCodeQuery: ITranslateQuery = {
    text: 'const result = array.map(item => item * 2);',
    detectFrom: 'javascript',
    detectTo: 'en',
    mode: 'explain-code'
};

// Execute translations
const translation = await translationProvider.translate(translateQuery);
const polished = await translationProvider.translate(polishQuery);
const summary = await translationProvider.translate(summarizeQuery);
const explanation = await translationProvider.translate(explainCodeQuery);

Localization File Translation

// Translate i18n locale files
const localizationQuery: ITranslateQuery = {
    text: JSON.stringify({
        "welcome": "Welcome to our application",
        "login": "Log in to continue",
        "error.required": "This field is required"
    }),
    detectFrom: 'en',
    detectTo: 'es',
    mode: 'translate'
};

const translatedLocale = await translationProvider.translate(localizationQuery);
// Result will preserve the key structure while translating values

Custom Translation Provider

import {
    TranslationProviderBase,
    ITranslationProviderConfig,
    ITranslateQuery,
    ITranslateResult
} from '@breadstone/ziegel-platform-translation';

// Define custom configuration
interface CustomProviderConfig extends ITranslationProviderConfig {
    customApiUrl: string;
    customApiKey: string;
    customModel: string;
}

// Implement custom provider
class CustomTranslationProvider extends TranslationProviderBase<CustomProviderConfig> {
    constructor(config: CustomProviderConfig) {
        super(config, {
            customApiUrl: 'https://api.custom-service.com',
            customApiKey: '',
            customModel: 'default-model'
        } as CustomProviderConfig);
    }

    async translate(query: ITranslateQuery): Promise<ITranslateResult> {
        // Custom translation logic
        const response = await fetch(`${this.config.customApiUrl}/translate`, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${this.config.customApiKey}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                text: query.text,
                from: query.detectFrom,
                to: query.detectTo,
                mode: query.mode
            })
        });

        const result = await response.json();
        return {
            translatedText: result.translation,
            sourceLanguage: query.detectFrom,
            targetLanguage: query.detectTo,
            confidence: result.confidence || 1.0
        };
    }
}

Custom Request Factory

import { IRequestFactoryFn } from '@breadstone/ziegel-platform-translation';

// Create custom request factory with additional headers
const customRequestFactory: IRequestFactoryFn = () => {
    return async (url: string, options?: RequestInit) => {
        const customOptions = {
            ...options,
            headers: {
                ...options?.headers,
                'User-Agent': 'MyApp/1.0',
                'X-Custom-Header': 'custom-value'
            }
        };

        return fetch(url, customOptions);
    };
};

// Use with provider
const provider = new OpenAiTranslationProvider(config, customRequestFactory);

Batch Translation

// Translate multiple texts
const queries: ITranslateQuery[] = [
    { text: 'Hello', detectFrom: 'en', detectTo: 'es', mode: 'translate' },
    { text: 'Goodbye', detectFrom: 'en', detectTo: 'es', mode: 'translate' },
    { text: 'Thank you', detectFrom: 'en', detectTo: 'es', mode: 'translate' }
];

// Process in parallel
const results = await Promise.all(
    queries.map(query => translationProvider.translate(query))
);

console.log('Translated texts:', results);

Error Handling

try {
    const result = await translationProvider.translate({
        text: 'Text to translate',
        detectFrom: 'en',
        detectTo: 'invalid-language',
        mode: 'translate'
    });
} catch (error) {
    console.error('Translation failed:', error);
    // Handle translation errors appropriately
}

Advanced Configuration

// Advanced OpenAI configuration
const advancedConfig: IOpenAiTranslationProviderConfig = {
    apiUrl: 'https://api.openai.com',
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4-turbo-preview',
    temperature: 0.1, // Lower for more consistent translations
    maxTokens: 4000,
    topP: 0.95,
    frequencyPenalty: 0.2,
    presencePenalty: 0.1
};

// Fine-tuned provider for specific use cases
const precisionProvider = new OpenAiTranslationProvider(
    advancedConfig,
    FETCH_REQUEST_FACTORY_FN
);

Package import points

import {
    // Core interfaces
    ITranslationProvider,
    ITranslateQuery,
    ITranslateResult,
    ITranslationProviderConfig,
    IRequestFactoryFn,

    // Main classes
    TranslationProviderBase,
    OpenAiTranslationProvider,

    // Configuration types
    IOpenAiTranslationProviderConfig,

    // Utilities
    TranslateMode,
    FETCH_REQUEST_FACTORY_FN
} from '@breadstone/ziegel-platform-translation';

API Documentation

For detailed API documentation, visit: API Docs

Supported Translation Modes

• translate: Standard text translation between languages
• polishing: Text improvement and refinement in the same language
• summarize: Text summarization to extract key points
• explain-code: Code explanation and documentation generation

Related Packages

• @breadstone/ziegel-core: Fundamental utilities and type definitions
• rxjs: Observable patterns for reactive programming

License

MIT

Issues

Report issues at: GitHub Issues