@happyvertical/translator

中文文档
0.113.1发布于 2026/11/17ISCTypeScriptES Module近 30 天下载 5429

Standardized translation interface supporting Google Translate, DeepL, and LibreTranslate

原始使用文档
文档目录14 节
  1. Installation
  2. Quick Start
  3. Environment Variables
  4. Explicit Options
  5. Template Function
  6. API
  7. getTranslator(options?): Promise<Translator>
  8. Translator Interface
  9. TranslationResult
  10. LanguageDetectionResult
  11. Error Classes
  12. Environment Variables
  13. Utility Exports
  14. License

@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

VariableDescription
HAVE_TRANSLATOR_PROVIDERgoogle, deepl, or libretranslate
HAVE_TRANSLATOR_TIMEOUTRequest timeout in ms
HAVE_TRANSLATOR_MAX_RETRIESMax retry attempts
HAVE_TRANSLATOR_API_URLLibreTranslate instance URL
HAVE_TRANSLATOR_FREE_APIDeepL free tier (true/false)
HAVE_TRANSLATOR_PROJECT_IDGoogle Cloud project ID
GOOGLE_TRANSLATE_API_KEYGoogle Translate API key
DEEPL_API_KEYDeepL 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

版本与发布记录

@happyvertical/translator 共发布 131 个版本,首次发布于 2026/06/23;过去 12 个月发布了 131 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.12026/11/125 天前
0.112.02026/11/125 天前

关于 @happyvertical/translator 的常见问题

@happyvertical/translator 是什么?

Standardized translation interface supporting Google Translate, DeepL, and LibreTranslate

如何安装 @happyvertical/translator?

在项目目录运行 npm install @happyvertical/translator,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-translator-context,可以用 npx have-translator-context 直接运行。

@happyvertical/translator 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/translator 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/translator 可以商用吗?

@happyvertical/translator 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/translator 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/translator 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,429 次,日均约 181 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/translator 还在维护吗?

最新版本 0.113.1 发布于 2026/11/17(今天);至今共发布 131 个版本,其中过去 12 个月发布了 131 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。