@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.

Translation Services: Enterprise translation patterns with AI-powered translation, multiple providers, and extensible architecture.

🚀 Overview

@breadstone/ziegel-platform-translation provides:

• 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

📦 Installation

npm install @breadstone/ziegel-platform-translation
# or
yarn add @breadstone/ziegel-platform-translation

🧩 Features & Usage Examples

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);

📚 Package import points

import {
    // Core Interfaces
    ITranslationProvider,
    ITranslateQuery,
    ITranslateResult,
    ITranslationProviderConfig,

    // Providers
    TranslationProviderBase,
    OpenAiTranslationProvider,
    IOpenAiTranslationProviderConfig,

    // Request Factory
    IRequestFactoryFn,
    FETCH_REQUEST_FACTORY_FN,

    // Translation Modes
    TranslateMode
} from '@breadstone/ziegel-platform-translation';

📚 API Documentation

For detailed API documentation, visit: API Docs

Related Packages

• @breadstone/ziegel-platform: Core platform services
• @breadstone/ziegel-intl: Internationalization utilities
• @breadstone/ziegel-core: Foundation utilities

License

MIT

Issues

Please report bugs and feature requests in the Issue Tracker

---

Part of the ziegel Enterprise TypeScript Framework sourceLanguage: 'en', targetLanguage: 'es', mode: TranslateMode.Standard } ];

const batchResults = await translationProvider.translateBatch(batchQueries);

batchResults.forEach((result, index) => { console.log(${batchQueries[index].text} -> ${result.translatedText}); });

### Custom Translation Provider

