多引擎中英翻译API搭建与使用教程

前一段时间正好考了英语四六级嘛，当时我在刷题的时候就想，能不能自己搭建一个翻译服务，个性化的去定制适合自己学习平台，于是我就搞了一个简单的中英文翻译的服务。在本教程中，我们将学习如何使用Python构建一个支持多种翻译引擎的中英翻译API服务。该服务不仅支持Google翻译，还支持百度翻译，可以根据需求选择最适合的翻译引擎。

一、环境准备

因为我使用的是Arch,所以接下来的操作我都会以Arch下的环境来进行演示

1. 安装Python（若未安装）

bash 复制代码

sudo pacman -S python python-pip

验证安装是否成功：

bash 复制代码

python --version  # 需要≥3.8（推荐3.10+）
pip --version

2. 创建项目目录与虚拟环境

（1）创建项目文件夹

bash 复制代码

mkdir -p ~/桌面/New\ Folder\ 1
cd ~/桌面/New\ Folder\ 1

（2）创建并激活虚拟环境

bash 复制代码

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境（Linux/Mac）
source venv/bin/activate

# 验证激活：终端前缀会出现 (New Folder 1) 或 (venv)

3. 安装依赖包

激活虚拟环境后，安装所需的依赖：

bash 复制代码

# 安装FastAPI（Web框架）、uvicorn（服务器）、deep-translator（翻译库）
pip install fastapi uvicorn deep-translator -i https://pypi.tuna.tsinghua.edu.cn/simple

二、编写API代码

在项目目录 ~/桌面/New\ Folder\ 1 下创建 translate_backend.py 文件，内容如下：

python 复制代码

from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
import hashlib
import time
import os
import urllib.request
import urllib.parse
import json

# 初始化FastAPI应用
app = FastAPI(title="多引擎中英翻译API")

# 跨域配置（允许前端任意域名请求）
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],        # 允许所有域名
    allow_credentials=True,
    allow_methods=["*"],        # 允许所有请求方法（GET/POST等）
    allow_headers=["*"],        # 允许所有请求头
)

# 定义请求体模型（规范入参格式）
class TranslateRequest(BaseModel):
    text: str                   # 待翻译文本（必填）
    direction: str = "auto"     # 翻译方向（可选，默认auto，支持zh2en/en2zh/auto）
    engine: str = "google"      # 翻译引擎（可选，默认google，支持google/baidu）

# 语言检测函数（纯本地逻辑，判断文本是中文/英文）
def detect_language(text: str) -> str:
    """检测文本语言类型，返回zh/en"""
    return "zh" if any('\u4e00' <= c <= '\u9fff' for c in text) else "en"

# 百度翻译函数
def baidu_translate(text: str, from_lang: str, to_lang: str) -> str:
    BAIDU_URL = 'https://fanyi-api.baidu.com/api/trans/vip/translate'
    APP_ID = os.getenv('BAIDU_APP_ID', '')  # 从环境变量读取
    SECRET_KEY = os.getenv('BAIDU_APP_KEY', '')  # 从环境变量读取
    
    if not APP_ID or not SECRET_KEY:
        raise Exception("请先配置百度翻译的APP_ID和SECRET_KEY环境变量")
    
    salt = str(round(time.time() * 1000))
    sign_str = APP_ID + text + salt + SECRET_KEY
    sign = hashlib.md5(sign_str.encode('utf-8')).hexdigest()
    
    params = {
        'q': text,
        'from': from_lang,
        'to': to_lang,
        'appid': APP_ID,
        'salt': salt,
        'sign': sign
    }
    
    # 构造URL
    url_params = urllib.parse.urlencode(params)
    full_url = BAIDU_URL + '?' + url_params
    
    # 发送请求
    try:
        with urllib.request.urlopen(full_url) as response:
            result = json.loads(response.read().decode())
            
        if 'trans_result' in result:
            return result['trans_result'][0]['dst']
        else:
            raise Exception(f"百度翻译错误: {result.get('error_msg', '未知错误')}")
    except Exception as e:
        raise Exception(f"百度翻译请求失败: {str(e)}")

