@happyvertical/translator

Standardized translation interface supporting Google Translate, DeepL, and LibreTranslate. Uses a factory/adapter pattern with a unified Translator interface across all providers. Google and DeepL providers include automatic in-memory caching via @happyvertical/cache.

Installation

pnpm add @happyvertical/translator

Quick Start

Environment Variables

export HAVE_TRANSLATOR_PROVIDER=deepl
export DEEPL_API_KEY=your_key

import { getTranslator } from '@happyvertical/translator';

const translator = await getTranslator();
const result = await translator.translate('Hello, world!', 'es');
console.log(result.translatedText); // "¡Hola, mundo!"

Explicit Options

// Google Translate
const translator = await getTranslator({
  provider: 'google',
  apiKey: process.env.GOOGLE_TRANSLATE_API_KEY!,
});

// DeepL
const translator = await getTranslator({
  provider: 'deepl',
  apiKey: process.env.DEEPL_API_KEY!,
  freeApi: true,
});

// LibreTranslate (no API key required for public instances)
const translator = await getTranslator({
  provider: 'libretranslate',
  apiUrl: 'https://libretranslate.com',
});

Template Function

Create pre-configured translation functions for repeated use:

const t = translator.templateFunction('en', 'es');

const greeting = await t('Hello, world!'); // "¡Hola, mundo!"
const farewell = await t('Goodbye!');       // "¡Adiós!"

API

getTranslator(options?): Promise<Translator>

Factory function. Reads HAVE_TRANSLATOR_* environment variables, merged with explicit options (explicit wins).

Translator Interface

interface Translator {
  translate(text: string, targetLang: string, sourceLang?: string): Promise<TranslationResult>;
  detectLanguage(text: string): Promise<LanguageDetectionResult>;
  getSupportedLanguages(): Promise<SupportedLanguage[]>;
  translateBatch(texts: string[], targetLang: string, sourceLang?: string): Promise<TranslationResult[]>;
  templateFunction(sourceLang?: string, targetLang?: string): (text: string) => Promise<string>;
}

TranslationResult

interface TranslationResult {
  translatedText: string;
  sourceText: string;
  sourceLanguage: string;
  targetLanguage: string;
  confidence?: number;
  alternatives?: string[];
  detectedSourceLanguage: boolean;
  raw: any;
}

LanguageDetectionResult

interface LanguageDetectionResult {
  language: string;
  confidence: number;
  alternatives?: Array<{ language: string; confidence: number }>;
  raw: any;
}

Error Classes

All extend TranslationError:

• TranslationError — base error with code and provider fields
• UnsupportedLanguageError — invalid language code
• QuotaExceededError — provider quota limit hit
• AuthenticationError — bad or missing API key
• InvalidTextError — empty or invalid input text

Environment Variables

| Variable | Description | |----------|-------------| | HAVE_TRANSLATOR_PROVIDER | google, deepl, or libretranslate | | HAVE_TRANSLATOR_TIMEOUT | Request timeout in ms | | HAVE_TRANSLATOR_MAX_RETRIES | Max retry attempts | | HAVE_TRANSLATOR_API_URL | LibreTranslate instance URL | | HAVE_TRANSLATOR_FREE_API | DeepL free tier (true/false) | | HAVE_TRANSLATOR_PROJECT_ID | Google Cloud project ID | | GOOGLE_TRANSLATE_API_KEY | Google Translate API key | | DEEPL_API_KEY | DeepL API key |

Utility Exports

• LANGUAGE_NAMES — map of ISO 639-1 codes to English names
• isValidLanguageCode(code) — validates 2-letter language codes
• getLanguageName(code) — looks up language name from code
• normalizeConfidence(score) — normalizes scores to 0–1 range
• isValidText(text) — checks text is non-empty
• truncateText(text, maxLength) — truncates with ellipsis

License

ISC