# translate-node

**Repository Path**: yanfanVIP/translate-node

## Basic Information

- **Project Name**: translate-node
- **Description**: nodejs翻译
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-01
- **Last Updated**: 2025-11-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Translate Node

一个基于 Node.js 的离线翻译服务，使用 Bergamot 翻译引擎提供高质量的机器翻译 API。

## 特性

- 🚀 **离线翻译** - 无需依赖外部 API，完全本地化运行
- ⚡ **高性能** - 基于 Fastify 框架，使用 Web Worker 并行处理
- 🔄 **批量翻译** - 支持单个和批量文本翻译
- 🌍 **多语言支持** - 支持多种语言对的直接翻译和中间语言转换
- 📦 **RESTful API** - 简洁易用的 REST API 接口
- 🎯 **优先级队列** - 支持翻译任务优先级管理
- 🖥️ **Web 界面** - 提供现代化、响应式的在线翻译界面
- 🔁 **自动检测** - 支持源语言自动检测功能

## 技术栈

- **Node.js** - JavaScript 运行环境
- **Fastify** - 高性能 Web 框架
- **@fastify/cors** - 跨域资源共享支持
- **@fastify/static** - 静态文件服务支持
- **Bergamot Translator** - WASM 翻译引擎
- **Web Worker** - 多线程翻译处理

## 目录结构

```
.
├── lib/                              # 核心库
│   ├── worker/                       # Web Worker 线程
│   │   ├── bergamot-translator-worker.js
│   │   └── translator-worker.js
│   ├── index.js
│   └── translator.js                 # 翻译器核心逻辑
├── models/                           # 翻译模型
│   ├── index.json
│   └── registry.json                 # 模型注册表
├── public/                           # 静态文件
│   └── index.html                    # Web 翻译界面
├── alias.js                          # 语言别名映射
├── api.js                            # API 路由定义
├── app.js                            # 服务入口文件
└── package.json
```

## 安装

```bash
# 克隆项目
git clone <repository-url>

# 进入项目目录
cd translate-node

# 安装依赖
npm install
```

## 模型下载
```
https://github.com/mozilla/firefox-translations-models
```
下载模型后，将模型文件放入 `models/` 目录，解压所有模型文件，并更新 `registry.json` 配置文件。

## 运行

### 生产环境

```bash
npm start
```

### 开发环境

```bash
npm run dev
```

### 自定义端口

```bash
# Windows
set PORT=8080 && npm start

# Linux/Mac
PORT=8080 npm start
```

服务启动后，默认地址为：`http://127.0.0.1:3000`

## Web 界面

服务启动后，可以通过浏览器访问以下地址使用图形化翻译界面：

```
http://127.0.0.1:3000/index.html
```

### 界面功能

- ✨ **现代化设计** - 渐变背景、圆角卡片、优雅的动画效果
- 🔄 **单个文本翻译** - 实时翻译显示，支持字符统计
- 📝 **批量翻译** - 支持多行文本同时翻译（每行一个句子）
- 🔁 **语言切换** - 一键交换源语言和目标语言
- 🤖 **自动检测** - 源语言支持自动检测功能（固定在左侧）
- 📋 **复制功能** - 快速复制翻译结果到剪贴板
- ⌨️ **快捷键支持** - Ctrl+Enter 快速翻译
- 📊 **实时反馈** - 显示翻译耗时和状态提示
- 📱 **响应式设计** - 完美适配移动端和桌面端

### 支持的语言

界面支持 16 种语言，包括：
- 中文 (Chinese)
- 英语 (English)
- 德语 (German)
- 法语 (French)
- 西班牙语 (Spanish)
- 意大利语 (Italian)
- 葡萄牙语 (Portuguese)
- 俄语 (Russian)
- 日语 (Japanese)
- 波兰语 (Polish)
- 荷兰语 (Dutch)
- 捷克语 (Czech)
- 保加利亚语 (Bulgarian)
- 爱沙尼亚语 (Estonian)
- 波斯语 (Persian)
- 乌克兰语 (Ukrainian)

## API 文档

### 1. 获取 API 文档

```http
GET /docs
```

返回完整的 API 接口文档和示例。

### 2. 健康检查

```http
GET /health
```

**响应示例：**

```json
{
  "success": true
}
```

### 3. 获取支持的语言

```http
GET /languages
```

返回所有支持的翻译语言对列表。

**响应示例：**

```json
[
  {
    "from": "en",
    "to": "zh"
  },
  {
    "from": "zh",
    "to": "en"
  }
]
```

### 4. 语言检测

```http
POST /detect
```

**请求参数：**

| 参数 | 类型   | 必填 | 说明       |
| ---- | ------ | ---- | ---------- |
| text | string | 是   | 待检测文本 |

**请求示例：**

```json
{
  "text": "Hello World"
}
```

**响应示例：**

```json
{
  "result": "en",
  "delay": 5
}
```

### 5. 单个文本翻译

```http
POST /translate
```

**请求参数：**