# 核心翻译接口（POST请求）
@app.post("/translate/zh-en", summary="中英互译接口")
def translate_zh_en(request: TranslateRequest):
    try:
        # 1. 校验入参
        text = request.text.strip()
        if not text:
            raise HTTPException(status_code=400, detail="文本不能为空")

        # 2. 确定翻译方向与语言代码
        if request.direction == "auto":
            lang = detect_language(text)
            if lang == "zh":
                source, target = "zh-CN", "en"  # 简体中文→英文
                direction = "zh2en"
            else:
                source, target = "en", "zh-CN"  # 英文→简体中文
                direction = "en2zh"
        else:
            if request.direction == "zh2en":
                source, target = "zh-CN", "en"
            elif request.direction == "en2zh":
                source, target = "en", "zh-CN"
            else:
                raise HTTPException(status_code=400, detail="direction仅支持auto/zh2en/en2zh")
            direction = request.direction

        # 3. 根据引擎选择翻译方法
        if request.engine == "google":
            from deep_translator import GoogleTranslator
            translated = GoogleTranslator(source=source, target=target).translate(text)
        elif request.engine == "baidu":
            # 百度翻译需要使用特定的语言代码
            source = source.replace('-CN', '')  # 百度翻译不需要区域代码
            translated = baidu_translate(text, source, target)
        else:
            raise HTTPException(status_code=400, detail="engine仅支持google/baidu")

        # 4. 返回结果
        return {
            "code": 200,          # 成功状态码
            "data": {
                "original": text,      # 原始文本
                "translated": translated,  # 翻译结果
                "direction": direction,    # 实际翻译方向
                "engine": request.engine   # 使用的翻译引擎
            },
            "msg": "翻译成功"      # 提示信息
        }
    except Exception as e:
        # 异常捕获，返回错误信息
        raise HTTPException(status_code=500, detail=f"翻译失败：{str(e)}")

# 启动服务（主函数）
if __name__ == "__main__":
    # 先杀死占用8888端口的进程（避免端口冲突）
    os.system("kill -9 $(lsof -t -i:8888) 2>/dev/null")
    # 启动uvicorn服务器
    import uvicorn
    uvicorn.run(
        app=app,
        host="0.0.0.0",  # 允许所有IP访问
        port=8888        # 服务端口
    )

三、配置翻译服务

1. 百度翻译配置（可选）

如果要使用百度翻译，需要先在百度翻译开放平台注册账号并创建应用，获得APP ID和密钥。（一个月可免费使用100万字的额度每个人使用或者练手都够用）

配置方法：

在项目根目录创建.env文件
添加以下内容：

bash 复制代码

# 百度的app id
BAIDU_APP_ID=your_baidu_app_id
BAIDU_APP_KEY=your_baidu_secret_key

2. 创建启动脚本

创建一个启动脚本start_server.sh，内容如下：

bash 复制代码

#!/bin/bash
export $(grep -v '^#' .env | xargs)
python translate_backend.py

给予脚本执行权限：

bash 复制代码

chmod +x start_server.sh

四、启动API服务

1. 启动服务

保持虚拟环境激活状态，执行：

bash 复制代码

cd ~/桌面/New\ Folder\ 1
./start_server.sh

或者直接运行：

bash 复制代码

python translate_backend.py

启动成功日志：

复制代码

INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8888 (Press CTRL+C to quit)

2. 停止服务

按 Ctrl + C 即可停止服务。

五、API使用说明

1. 接口信息

项	说明
请求地址	`http://服务器IP:8888/translate/zh-en`（本地测试用 `localhost:8888`）
请求方法	POST
请求格式	JSON
跨域支持	支持（可直接被前端/其他服务调用）

2. 请求参数

参数名	类型	是否必填	可选值	说明
text	string	是	任意文本	待翻译的文本（中英均可）
direction	string	否	auto（默认）/zh2en/en2zh	翻译方向： auto=自动检测方向 zh2en=中译英 en2zh=英译中
engine	string	否	google（默认）/baidu	翻译引擎： google=Google翻译 baidu=百度翻译

3. 调用示例

（1）curl命令调用（本地测试）

示例1：自动检测方向（中文→英文），使用Google翻译

bash 复制代码

curl -X POST "http://localhost:8888/translate/zh-en" \
-H "Content-Type: application/json" \
-d '{"text":"为什么响应特别的慢","direction":"auto","engine":"google"}'

示例2：手动指定中译英，使用百度翻译

