内容
# Google翻译工具 (Googletrans-py-tool)
基于 `googletrans` 的独立翻译工具，提供API服务和命令行工具。
## 特性
- ✅ **完全免费** - 使用Google翻译网页版接口
- ✅ **自给自足** - 独立虚拟环境，无依赖冲突
- ✅ **API服务** - 提供RESTful API接口
- ✅ **命令行工具** - 支持单文本和批量文件翻译
- ✅ **MCP 服务器** - 一键集成到 Claude Desktop（见 MCP使用指南.md）
- ✅ **智能限流** - 1.5秒间隔，避免被封
- ✅ **多语言支持** - 支持100+种语言
## 目录结构
```
📂 项目结构
Googletrans-py-tool/
├── venv/ # 独立虚拟环境
├── src/
│ └── googletrans_mcp/ # MCP 服务器
├── app.py # Flask API服务
├── translate.py # CLI工具
├── batch_translate.py # 批量翻译
├── smart_translate.py # 智能翻译
├── translate_remaining.py # 补充翻译
├── requirements.txt # 依赖列表
├── README.md # 详细文档
└── MCP使用指南.md # MCP 集成指南
```
## 快速开始
### 1. 启动API服务
```bash
# 方式1：使用启动脚本（推荐）
./start.sh
# 方式2：手动启动
source venv/bin/activate
python app.py
```
服务启动后访问：http://localhost:5000
### 2. 使用API接口
**翻译文本：**
```bash
curl -X POST http://localhost:5000/translate \
-H "Content-Type: application/json" \
-d '{
"text": "Hello World",
"target": "zh-cn"
}'
```
**响应示例：**
```json
{
"success": true,
"original": "Hello World",
"translated": "你好世界",
"source_lang": "en",
"target_lang": "zh-cn"
}
```
### 3. 使用命令行工具
**翻译单个文本：**
```bash
source venv/bin/activate
python translate.py "Hello World" -t zh-cn
```
**翻译文件：**
```bash
source venv/bin/activate
python translate.py -f input.txt -t zh-cn -o output.txt
```
**批量翻译：**
```bash
source venv/bin/activate
# 翻译所有Markdown文件
for file in ../.claude/agents/*.md; do
python translate.py -f "$file" -t zh-cn
done
```
## API接口文档
### POST /translate
翻译文本
**请求参数：**
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| text | string | 是 | 要翻译的文本 |
| target | string | 否 | 目标语言代码（默认：zh-cn） |
| source | string | 否 | 源语言代码（默认：auto自动检测） |
**响应字段：**
| 字段 | 类型 | 说明 |
|------|------|------|
| success | boolean | 是否成功 |
| original | string | 原文 |
| translated | string | 译文 |
| source_lang | string | 源语言代码 |
| target_lang | string | 目标语言代码 |
### GET /health
健康检查
**响应示例：**
```json
{
"status": "healthy",
"service": "Google Translator API"
}
```
## 支持的语言代码
| 代码 | 语言 |
|------|------|
| zh-cn | 简体中文 |
| zh-tw | 繁体中文 |
| en | 英语 |
| ja | 日语 |
| ko | 韩语 |
| fr | 法语 |
| de | 德语 |
| es | 西班牙语 |
| ru | 俄语 |
| ar | 阿拉伯语 |
更多语言代码请参考：https://cloud.google.com/translate/docs/languages
## 命令行工具参数
```bash
python translate.py [选项]
选项：
text 要翻译的文本
-f, --file FILE 要翻译的文件路径
-t, --target LANG 目标语言代码（默认：zh-cn）
-s, --source LANG 源语言代码（默认：auto）
-o, --output FILE 输出文件路径
-d, --delay SECONDS 请求间隔时间（秒，默认1.5）
```
## 使用示例
### 示例1：翻译单个文本
```bash
source venv/bin/activate
python translate.py "This is a test" -t zh-cn
# 输出：
# 原文: This is a test
# 译文: 这是一个测试
# 语言: en -> zh-cn
```
### 示例2：翻译文件
```bash
source venv/bin/activate
python translate.py -f document.md -t zh-cn -o document_cn.md
```
### 示例3：使用API（Python）
```python
import requests
url = "http://localhost:5000/translate"
data = {
"text": "Hello World",
"target": "zh-cn"
}
response = requests.post(url, json=data)
result = response.json()
if result['success']:
print(f"译文: {result['translated']}")
```
### 示例4：批量翻译Markdown文件
```bash
#!/bin/bash
source venv/bin/activate
# 翻译agents目录下的所有Markdown文件
for file in ../.claude/agents/*.md; do
filename=$(basename "$file")
echo "正在翻译: $filename"
python translate.py -f "$file" -t zh-cn
echo "---"
done
echo "✅ 批量翻译完成！"
```
## 注意事项
1. **请求频率**：默认1.5秒/次，避免被Google封禁
2. **网络要求**：需要能访问Google服务
3. **文本长度**：单次翻译建议不超过5000字符
4. **稳定性**：虽然googletrans已2年未更新，但仍然稳定可用
## 故障排除
### API连接失败
确保服务已启动：
```bash
curl http://localhost:5000/health
```
### 翻译失败
1. 检查网络连接
2. 降低请求频率（增加delay参数）
3. 检查文本编码是否为UTF-8
### 虚拟环境问题
重新创建虚拟环境：
```bash
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
## 开发与扩展
### 修改请求间隔
编辑 `app.py`：
```python
TRANSLATE_DELAY = 2.0 # 修改为2秒
```
### 添加其他翻译引擎
可以在 `translate.py` 中添加其他翻译引擎作为备用：
```python
# 例如：添加百度翻译
from deep_translator import BaiduTranslator
```
## 许可证
MIT License
## 致谢
- [googletrans](https://github.com/ssut/py-googletrans) - Google翻译Python库
- [Flask](https://flask.palletsprojects.com/) - Web框架
### 3. 作为 MCP 服务器使用
请参考 `MCP使用指南.md` 获取完整的安装、配置、测试、故障排除说明。已提供 `fastmcp.json` 避免 googletrans 与 fastmcp 的 httpx 依赖冲突。
