@happyvertical/translator

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

支持 Google 翻译、 DeepL 和 Libre 翻译的标准化翻译界面

中文使用文档
文档目录14 节
  1. 安装
  2. 快速启动
  3. 环境变量
  4. 明确选项
  5. 模板函数
  6. API 密码
  7. getTranslator(options?): Promise<Translator>
  8. Translator 接口
  9. TranslationResult
  10. LanguageDetectionResult
  11. 错误分类
  12. 环境变量
  13. 工具出口
  14. 许可证

@ happyvertical/ 翻译器

标准化翻译界面支持Google Translate,DeepL,和Libre Translate. 采用工厂/适应器模式,采用统一 Translator 对所有提供者进行接口。 Google 和 DeepL 的供应商包括自动内存缓存 @happyvertical/cache。 。 。 .

安装

pnpm add @happyvertical/translator

快速启动

环境变量

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!"

明确选项

// 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',
});

模板函数

为重复使用创建预配置的翻译功能 :

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>

工厂功能. 读取 HAVE_TRANSLATOR_* 环境变量,与明确选项(明显胜出)合并.

Translator 接口

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

错误分类

全部扩展 TranslationError数字 :

  • TranslationError ——基础出错 code 财务报告和审定财务报表 provider 字段
  • UnsupportedLanguageError ——语言代码无效
  • QuotaExceededError ——供应商配额限制
  • AuthenticationError - 错误或缺失 API 密钥
  • InvalidTextError — 空或无效的输入文本

环境变量

变量说明
HAVE_TRANSLATOR_PROVIDERgoogle, (中文(简体) ), deepl,或 libretranslate
HAVE_TRANSLATOR_TIMEOUT请求超时( ms)
HAVE_TRANSLATOR_MAX_RETRIES最大重试尝试
HAVE_TRANSLATOR_API_URL自由翻译实例 URL
HAVE_TRANSLATOR_FREE_API深 L 自由级( E)true编号 :false(中文(简体) )
HAVE_TRANSLATOR_PROJECT_ID谷歌云项目ID
GOOGLE_TRANSLATE_API_KEY谷歌翻译 API 密钥
DEEPL_API_KEY深 L API 密钥

工具出口

  • LANGUAGE_NAMES – ISO 639-1 编码到英文名的地图
  • isValidLanguageCode(code) ——验证两字母语言代码
  • getLanguageName(code) 从代码中查找语言名称
  • normalizeConfidence(score) ——将分数常态化为 0–1 范围
  • isValidText(text) ——检查文本为非空
  • truncateText(text, maxLength) — 有椭圆形的调值

许可证

公务员制度委员会

版本与发布记录

@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 是什么?

支持 Google 翻译、 DeepL 和 Libre 翻译的标准化翻译界面

如何安装 @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 和提交记录判断。