# ai-translate-sdk

**Repository Path**: hanxiaohui521/ai-translate-sdk

## Basic Information

- **Project Name**: ai-translate-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Translate SDK

通用可扩展的翻译 SDK，基于 **Adapter 模式** 设计。内置 OpenAI、Ollama、DeepSeek 及任意 OpenAI 兼容 API 的适配器。

```typescript
import { Translator, OpenAIAdapter } from 'ai-translate-sdk';

const translator = new Translator();
translator.use(new OpenAIAdapter({ apiKey: 'sk-...' }));

console.log(await translator.translate('你好世界', 'zh', 'en'));
// → "Hello World"
```

## 特性

- **任意语言对** — 中→英、英→中、法→日... 任何组合
- **10+ 内置 Provider** — OpenAI、Ollama、DeepSeek、Gemini、Anthropic、Claude、DashScope、Ernie 等
- **流式翻译 + 自动重试** — SSE 逐 token 输出，首次连接失败时指数退避重试
- **术语表** — 强制特定术语的翻译一致性（Transformer → Transformer 架构）
- **链式回退** — Provider 失败自动降级（OpenAI → Ollama）
- **共识翻译** — 多 Provider 并行投票，选出最佳译文
- **批量翻译** — 并发控制 + 自动检测 + 逐条目缓存
- **缓存** — LRU + TTL，可选持久化到本地文件（翻译记忆）
- **重试与超时** — 选择性重试（5xx/429 重试，4xx 跳过）+ 指数退避
- **熔断器** — 连续失败自动跳过故障 Provider，冷却后恢复
- **国际化文件翻译** — 直接读写 JSON / PO / YAML 格式
- **CLI 工具** — `npx ai-translate` 单条/批量/流式/交互/serve/i18n
- **HTTP 服务** — `ai-translate serve --port 8080` 启动 REST API
- **调试模式** — `debug: true` 输出完整内部链路日志
- **0 运行时依赖** — 仅用 Node.js 原生 fetch

---

## 安装

```bash
npm install ai-translate-sdk
```

Node.js >= 18 必需（使用原生 fetch）。

---

## 内置适配器

SDK 内置 8 个翻译适配器，均实现 `ITranslatorProvider` 接口。

### 通用配置选项（所有适配器通用）

| 选项 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `model` | `string` | 见各适配器 | 模型名称 |
| `systemPrompt` | `string \| null` | 翻译专用 prompt | 系统提示词，设为 `null` 禁用 |
| `temperature` | `number` | `0.1` | 生成温度，范围 0~2 |
| `maxTokens` | `number` | `4096` | 最大输出 token 数 |

---

### OpenAI

**环境变量：** `OPENAI_API_KEY`

```typescript
import { OpenAIAdapter } from 'ai-translate-sdk';

translator.use(new OpenAIAdapter({
  apiKey: process.env.OPENAI_API_KEY,       // 必填
  model: 'gpt-4o-mini',                     // 默认 gpt-4o-mini
  baseURL: 'https://api.openai.com/v1',     // 自定义地址（兼容第三方 API）
  temperature: 0.1,
  maxTokens: 4096,
}));
```

### Ollama（本地，无需 API Key）

**环境变量：** `OLLAMA_HOST` / `OLLAMA_BASE_URL` — 自定义服务地址

```typescript
import { OllamaAdapter } from 'ai-translate-sdk';

translator.use(new OllamaAdapter({
  model: 'qwen2:7b',                        // 默认 demonbyron/HY-MT1.5-1.8B
  baseURL: 'http://localhost:11434/v1',     // 默认值，可自定义
  // 额外支持 Ollama 特有参数：
  ollama: {
    numCtx: 8192,          // 上下文大小，长文本翻译时增大此值
    seed: 42,              // 固定随机种子，复现结果
    keepAlive: '10m',      // 模型驻留时间
    repeatPenalty: 1.1,    // 重复惩罚系数
    topK: 40,              // Top-K 采样
    topP: 0.9,             // Top-P 核采样
    mirostat: 0,           // Mirostat 采样 (0=关, 1=基本, 2=2.0)
    raw: false,             // 原始模式（跳过模板）
    stop: ['\n'],           // 停止序列
  },
}));
```

**地址优先级：** `baseURL` > `OLLAMA_HOST` 环境变量 > `http://localhost:11434/v1`

### DeepSeek

**环境变量：** `DEEPSEEK_API_KEY`

```typescript
import { DeepSeekAdapter } from 'ai-translate-sdk';

translator.use(new DeepSeekAdapter({
  apiKey: process.env.DEEPSEEK_API_KEY,
  model: 'deepseek-chat',                    // 默认 deepseek-chat
  baseURL: 'https://api.deepseek.com/v1',    // 自定义地址
}));
```