| 参数     | 类型    | 必填 | 说明                                                  |
| -------- | ------- | ---- | ----------------------------------------------------- |
| text     | string  | 是   | 待翻译文本                                            |
| from     | string  | 否   | 源语言代码 (如: zh, en, de)，不传则自动检测           |
| to       | string  | 是   | 目标语言代码 (如: zh, en, de)                         |
| html     | boolean | 否   | 是否为 HTML 格式，默认 false                          |
| priority | number  | 否   | 优先级，数字越小优先级越高，默认 0                    |

**请求示例：**

```json
{
  "text": "Hello World",
  "from": "en",
  "to": "zh"
}
```

**响应示例：**

```json
{
  "result": {
    "target": {
      "text": "你好世界"
    }
  },
  "delay": 150
}
```

### 6. 批量文本翻译

```http
POST /translate/batch
```

**请求参数：**

| 参数     | 类型    | 必填 | 说明                          |
| -------- | ------- | ---- | ----------------------------- |
| texts    | array   | 是   | 待翻译文本数组                |
| from     | string  | 是   | 源语言代码                    |
| to       | string  | 是   | 目标语言代码                  |
| html     | boolean | 否   | 是否为 HTML 格式，默认 false  |
| priority | number  | 否   | 优先级，默认 0                |

**请求示例：**

```json
{
  "texts": ["Hello", "World", "Good morning"],
  "from": "en",
  "to": "zh"
}
```

**响应示例：**

```json
{
  "results": [
    {
      "index": 0,
      "sourceText": "Hello",
      "targetText": "你好"
    },
    {
      "index": 1,
      "sourceText": "World",
      "targetText": "世界"
    },
    {
      "index": 2,
      "sourceText": "Good morning",
      "targetText": "早上好"
    }
  ],
  "totalCount": 3,
  "delay": 200
}
```

## 使用示例

### cURL

```bash
# 单个翻译
curl -X POST http://localhost:3000/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello World","from":"en","to":"zh"}'

# 批量翻译
curl -X POST http://localhost:3000/translate/batch \
  -H "Content-Type: application/json" \
  -d '{"texts":["Hello","World"],"from":"en","to":"zh"}'
```

### JavaScript

```javascript
// 单个翻译
const response = await fetch("http://localhost:3000/translate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Hello World",
    from: "en",
    to: "zh",
  }),
});

const data = await response.json();
console.log(data.result.target.text); // 你好世界

// 批量翻译
const batchResponse = await fetch("http://localhost:3000/translate/batch", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    texts: ["Hello", "World", "Good morning"],
    from: "en",
    to: "zh",
  }),
});

const batchData = await batchResponse.json();
console.log(batchData.results);
```

### Python

```python
import requests

# 单个翻译
response = requests.post(
    "http://localhost:3000/translate",
    json={
        "text": "Hello World",
        "from": "en",
        "to": "zh"
    }
)
result = response.json()
print(result["result"]["target"]["text"])  # 你好世界

# 批量翻译
batch_response = requests.post(
    "http://localhost:3000/translate/batch",
    json={
        "texts": ["Hello", "World", "Good morning"],
        "from": "en",
        "to": "zh"
    }
)
batch_result = batch_response.json()
print(batch_result["results"])
```

## 配置选项

### 环境变量

- `PORT` - 服务端口，默认 3000
- `HOST` - 服务主机，默认绑定所有网卡

### 翻译器配置

在 `translator.js` 中可以配置以下选项：

- `cacheSize` - 缓存大小
- `workers` - Worker 线程数量
- `batchSize` - 批处理大小，影响吞吐量和延迟
- `pivotLanguage` - 中间语言，用于不支持直接翻译的语言对
- `downloadTimeout` - 模型下载超时时间（毫秒）

## 错误处理

所有 API 错误响应格式如下：

```json
{
  "requestId": "request-id",
  "url": "/translate",
  "method": "POST",
  "code": "ERROR_CODE",
  "error": "错误信息",
  "cause": "错误原因"
}
```

常见错误：

- `400` - 请求参数错误（缺少必要字段或字段类型错误）
- `500` - 服务器内部错误（翻译引擎错误或模型加载失败）

## 性能优化建议

1. **批量翻译** - 对于多个文本，使用批量翻译接口可以显著提高性能
2. **优先级管理** - 为重要任务设置更高优先级（更小的数字）
3. **Worker 数量** - 根据 CPU 核心数调整 Worker 线程数量
4. **批处理大小** - 增大 `batchSize` 可提高吞吐量，但会增加延迟

## 开发

### 运行测试

```bash
npm run test
```

## 许可证

ISC

## 作者

yanfan

## 贡献

欢迎提交 Issue 和 Pull Request！

## 常见问题

**Q: 支持哪些语言？**  
A: 访问 `/languages` 接口查看所有支持的语言对。

**Q: 可以离线使用吗？**  
A: 是的，这是一个完全离线的翻译服务，所有翻译模型都在本地运行。

**Q: 翻译质量如何？**  
A: 基于 Bergamot 翻译引擎，提供与主流翻译服务相当的质量。

**Q: 性能如何？**  
A: 使用 Web Worker 并行处理，批量翻译性能优异，具体取决于硬件配置。

**Q: 如何添加新的语言模型？**  
A: 将模型文件放入 `models/` 目录，并更新 `registry.json` 配置文件。