bash 复制代码

curl -X POST "http://localhost:8888/translate/zh-en" \
-H "Content-Type: application/json" \
-d '{"text":"为什么响应特别的慢","direction":"zh2en","engine":"baidu"}'

示例3：手动指定英译中，使用Google翻译

bash 复制代码

curl -X POST "http://localhost:8888/translate/zh-en" \
-H "Content-Type: application/json" \
-d '{"text":"Why is the response particularly slow","direction":"en2zh","engine":"google"}'

（2）Python代码调用

python 复制代码

import requests

# 接口地址
url = "http://localhost:8888/translate/zh-en"

# 请求参数
data = {
    "text": "为什么响应特别的慢",
    "direction": "zh2en",
    "engine": "google"
}

# 发送请求
response = requests.post(url, json=data)

# 解析响应
if response.status_code == 200:
    result = response.json()
    print("原始文本：", result["data"]["original"])
    print("翻译结果：", result["data"]["translated"])
    print("翻译引擎：", result["data"]["engine"])
else:
    print("请求失败：", response.json()["detail"])

（3）前端JS调用（Axios）

javascript 复制代码

import axios from 'axios';

async function translateText() {
  try {
    const response = await axios.post('http://localhost:8888/translate/zh-en', {
      text: '为什么响应特别的慢',
      direction: 'zh2en',
      engine: 'google'
    });
    console.log('翻译结果：', response.data.data.translated);
    console.log('使用引擎：', response.data.data.engine);
  } catch (error) {
    console.error('翻译失败：', error.response.data.detail);
  }
}

translateText();

4. 响应格式

成功响应（200）

json 复制代码

{
  "code": 200,
  "data": {
    "original": "为什么响应特别的慢",
    "translated": "Why is the response particularly slow",
    "direction": "zh2en",
    "engine": "google"
  },
  "msg": "翻译成功"
}

失败响应

（1）文本为空（400）

json 复制代码

{
  "detail": "文本不能为空"
}

（2）方向参数错误（400）

json 复制代码

{
  "detail": "direction仅支持auto/zh2en/en2zh"
}

（3）引擎参数错误（400）

json 复制代码

{
  "detail": "engine仅支持google/baidu"
}

（4）翻译异常（500）

json 复制代码

{
  "detail": "翻译失败：[具体错误信息]"
}

六、注意事项

虚拟环境 ：每次启动服务前需确保激活虚拟环境（source venv/bin/activate），否则会提示模块找不到；
端口占用 ：若8888端口被占用，可修改代码中port=8888为其他端口（如8080）；
离线运行 ：deep-translator首次启动会缓存翻译词典，后续断网仍可正常使用；
语言范围：仅支持中英互译，不支持其他语言；
部署说明 ：若需外网访问，需确保服务器开放对应端口（如8888），并将host="0.0.0.0"保留（允许外网访问）；
百度翻译：使用百度翻译需要配置有效的APP ID和密钥，否则会报错；
翻译质量：不同翻译引擎的质量可能有所差异，可根据实际情况选择合适的引擎。

七、常见问题排查

问题现象	解决方案
模块找不到（如fastapi/deep-translator）	确认虚拟环境已激活，重新执行`pip install fastapi uvicorn deep-translator`
端口被占用（Errno 98）	执行`kill -9 $(lsof -t -i:8888)`杀死占用进程，或修改代码中的端口号
语言代码错误（zh --> No support）	确保代码中使用`zh-CN`（简体中文）而非`zh`
响应慢（首次调用）	首次调用需缓存词典，后续调用会极速响应（<100ms）
百度翻译认证失败	检查`.env`文件中的APP ID和密钥是否正确
百度翻译报签名错误	检查生成签名的算法是否正确

最近正好在学next.js，所以就打算自己做一个学习的工具，可以上传文档，然后程序会读取你的文本，将其存储到数据库中，然后我们在阅读上传的文档的时候，可以通过选中文本，然后会出现选项，你可以选择将这段文本翻译或者使用其去问ai,项目会集成deepseek的推理模型，以及上述的翻译服务（node版本），目前正在处于开发阶段，开发一个初始版本可能还得两天,后续周末我会将这个项目的仓库发到评论区，有兴趣的同学可以去看一下，如果你有更好的想法，我们也可以一起去开发