### Google Gemini

**环境变量：** `GEMINI_API_KEY`

> 注意：Gemini API 使用自己的原生 API，**不兼容** OpenAI 格式。

```typescript
import { GeminiAdapter } from 'ai-translate-sdk';

translator.use(new GeminiAdapter({
  apiKey: process.env.GEMINI_API_KEY,       // 必填
  model: 'gemini-2.0-flash',                // 默认 gemini-2.0-flash
  temperature: 0.1,
  maxTokens: 4096,
}));
```

### Anthropic Claude

**环境变量：** `ANTHROPIC_API_KEY`

> 注意：Anthropic API 使用自己的消息格式（system 独立），**不兼容** OpenAI 格式。

```typescript
import { AnthropicAdapter } from 'ai-translate-sdk';

translator.use(new AnthropicAdapter({
  apiKey: process.env.ANTHROPIC_API_KEY,    // 必填
  model: 'claude-sonnet-4-20250514',         // 默认 claude-sonnet-4-20250514
  temperature: 0.1,
  maxTokens: 4096,
}));
```

### Claude Adapter（备用实现）

**环境变量：** `ANTHROPIC_API_KEY`

基于 Messages API 的 Claude 适配器，支持更多配置：

```typescript
import { ClaudeAdapter } from 'ai-translate-sdk';

translator.use(new ClaudeAdapter({
  apiKey: process.env.ANTHROPIC_API_KEY,    // 必填
  model: 'claude-3-5-sonnet-20241022',      // 默认 claude-3-5-sonnet-20241022
  baseURL: 'https://api.anthropic.com/v1',  // 自定义地址
  temperature: 0.1,
  maxTokens: 4096,
}));
```

### 阿里通义千问 (DashScope)

**环境变量：** `DASHSCOPE_API_KEY`

```typescript
import { DashScopeAdapter } from 'ai-translate-sdk';

translator.use(new DashScopeAdapter({
  apiKey: process.env.DASHSCOPE_API_KEY,   // 必填
  model: 'qwen-max',                        // 默认 qwen-max
  temperature: 0.1,
  maxTokens: 4096,
}));
```

### 百度文心一言 (Ernie)

**环境变量：** `ERNIE_API_KEY` + `ERNIE_SECRET_KEY`

> 文心一言需要 **API Key + Secret Key** 两个凭证，获取方式见百度千帆平台。

```typescript
import { ErnieAdapter } from 'ai-translate-sdk';

translator.use(new ErnieAdapter({
  apiKey: process.env.ERNIE_API_KEY,        // 必填
  secretKey: process.env.ERNIE_SECRET_KEY,   // 必填
  model: 'ernie-4.0-8k-latest',             // 默认 ernie-4.0-8k-latest
  temperature: 0.1,
  maxTokens: 4096,
}));
```

### OpenAI 兼容 API（任意第三方）

对于任何兼容 OpenAI Chat API 格式的服务（零一万物、Groq、Together AI、vLLM、LocalAI 等），继承 `OpenAICompatibleAdapter` 即可：

```typescript
import { OpenAICompatibleAdapter } from 'ai-translate-sdk';

class CustomAdapter extends OpenAICompatibleAdapter {
  readonly name = 'custom';
  constructor(config = {}) {
    super({
      apiKey: config.apiKey,
      baseURL: config.baseURL ?? 'https://api.custom-service.com/v1',
      model: config.model ?? 'default-model',
      // 支持所有 OpenAICompatibleConfig 选项
      systemPrompt: null,          // 禁用 system prompt
      temperature: 0.1,
      maxTokens: 4096,
      extraBody: {                 // 额外请求体参数
        custom_option: 'value',
      },
    });
  }
}
```

### 适配器对比

| Adapter | 默认模型 | 环境变量 | 流式 | 需 API Key |
|---------|---------|----------|:----:|:----------:|
| `OpenAIAdapter` | `gpt-4o-mini` | `OPENAI_API_KEY` | ✅ | ✅ |
| `OllamaAdapter` | `demonbyron/HY-MT1.5-1.8B` | `OLLAMA_HOST` | ✅ | ❌ |
| `DeepSeekAdapter` | `deepseek-chat` | `DEEPSEEK_API_KEY` | ✅ | ✅ |
| `GeminiAdapter` | `gemini-2.0-flash` | `GEMINI_API_KEY` | ✅ | ✅ |
| `AnthropicAdapter` | `claude-sonnet-4-20250514` | `ANTHROPIC_API_KEY` | ✅ | ✅ |
| `ClaudeAdapter` | `claude-3-5-sonnet-20241022` | `ANTHROPIC_API_KEY` | ✅ | ✅ |
| `DashScopeAdapter` | `qwen-max` | `DASHSCOPE_API_KEY` | ❌ | ✅ |
| `ErnieAdapter` | `ernie-4.0-8k-latest` | `ERNIE_API_KEY` + `ERNIE_SECRET_KEY` | ❌ | ✅ (含 Secret) |

