# @happyvertical/translator 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/translator/

版本：0\.113\.1
npm 元数据更新时间：2026-11-17T00:03:13.072Z
中文译文更新时间：2026-11-17T14:17:59.632Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/translator
原文对照：https://npmcn.com/package/%40happyvertical/translator/?lang=original
项目主页：https://github.com/happyvertical/sdk/tree/main/packages/translator#readme
源码仓库：https://github.com/happyvertical/sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：113 kB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-06-23T08:14:21.684Z
- 最新版本发布：2026-11-17T00:03:12.845Z
- 近 30 天下载量：5429（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：131（近 12 个月 131 个）

## 中文简介

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

## 安装

```sh
npm install @happyvertical/translator
```

也可以使用：`pnpm add @happyvertical/translator`、`yarn add @happyvertical/translator`、`bun add @happyvertical/translator`

## README

# @ happyvertical/ 翻译器

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

## 安装

```bash
pnpm add @happyvertical/translator
```

## 快速启动

### 环境变量

```bash
export HAVE_TRANSLATOR_PROVIDER=deepl
export DEEPL_API_KEY=your_key
```

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

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

### 明确选项

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

## 模板函数

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

```typescript
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` 接口

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

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

### `LanguageDetectionResult`

```typescript
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_PROVIDER` | `google`, (中文(简体) ), `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 是什么？

支持 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 和提交记录判断。

