Ziegel API Docs

Appearance

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 ​

bash
npm install @breadstone/ziegel-platform-translation

Usage ​

OpenAI Translation Setup ​

typescript
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 ​

typescript
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 ​

typescript
// 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 ​

typescript
// 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 ​

typescript
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 ​

typescript
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 ​

typescript
// 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 ​

typescript
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 ​

typescript
// 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 ​

typescript
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 ​

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
  • @breadstone/ziegel-core: Fundamental utilities and type definitions
  • rxjs: Observable patterns for reactive programming

License ​

MIT

Issues ​

Report issues at: GitHub Issues

Released under the MIT License.

© 2026 Ziegel Platform