---

## API 参考

### `Translator` 类

```typescript
const t = new Translator(options?: TranslatorOptions);
```

#### 构造选项 `TranslatorOptions`

| 选项 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `defaultFrom` | `LanguageCode` | `'auto'` | 默认源语言 |
| `defaultTo` | `LanguageCode` | `'en'` | 默认目标语言 |
| `timeout` | `number` | — | 单次请求超时 (ms) |
| `retryCount` | `number` | `0` | 失败重试次数 |
| `retryDelay` | `number` | `0` | 重试延迟基数 (ms)，指数退避 |
| `retryJitter` | `number` | `1000` | 重试随机抖动上限 (ms) |
| `maxRetryDelay` | `number` | `30000` | 重试退避上限 (ms) |
| `cache` | `boolean \| { maxSize?: number; ttl?: number; persistPath?: string }` | `false` | 缓存配置（支持持久化到本地文件） |
| `glossary` | `Glossary` | — | 全局术语表 |
| `requestInterval` | `number` | `0` | 请求间隔 (ms)，防 API 限流 |
| `circuitBreaker` | `boolean \| CircuitBreakerConfig` | `false` | 熔断器配置 |
| `autoDetect` | `boolean` | `false` | 启用自动语言检测 |
| `detectLanguage` | `(text) => string` | 内置检测 | 自定义语言检测器 |
| `streamChunkTimeout` | `number` | `同 timeout` | 流式 chunk 超时 (ms) |
| `debug` | `boolean` | `false` | 调试日志（stderr） |

#### 翻译方法

**`translate(text, from?, to?, opts?)`** → `Promise<string>`

最简用法，返回译文文本：

```typescript
// 位置参数
await t.translate('你好', 'zh', 'en');
await t.translate('Hello', 'en', 'zh', { provider: 'ollama' });

// 对象参数
await t.translate('Hello', { from: 'en', to: 'zh', noCache: true });

// 简写（依赖 defaultTo）
const t = new Translator({ defaultTo: 'zh' });
await t.translate('Hello'); // auto → zh
```

**`translateDetail(text, from?, to?, opts?)`** → `Promise<TranslateResult>`

返回含元数据的完整结果：

```typescript
const r = await t.translateDetail('你好', 'zh', 'en');
// { text: 'Hello', from: 'zh-CN', to: 'en', provider: 'openai', cached: false }
```

**`translateBatch(texts, from?, to?, opts?)`** → `Promise<TranslateResult[]>`

批量翻译，支持并发控制和逐条目自动检测：

```typescript
const results = await t.translateBatch(
  ['人工智能', '深度学习', '机器翻译'],
  'zh', 'en',
  { concurrency: 5 },
);

// 对象参数（逐条目 auto-detect）
const results = await t.translateBatch(
  ['hello', '你好', '안녕하세요'],
  { to: 'en', concurrency: 3 },
);
```

**`stream(text, from?, to?, opts?)`** → `AsyncGenerator<string>`

流式翻译，逐 token 输出，适用长文本：

```typescript
for await (const chunk of t.stream('你好世界', 'zh', 'en')) {
  process.stdout.write(chunk);
  // → "Hel" "lo" " Wor" "ld"
}

// 对象参数
for await (const chunk of t.stream('hello', { from: 'en', to: 'zh' })) {
  process.stdout.write(chunk);
}
```

如果 Provider 不支持 `stream()`，自动回退到 `translate()` 后一次性 yield。

**`translateWithConsensus(text, from?, to?, opts?)`** → `Promise<ConsensusResult>`

多 Provider 共识翻译：同时调用多个 Provider，通过投票选出最佳译文：

```typescript
const result = await t.translateWithConsensus('Hello', 'en', 'zh', {
  minVotes: 2,                 // 至少 2 票达成共识
  similarityThreshold: 0.8,    // 相似度阈值
  providers: ['openai', 'ollama'], // 指定参与投票的 Provider
  timeout: 5000,               // 单 Provider 超时
});
// {
//   consensus: '你好',          // 胜出译文
//   voteCount: 2,              // 得票数
//   totalVotes: 2,             // 总票数
//   agreed: true,              // 是否达成共识
//   votes: [                   // 投票详情
//     { provider: 'openai', text: '你好' },
//     { provider: 'ollama', text: '你好' },
//   ],
// }
```