```typescript
import {
  TranslationProviderBase,
  ITranslationProvider,
  ITranslationProviderConfig
} from '@breadstone/ziegel-platform-translation';

interface ICustomTranslationConfig extends ITranslationProviderConfig {
  apiEndpoint: string;
  apiKey: string;
  defaultModel: string;
}

class CustomTranslationProvider extends TranslationProviderBase implements ITranslationProvider {
  constructor(private config: ICustomTranslationConfig) {
    super();
  }

  public async translate(query: ITranslateQuery): Promise<ITranslateResult> {
    try {
      const response = await fetch(this.config.apiEndpoint, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.config.apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          text: query.text,
          source: query.sourceLanguage,
          target: query.targetLanguage,
          model: this.config.defaultModel
        })
      });

      const data = await response.json();

      return {
        translatedText: data.translation,
        confidence: data.confidence || 1.0,
        sourceLanguage: query.sourceLanguage,
        targetLanguage: query.targetLanguage,
        provider: 'custom-provider',
        metadata: {
          model: this.config.defaultModel,
          processingTime: data.processingTime
        }
      };
    } catch (error) {
      throw new Error(`Translation failed: ${error.message}`);
    }
  }

  public async translateBatch(queries: ITranslateQuery[]): Promise<ITranslateResult[]> {
    // Implement batch translation logic
    const results: ITranslateResult[] = [];

    for (const query of queries) {
      const result = await this.translate(query);
      results.push(result);
    }

    return results;
  }

  public isLanguageSupported(languageCode: string): boolean {
    const supportedLanguages = ['en', 'es', 'fr', 'de', 'it', 'pt'];
    return supportedLanguages.includes(languageCode);
  }
}

Request Factory Configuration

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

// Custom request factory with retry logic
const retryRequestFactory: IRequestFactoryFn = async (url, options) => {
  const maxRetries = 3;
  let lastError: Error;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }

      return response;
    } catch (error) {
      lastError = error;

      if (attempt < maxRetries) {
        // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
      }
    }
  }

  throw lastError;
};

// Use custom request factory
const providerWithRetry = new OpenAiTranslationProvider(config, {
  requestFactory: retryRequestFactory
});

Advanced Features

Translation Caching

class CachedTranslationProvider extends TranslationProviderBase {
  private cache = new Map<string, ITranslateResult>();

  constructor(private baseProvider: ITranslationProvider) {
    super();
  }

  public async translate(query: ITranslateQuery): Promise<ITranslateResult> {
    const cacheKey = this.generateCacheKey(query);

    // Check cache first
    if (this.cache.has(cacheKey)) {
      return this.cache.get(cacheKey)!;
    }

    // Translate and cache result
    const result = await this.baseProvider.translate(query);
    this.cache.set(cacheKey, result);

    return result;
  }

  private generateCacheKey(query: ITranslateQuery): string {
    return `${query.sourceLanguage}-${query.targetLanguage}-${query.mode}-${btoa(query.text)}`;
  }

  public clearCache(): void {
    this.cache.clear();
  }
}

// Usage
const cachedProvider = new CachedTranslationProvider(translationProvider);

Translation Quality Assessment

class QualityAssessedTranslationProvider extends TranslationProviderBase {
  constructor(private baseProvider: ITranslationProvider) {
    super();
  }

  public async translate(query: ITranslateQuery): Promise<ITranslateResult> {
    const result = await this.baseProvider.translate(query);

    // Assess translation quality
    const quality = await this.assessQuality(query, result);

    return {
      ...result,
      quality,
      metadata: {
        ...result.metadata,
        qualityScore: quality.score,
        qualityIssues: quality.issues
      }
    };
  }

  private async assessQuality(
    query: ITranslateQuery,
    result: ITranslateResult
  ): Promise<QualityAssessment> {
    const issues: string[] = [];
    let score = 1.0;

    // Check for obvious issues
    if (result.translatedText.length === 0) {
      issues.push('Empty translation');
      score -= 0.5;
    }

    if (result.translatedText === query.text) {
      issues.push('No translation performed');
      score -= 0.3;
    }

    // Check for HTML/markup preservation
    if (query.text.includes('<') && !result.translatedText.includes('<')) {
      issues.push('HTML markup not preserved');
      score -= 0.2;
    }

    return {
      score: Math.max(0, score),
      issues,
      confidence: result.confidence || 1.0
    };
  }
}

interface QualityAssessment {
  score: number;
  issues: string[];
  confidence: number;
}

Multi-Provider Translation

class MultiProviderTranslationService {
  private providers: ITranslationProvider[] = [];

  public addProvider(provider: ITranslationProvider): void {
    this.providers.push(provider);
  }

  public async translateWithFallback(query: ITranslateQuery): Promise<ITranslateResult> {
    let lastError: Error;

    for (const provider of this.providers) {
      try {
        const result = await provider.translate(query);

        // Return first successful translation
        if (result.translatedText && result.translatedText.trim().length > 0) {
          return result;
        }
      } catch (error) {
        lastError = error;
        console.warn(`Provider failed:`, error);
      }
    }

    throw new Error(`All translation providers failed. Last error: ${lastError?.message}`);
  }

  public async translateWithConsensus(query: ITranslateQuery): Promise<ITranslateResult> {
    const results = await Promise.allSettled(
      this.providers.map(provider => provider.translate(query))
    );

    const successfulResults = results
      .filter((result): result is PromiseFulfilledResult<ITranslateResult&gt; =>
        result.status === 'fulfilled')
      .map(result => result.value);

    if (successfulResults.length === 0) {
      throw new Error('No translation providers succeeded');
    }

    // Return the result with highest confidence
    return successfulResults.reduce((best, current) =>
      (current.confidence || 0) > (best.confidence || 0) ? current : best
    );
  }
}

Specialized Translation Modes

class SpecializedTranslationService {
  constructor(private provider: ITranslationProvider) {}

  public async translateCode(
    code: string,
    sourceLanguage: string,
    targetLanguage: string
  ): Promise<ITranslateResult> {
    const query: ITranslateQuery = {
      text: code,
      sourceLanguage,
      targetLanguage,
      mode: TranslateMode.Technical,
      context: 'programming code',
      preserveFormatting: true,
      instructions: 'Translate comments only, preserve code structure and syntax'
    };

    return this.provider.translate(query);
  }

  public async translateMarketing(
    content: string,
    sourceLanguage: string,
    targetLanguage: string
  ): Promise<ITranslateResult> {
    const query: ITranslateQuery = {
      text: content,
      sourceLanguage,
      targetLanguage,
      mode: TranslateMode.Creative,
      tone: 'persuasive',
      context: 'marketing content',
      preserveStyle: true
    };

    return this.provider.translate(query);
  }

  public async translateLegal(
    document: string,
    sourceLanguage: string,
    targetLanguage: string
  ): Promise<ITranslateResult> {
    const query: ITranslateQuery = {
      text: document,
      sourceLanguage,
      targetLanguage,
      mode: TranslateMode.Professional,
      tone: 'formal',
      context: 'legal document',
      accuracy: 'high'
    };

    return this.provider.translate(query);
  }
}

Configuration Options

OpenAI Provider Configuration

interface IOpenAiTranslationProviderConfig extends ITranslationProviderConfig {
  apiKey: string;
  model?: 'gpt-3.5-turbo' | 'gpt-4' | 'gpt-4-turbo';
  maxTokens?: number;
  temperature?: number;
  topP?: number;
  frequencyPenalty?: number;
  presencePenalty?: number;
  organizationId?: string;
  baseURL?: string;
}

const config: IOpenAiTranslationProviderConfig = {
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4-turbo',
  maxTokens: 2000,
  temperature: 0.1, // Low temperature for more consistent translations
  topP: 1.0,
  frequencyPenalty: 0.0,
  presencePenalty: 0.0
};

Translation Modes

enum TranslateMode {
  Standard = 'standard',      // Regular translation
  Professional = 'professional', // Business/formal translation
  Creative = 'creative',      // Literary/creative translation
  Technical = 'technical',    // Technical/specialized translation
  Casual = 'casual'          // Informal/conversational translation
}

Integration Examples

React Integration

import React, { useState, useEffect } from 'react';
import { OpenAiTranslationProvider } from '@breadstone/ziegel-platform-translation';

const TranslationComponent: React.FC = () => {
  const [translationProvider] = useState(() =>
    new OpenAiTranslationProvider({
      apiKey: process.env.REACT_APP_OPENAI_API_KEY!,
      model: 'gpt-4'
    })
  );

  const [text, setText] = useState('');
  const [translatedText, setTranslatedText] = useState('');
  const [isTranslating, setIsTranslating] = useState(false);

  const handleTranslate = async () => {
    if (!text.trim()) return;

    setIsTranslating(true);
    try {
      const result = await translationProvider.translate({
        text,
        sourceLanguage: 'en',
        targetLanguage: 'es',
        mode: TranslateMode.Standard
      });

      setTranslatedText(result.translatedText);
    } catch (error) {
      console.error('Translation failed:', error);
    } finally {
      setIsTranslating(false);
    }
  };

  return (
    <div&gt;
      <textarea
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="Enter text to translate..."
      />
      <button onClick={handleTranslate} disabled={isTranslating}>
        {isTranslating ? 'Translating...' : 'Translate'}
      </button&gt;
      {translatedText && (
        <div&gt;
          <h3>Translation:</h3>
          <p&gt;{translatedText}</p&gt;
        </div&gt;
      )}
    </div&gt;
  );
};

Node.js API Integration

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

const app = express();
app.use(express.json());

const translationProvider = new OpenAiTranslationProvider({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4'
});

app.post('/api/translate', async (req, res) => {
  try {
    const { text, sourceLanguage, targetLanguage, mode } = req.body;

    const result = await translationProvider.translate({
      text,
      sourceLanguage,
      targetLanguage,
      mode: mode || TranslateMode.Standard
    });

    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.post('/api/translate/batch', async (req, res) => {
  try {
    const { queries } = req.body;

    const results = await translationProvider.translateBatch(queries);

    res.json(results);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

Best Practices

1. API Key Management

// Use environment variables for API keys
const getApiKey = (): string => {
  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) {
    throw new Error('OPENAI_API_KEY environment variable is required');
  }
  return apiKey;
};

const provider = new OpenAiTranslationProvider({
  apiKey: getApiKey(),
  model: 'gpt-4'
});

2. Error Handling

class RobustTranslationService {
  constructor(private provider: ITranslationProvider) {}

  public async safeTranslate(query: ITranslateQuery): Promise<ITranslateResult | null> {
    try {
      return await this.provider.translate(query);
    } catch (error) {
      console.error('Translation error:', error);

      // Return fallback or null
      return {
        translatedText: query.text, // Fallback to original text
        confidence: 0,
        sourceLanguage: query.sourceLanguage,
        targetLanguage: query.targetLanguage,
        provider: 'fallback',
        error: error.message
      };
    }
  }
}

3. Rate Limiting

class RateLimitedTranslationProvider extends TranslationProviderBase {
  private requestQueue: Array<() => Promise<void>> = [];
  private isProcessing = false;
  private requestCount = 0;
  private resetTime = Date.now() + 60000; // 1 minute window

  constructor(
    private baseProvider: ITranslationProvider,
    private maxRequestsPerMinute: number = 60
  ) {
    super();
  }

  public async translate(query: ITranslateQuery): Promise<ITranslateResult> {
    return new Promise((resolve, reject) => {
      this.requestQueue.push(async () => {
        try {
          const result = await this.baseProvider.translate(query);
          resolve(result);
        } catch (error) {
          reject(error);
        }
      });

      this.processQueue();
    });
  }

  private async processQueue(): Promise<void> {
    if (this.isProcessing || this.requestQueue.length === 0) return;

    this.isProcessing = true;

    while (this.requestQueue.length > 0) {
      // Reset counter if time window expired
      if (Date.now() > this.resetTime) {
        this.requestCount = 0;
        this.resetTime = Date.now() + 60000;
      }

      // Check rate limit
      if (this.requestCount >= this.maxRequestsPerMinute) {
        const waitTime = this.resetTime - Date.now();
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      const request = this.requestQueue.shift()!;
      this.requestCount++;
      await request();
    }

    this.isProcessing = false;
  }
}

Migration Guide

Setting Up Translation Services

When migrating to this package:

1. Install the package and configure your preferred translation provider
2. Set up API keys securely using environment variables
3. Implement error handling for network and API failures
4. Consider caching for frequently translated content

// Migration example
// Before: Manual API calls
const translateText = async (text: string) => {
  const response = await fetch('https://api.translator.com/v1/translate', {
    method: 'POST',
    body: JSON.stringify({ text, from: 'en', to: 'es' })
  });
  return response.json();
};

// After: Using ziegel-platform-translation
const provider = new OpenAiTranslationProvider(config);
const result = await provider.translate({
  text,
  sourceLanguage: 'en',
  targetLanguage: 'es',
  mode: TranslateMode.Standard
});

Related Packages

• @breadstone/ziegel-core: Core utilities and patterns
• @breadstone/ziegel-platform: Platform services integration
• @breadstone/ziegel-intl: Internationalization support

Troubleshooting

Common Issues

1. API key errors: Ensure your OpenAI API key is valid and has sufficient credits
2. Rate limiting: Implement proper rate limiting to avoid API throttling
3. Large text handling: Break large texts into smaller chunks for translation

Debug Configuration

const debugProvider = new OpenAiTranslationProvider({
  apiKey: 'your-api-key',
  model: 'gpt-4',
  debug: true // Enable debug logging
});

API Reference

For detailed API documentation, see the auto-generated API reference.

ITranslationProvider

• translate(query: ITranslateQuery): Promise<ITranslateResult> - Translate single text
• translateBatch(queries: ITranslateQuery[]): Promise<ITranslateResult[]> - Translate multiple texts
• isLanguageSupported(languageCode: string): boolean - Check language support

ITranslateQuery

• text: string - Text to translate
• sourceLanguage: string - Source language code
• targetLanguage: string - Target language code
• mode?: TranslateMode - Translation mode
• context?: string - Additional context
• tone?: string - Desired tone

ITranslateResult

• translatedText: string - Translated text
• confidence?: number - Translation confidence score
• sourceLanguage: string - Source language
• targetLanguage: string - Target language
• provider: string - Provider used for translation
• metadata?: any - Additional metadata