#### Provider 管理

```typescript
t.use(provider, config?);           // 注册
t.use(new OpenAIAdapter({ apiKey }), { as: 'gpt4', fallback: true });
t.removeProvider('gpt4');           // 注销
t.getProvider('ollama');            // 获取
t.listProviders();                  // 列出
t.ping('ollama');                   // 健康检查 → boolean
```

#### 统计

```typescript
t.stats           // { totalCalls, cacheHits, errors }
t.getStats()      // 快照副本
t.resetStats()    // 清零
t.clearCache()    // 清空缓存
```

---

## 高级功能

### 术语表 Glossary

```typescript
// 全局术语表
const t = new Translator({
  glossary: { 'Transformer': 'Transformer 架构', 'attention': '注意力机制' },
});

// 单次覆盖（与全局合并，同键覆盖）
t.translate('Transformer attention mechanism', 'en', 'zh', {
  glossary: { 'attention mechanism': '自注意力机制' },
});

// 跳过全局术语表
t.translate('test', 'en', 'zh', { glossary: {} });
```

### 缓存

```typescript
const t = new Translator({
  cache: { maxSize: 1000, ttl: 3600000 }, // 1000 条, 1 小时过期
});

t.translate('hello', 'en', 'zh');  // 穿透 → 翻译 → 缓存
t.translate('hello', 'en', 'zh');  // 命中缓存

t.translate('hello', 'en', 'zh', { noCache: true }); // 跳过缓存
t.clearCache(); // 手动清空
```

### 缓存持久化（翻译记忆）

```typescript
// 缓存持久化到本地文件，进程重启后恢复
const t = new Translator({
  cache: {
    maxSize: 1000,
    persistPath: './translation-memory.json',
  },
});

await t.translate('Hello World', 'en', 'zh'); // 穿透 → 翻译 → 缓存到文件

// 新进程、新实例：从文件恢复缓存
const t2 = new Translator({
  cache: { persistPath: './translation-memory.json' },
});
await t2.translate('Hello World', 'en', 'zh'); // 缓存命中！无需调用 API

// 强制立即写入（默认 debounce 2 秒自动写入）
t.cache.flushSync?.();
```

### 共识翻译（多 Provider 投票）

```typescript
const t = new Translator();
t.use(new OpenAIAdapter({ apiKey }), { as: 'openai' });
t.use(new OllamaAdapter(), { as: 'ollama' });
t.use(new DeepSeekAdapter({ apiKey }), { as: 'deepseek' });

// 三个 Provider 同时翻译，选取得票最多的结果
const result = await t.translateWithConsensus(
  'Artificial intelligence is transforming the world.',
  'en', 'zh',
  { minVotes: 2 },
);

console.log(result.consensus); // 共识译文
console.log(`得票: ${result.voteCount}/${result.totalVotes}`);
console.log(result.agreed ? '✅ 已达成共识' : '⚠️ 未达成共识');

// 查看各 Provider 的译文
for (const vote of result.votes) {
  console.log(`[${vote.provider}] ${vote.text || vote.error}`);
}
```

### 国际化文件翻译（i18n）

```typescript
import { translateI18nFile, translateObject } from 'ai-translate-sdk';

// JSON 文件翻译
await translateI18nFile(translator, 'en.json', 'zh-CN.json', {
  from: 'en', to: 'zh-CN',
});

// PO (gettext) 文件翻译
await translateI18nFile(translator, 'messages.po', 'messages-zh.po', {
  from: 'en', to: 'zh-CN',
});

// YAML 文件翻译
await translateI18nFile(translator, 'en.yaml', 'zh.yaml', {
  from: 'en', to: 'zh-CN',
});

// 直接翻译内存中的对象（保留非字符串值）
const translated = await translateObject(translator, {
  title: 'Welcome',
  description: 'Hello World',
  version: 42, // 非字符串值保持不变
}, 'en', 'zh');
```

### 链式回退

```typescript
translator
  .use(new OpenAIAdapter({ apiKey }))
  .use(new OllamaAdapter(), { fallback: true })  // OpenAI 失败 → Ollama
  .use(new DeepSeekAdapter({ apiKey }), { fallback: true });

// 指定使用哪个
await t.translate('hello', 'en', 'zh', { provider: 'deepseek' });
```

### 请求间隔（限流保护）

```typescript
// 每 200ms 最多 1 个请求，防止打满 API 配额
const t = new Translator({ requestInterval: 200 });
await t.translateBatch(largeArray, 'en', 'zh', { concurrency: 5 });
```

### 调试日志

```typescript
const t = new Translator({ debug: true });
await t.translate('你好', 'zh', 'en');
// stderr:
// [2026-06-25 17:52:54.662] [INFO ] [AiTranslate] init { retryCount: 0, timeout: undefined, cache: false }
// [2026-06-25 17:52:54.663] [INFO ] [AiTranslate] register openai (primary)
// [2026-06-25 17:52:54.663] [DEBUG] [AiTranslate] resolve from="zh-CN" to="en"
// [2026-06-25 17:52:54.663] [DEBUG] [AiTranslate] detect text="你好" from="zh-CN"
// [2026-06-25 17:52:54.663] [DEBUG] [AiTranslate] cache-miss "你好" (zh-CN → en)
// [2026-06-25 17:52:55.789] [INFO ] [AiTranslate] translate provider="openai" "你好" → "Hello"
```

日志等级可通过 `logConfig` 自定义：

```typescript
import { Logger, LogLevel } from 'ai-translate-sdk';

const t = new Translator({
  debug: true,
  logConfig: {
    level: LogLevel.DEBUG,        // 输出所有日志（含 DEBUG）
    format: 'pretty',             // 'pretty' | 'json'
    timestamp: true,              // 显示时间戳
  },
});

// 使用预设
const t = new Translator({
  debug: true,
  logConfig: Logger.Presets.verbose,  // 开发调试
  logConfig: Logger.Presets.json,     // JSON 结构化日志
  logConfig: Logger.Presets.silent,   // 关闭日志
});
```

### 自定义 Provider

实现 `ITranslatorProvider` 接口即可创建自定义翻译适配器：

```typescript
import type { ITranslatorProvider } from 'ai-translate-sdk';

class MyAdapter implements ITranslatorProvider {
  /** 适配器唯一名称，用于 use() 注册和 provider 参数路由 */
  readonly name = 'my-service';

  /**
   * 翻译单条文本（必填）。
   * @param text    待翻译文本
   * @param from    源语言代码（BCP-47，如 zh-CN, en, ja）
   * @param to      目标语言代码
   * @param signal  可选的取消信号（AbortController）
   */
  async translate(
    text: string,
    from: string,
    to: string,
    signal?: AbortSignal,
  ): Promise<string> {
    const response = await fetch('https://api.example.com/translate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text, from, to }),
      signal, // 支持取消
    });
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    const data = await response.json();
    return data.translation;
  }

  // ── 以下为可选方法 ──

  /** 流式翻译（SSE 逐 token 输出） */
  async *stream(
    text: string,
    from: string,
    to: string,
    signal?: AbortSignal,
  ): AsyncGenerator<string, void, undefined> {
    // 实现逐块产出译文
    yield '逐';
    yield '块';
    yield '输';
    yield '出';
  }

  /** 批量翻译（如未实现，SDK 自动退化为并发调用 translate()） */
  async translateBatch?(
    texts: string[],
    from: string,
    to: string,
    signal?: AbortSignal,
  ): Promise<string[]> {
    return Promise.all(texts.map(t => this.translate(t, from, to, signal)));
  }

  /** 健康检查 */
  async ping?(): Promise<boolean> {
    try {
      const res = await fetch('https://api.example.com/health', { signal: AbortSignal.timeout(5000) });
      return res.ok;
    } catch { return false; }
  }

  /** 语言对支持判断（不实现则默认支持所有语言对） */
  supports?(from: string, to: string): boolean {
    return true; // 支持所有语言对
  }
}

// 注册使用
translator.use(new MyAdapter());
translator.use(new MyAdapter(), { as: 'my-custom', fallback: true });
await translator.translate('你好', 'zh', 'en', { provider: 'my-service' });
```

对于 OpenAI 兼容 API（DeepSeek、零一万物、Groq、Together AI、vLLM、LocalAI 等），继承 `OpenAICompatibleAdapter` 只需定义名称和默认参数：

```typescript
import { OpenAICompatibleAdapter } from 'ai-translate-sdk';

class CustomAdapter extends OpenAICompatibleAdapter {
  readonly name = 'custom';
  constructor(config = {}) {
    super({
      apiKey: config.apiKey,
      baseURL: config.baseURL ?? 'https://api.custom-service.com/v1',
      model: config.model ?? 'default-model',
      // 完整配置选项：
      systemPrompt: null,          // 禁用 system prompt
      temperature: 0.1,
      maxTokens: 4096,
      extraBody: {                 // 额外请求体参数
        custom_option: 'value',
      },
    });
  }
}

### 错误处理

```typescript
import {
  TranslateError,          // 通用翻译失败（带 provider 名和 cause）
  ProviderNotFoundError,   // 指定名称的 Provider 未注册
  NoProviderError,         // 无任何 Provider 注册
  UnsupportedLanguageError,// 语言对不支持
  ProviderHttpError,       // HTTP 错误（带 statusCode + isRetryable）
} from 'ai-translate-sdk';

try {
  await translator.translate('hi', 'en', 'zh');
} catch (err) {
  if (err instanceof ProviderHttpError && err.isRetryable) {
    // 5xx 或 429，可以重试
  }
}
```

---

## CLI 工具

`ai-translate` 命令行工具支持多种翻译模式，安装后全局使用：

```bash
npm install -g ai-translate-sdk
# 或者本地使用
npx ai-translate "你好世界"
```

### 基本用法

```bash
# 翻译单条文本（自动检测语言 → 英文）
npx ai-translate "你好世界"
npx ai-translate "Hello"

# 指定语言对
npx ai-translate "Hello" -f en -t zh
npx ai-translate "Bonjour" -f fr -t en

# JSON 格式输出
npx ai-translate "Good morning" -t zh --json
```

### 翻译模式

#### 1. 单条翻译（默认）

```bash
npx ai-translate "文本" [选项]
```

常用选项：

| 选项 | 说明 |
|------|------|
| `-f, --from <lang>` | 源语言，默认 `auto`（自动检测） |
| `-t, --to <lang>` | 目标语言，默认 `en` |
| `-s, --stream` | 流式输出，逐 token 显示 |
| `-j, --json` | JSON 格式输出 |
| `--glossary <file>` | 术语表 JSON 文件 |

#### 2. 交互模式（推荐）

```bash
npx ai-translate interactive [选项]
```

美学终端界面，实时对话式翻译：

```
━━━ AI Translate · 智能翻译终端
────────────────────────────────────────
  English → 中文  [ollama]   :h 命令  :q 退出

English → 中文
❯ Hello World
── Hello World
  Hello World
────  ollama  1234ms
```

**启动参数：**

```bash
# 启动时指定语言和引擎
npx ai-translate interactive --from en --to zh
npx ai-translate interactive --ollama --model qwen2:7b
npx ai-translate interactive --from auto --to ja
```

**内置命令：**

| 命令 | 功能 |
|------|------|
| `:from <lang>` | 切换源语言 |
| `:to <lang>` | 切换目标语言 |
| `:pv <name>` | 切换翻译引擎 |
| `:pvs` | 列出可用引擎 |
| `:stats` | 查看 API 统计 |
| `:s` | 查看会话统计 |
| `:lang` | 查看支持语种 |
| `:c` | 清屏 |
| `:h` | 帮助 |
| `:q` | 退出 |

#### 3. 批量翻译

```bash
npx ai-translate batch input.json -f en -t zh -o output.json
```

输入文件为 JSON 字符串数组：

```json
["Hello World", "How are you?", "Good morning"]
```

#### 4. 国际化文件翻译（i18n）

```bash
# JSON 文件
npx ai-translate i18n en.json -f en -t zh -o zh-CN.json

# PO (gettext) 文件
npx ai-translate i18n messages.po -f en -t zh

# YAML 文件
npx ai-translate i18n en.yaml -f en -t zh
```

#### 5. HTTP 服务

```bash
npx ai-translate serve --port 8080
# POST /translate  单条翻译
# POST /batch      批量翻译
# GET  /health     健康检查
```

#### 6. 流式翻译

```bash
npx ai-translate -s "你好世界" -f zh -t en
```

### Provider 选择

```bash
# 使用 Ollama（本地，无需 API Key）
npx ai-translate --ollama "你好世界"

# 指定 Ollama 模型
npx ai-translate --ollama --model qwen2:7b "你好世界"

# 使用 OpenAI
npx ai-translate --api-key sk-xxx "你好世界"

# 使用其他 Provider
npx ai-translate --gemini "你好"
npx ai-translate --anthropic "Hello" -t zh
npx ai-translate --dashscope "你好"
npx ai-translate --ernie "你好"
```

### 配置文件

项目根目录下的 `.ai-translate.json` 会自动加载：

```json
{
  "ollama": true,
  "ollamaModel": "demonbyron/HY-MT1.5-1.8B",
  "from": "auto",
  "to": "zh",
  "timeout": 30000,
  "retryCount": 2
}
```

也可通过 `--config` 指定路径：

```bash
npx ai-translate --config ./my-config.json "你好世界"
```

### 完整选项

```
选项:
  -f, --from <lang>      源语言 (默认 auto)
  -t, --to <lang>        目标语言 (默认 en)
  --provider <name>      指定适配器
  --api-key <key>        API Key
  --model <name>         模型名称
  --base-url <url>       自定义 API 地址
  --ollama               使用 Ollama (无需 API Key)
  --ollama-url <url>     Ollama 服务地址
  --gemini               使用 Gemini
  --anthropic            使用 Anthropic
  --dashscope            使用通义千问
  --ernie                使用文心一言
  -s, --stream          流式输出
  -j, --json             JSON 格式
  --glossary <file>     术语表 JSON 文件
  --config <path>       配置文件路径
  -o, --output <file>   输出文件路径
  --concurrency <n>     并发数 (默认 5)
  --port <n>            serve 端口 (默认 3000)
  -h, --help            显示帮助
  -v, --version         显示版本
```

---

## HTTP 服务（Serve 模式）

通过 `serve` 子命令启动 REST API 服务，可供前端、移动端、微服务等外部应用调用翻译能力。

```bash
# 默认端口 3000，使用配置的 Provider
npx ai-translate serve

# 指定端口
npx ai-translate serve --port 8080

# 完整配置示例
npx ai-translate serve \
  --port 8080 \
  --ollama \
  --ollama-url http://192.168.1.100:11434/v1 \
  --model qwen2:7b \
  --to zh
```

### 端点

#### `GET /health` — 健康检查

```bash
curl http://localhost:8080/health
```

**成功响应（200）：**

```json
{
  "status": "ok",
  "providers": ["ollama"],
  "uptime": 123.45
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `status` | `string` | `"ok"` 正常、`"degraded"` 降级（Provider 不可用） |
| `providers` | `string[]` | 已注册的翻译 Provider 列表 |
| `uptime` | `number` | 服务运行秒数 |

#### `POST /translate` — 单条翻译

```bash
curl -X POST http://localhost:8080/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"你好世界","from":"zh","to":"en"}'
```

**请求体：**

| 字段 | 类型 | 必填 | 默认 | 说明 |
|------|------|:----:|:----:|------|
| `text` | `string` | ✅ | — | 待翻译文本 |
| `from` | `string` | ❌ | `"auto"` | 源语言代码（`"auto"` 自动检测） |
| `to` | `string` | ❌ | `"en"` | 目标语言代码 |
| `provider` | `string` | ❌ | — | 指定使用的 Provider 名称 |
| `noCache` | `boolean` | ❌ | `false` | 跳过缓存 |
| `glossary` | `object` | ❌ | — | 术语表 `{ "原词": "译文" }` |

**成功响应（200）：**

```json
{
  "text": "Hello World",
  "from": "zh-CN",
  "to": "en",
  "provider": "ollama",
  "cached": false
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `text` | `string` | 译文文本 |
| `from` | `string` | 实际使用的源语言代码 |
| `to` | `string` | 目标语言代码 |
| `provider` | `string` | 实际调用的 Provider 名称（缓存命中时为空字符串） |
| `cached` | `boolean` | 是否来自缓存 |

**错误响应（422）：**

```json
{
  "error": "Provider \"ollama\" failed: connection refused"
}
```

**完整示例：**

```bash
# 中译英 + 术语表
curl -X POST http://localhost:8080/translate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Transformer uses attention mechanism",
    "from": "en",
    "to": "zh",
    "glossary": {
      "Transformer": "Transformer 架构",
      "attention mechanism": "注意力机制"
    }
  }'

# 跳过缓存
curl -X POST http://localhost:8080/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"hello","from":"en","to":"zh","noCache":true}'
```

#### `POST /batch` — 批量翻译

```bash
curl -X POST http://localhost:8080/batch \
  -H "Content-Type: application/json" \
  -d '{
    "texts": ["人工智能", "深度学习", "自然语言处理"],
    "from": "zh",
    "to": "en"
  }'
```

**请求体：**

| 字段 | 类型 | 必填 | 默认 | 说明 |
|------|------|:----:|:----:|------|
| `texts` | `string[]` | ✅ | — | 待翻译文本数组 |
| `from` | `string` | ❌ | `"auto"` | 源语言代码 |
| `to` | `string` | ❌ | `"en"` | 目标语言代码 |
| `provider` | `string` | ❌ | — | 指定 Provider 名称 |
| `concurrency` | `number` | ❌ | `5` | 并发翻译数 |
| `noCache` | `boolean` | ❌ | `false` | 跳过缓存 |
| `glossary` | `object` | ❌ | — | 术语表 |

**成功响应（200）：**

```json
{
  "results": [
    { "text": "Artificial Intelligence", "from": "zh-CN", "to": "en", "provider": "ollama", "cached": false },
    { "text": "Deep Learning",          "from": "zh-CN", "to": "en", "provider": "ollama", "cached": false },
    { "text": "Natural Language Processing","from": "zh-CN","to": "en", "provider": "ollama", "cached": false }
  ]
}
```

每条结果的结构与 `/translate` 相同，额外支持 `error` 字段（单条失败时的错误消息）。

### CORS

服务默认允许所有来源（`Access-Control-Allow-Origin: *`），支持浏览器 `OPTIONS` 预检请求。

---

## 发布

```bash
# 发布 patch 版本（0.1.0 → 0.1.1）
npm run publish:go

# 指定版本类型
node scripts/publish.mjs minor    # 0.1.0 → 0.2.0
node scripts/publish.mjs major    # 0.1.0 → 1.0.0

# 预演（不实际执行）
node scripts/publish.mjs patch --dry
```

发布脚本自动执行：检查工作区 → 构建 → 整理 CHANGELOG → 版本升级 → npm publish → git push --tags。

---

## 迁移指南

### 从 `@google-cloud/translate` 迁移

```typescript
// Before
const { Translate } = require('@google-cloud/translate');
const translate = new Translate();
const [translation] = await translate.translate('你好', 'en');

// After
const { Translator } = require('ai-translate-sdk');
const { GoogleAdapter } = require('ai-translate-sdk/providers/google');
const t = new Translator();
t.use(new GoogleAdapter({ apiKey }));
const translation = await t.translate('你好', 'zh', 'en');
```

### 从 `openai` npm 包迁移

```typescript
// Before
const openai = new OpenAI({ apiKey });
const completion = await openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Translate zh to en: 你好' }],
});

// After
t.use(new OpenAIAdapter({ apiKey }));
await t.translate('你好', 'zh', 'en');
```

---

## Desktop 桌面应用

项目自带桌面应用，支持 **Electron** 和 **HTTP 服务** 两种运行模式，共享同一套 Web UI。

### 启动方式

```bash
# Electron 模式（原生桌面窗口）
npm run desktop

# HTTP 服务模式（浏览器访问 http://localhost:3756）
npm run serve
npm run serve:open    # 自动打开浏览器
```

### 功能

- 双语翻译（支持自动检测语言）
- 流式翻译（SSE 逐 token 输出）
- 批量翻译
- Provider 管理（添加/删除/配置翻译引擎）
- 翻译历史记录
- 运行统计（调用次数、缓存命中、错误次数）
- 设置持久化（默认语言、超时、重试、缓存、日志等级）
- 深色模式自动适配

### 日志配置

桌面应用的日志等级可在设置面板中调整：

| 等级 | 说明 |
|------|------|
| `DEBUG` | 全部输出（含请求参数、路由详情） |
| `INFO` | 正常日志（默认） |
| `WARN` | 仅警告与错误 |
| `ERROR` | 仅错误 |
| `SILENT` | 关闭日志 |

HTTP 服务模式也支持命令行参数：

```bash
node desktop/server.mjs --log-level debug
node desktop/server.mjs --log-level silent --port 8080
```

日志格式统一为 `[timestamp] [LEVEL] [Tag] message`：

```
[2026-06-25 17:31:10.757] [INFO] [Desktop] [IPC:a1b2c3] << translate (123ms)
[2026-06-25 17:31:10.758] [DEBUG] [Desktop] [a1b2c3] POST /api/translate { text: "Hello", from: "auto", to: "zh" }
```

## 常见问题

**Q: Ollama 连接被拒绝？**
```
fetch failed: connect ECONNREFUSED ::1:11434
```
→ 运行 `ollama serve` 启动服务

**Q: 模型未找到？**
→ 运行 `ollama pull qwen2:7b` 拉取模型

**Q: API Key 错误？**
→ 检查环境变量 `OPENAI_API_KEY` 或 `--api-key` 参数

**Q: 如何多个 Provider 一起用？**
```typescript
t.use(new OpenAIAdapter({ apiKey }));
t.use(new OllamaAdapter(), { fallback: true });
t.use(new DeepSeekAdapter({ apiKey }), { as: 'deepseek' });
await t.translate('hi', 'en', 'zh', { provider: 'deepseek' });
```

**Q: 如何添加新语言？**
→ `LanguageCode` 是 `string` 类型别名，直接用 BCP-47 代码即可：
```typescript
t.translate('hello', 'en', 'pt-BR'); // 巴西葡萄牙语
```

---

## 许可证

MIT