Content
# Tool List
Based on `googletrans`, an independent translation tool providing API services and command-line tools.
## Features
- ✅ **Completely Free** - Using Google Translate web interface
- ✅ **Self-sufficient** - Independent virtual environment, no dependency conflicts
- ✅ **API Service** - Providing RESTful API interface
- ✅ **Command-line Tool** - Supporting single text and batch file translation
- ✅ **MCP Server** - One-click integration with Claude Desktop (see MCP Usage Guide.md)
- ✅ **Intelligent Rate Limiting** - 1.5 seconds interval, avoiding being blocked
- ✅ **Multi-language Support** - Supporting 100+ languages
## Directory Structure
```
📂 Project Structure
Googletrans-py-tool/
├── venv/ # Independent virtual environment
├── src/
│ └── googletrans_mcp/ # MCP Server
├── app.py # Flask API service
├── translate.py # CLI tool
├── batch_translate.py # Batch translation
├── smart_translate.py # Intelligent translation
├── translate_remaining.py # Supplementary translation
├── requirements.txt # Dependency list
├── README.md # Detailed documentation
└── MCP Usage Guide.md # MCP integration guide
```
## Quick Start
### 1. Start API Service
```bash
# Method 1: Using startup script (recommended)
./start.sh
# Method 2: Manual startup
source venv/bin/activate
python app.py
```
Access the service after startup: http://localhost:5000
### 2. Use API Interface
**Translate Text:**
```bash
curl -X POST http://localhost:5000/translate \
-H "Content-Type: application/json" \
-d '{
"text": "Hello World",
"target": "zh-cn"
}'
```
**Response Example:**
```json
{
"success": true,
"original": "Hello World",
"translated": "你好世界",
"source_lang": "en",
"target_lang": "zh-cn"
}
```
### 3. Use Command-line Tool
**Translate Single Text:**
```bash
source venv/bin/activate
python translate.py "Hello World" -t zh-cn
```
**Translate File:**
```bash
source venv/bin/activate
python translate.py -f input.txt -t zh-cn -o output.txt
```
**Batch Translation:**
```bash
source venv/bin/activate
# Translate all Markdown files
for file in ../.claude/agents/*.md; do
python translate.py -f "$file" -t zh-cn
done
```
## API Interface Documentation
### POST /translate
Translate text
**Request Parameters:**
| Parameter | Type | Required | Description |
|------|------|------|------|
| text | string | Yes | Text to translate |
| target | string | No | Target language code (default: zh-cn) |
| source | string | No | Source language code (default: auto detection) |
**Response Fields:**
| Field | Type | Description |
|------|------|------|
| success | boolean | Whether successful |
| original | string | Original text |
| translated | string | Translated text |
| source_lang | string | Source language code |
| target_lang | string | Target language code |
### GET /health
Health check
**Response Example:**
```json
{
"status": "healthy",
"service": "Google Translator API"
}
```
## Supported Language Codes
| Code | Language |
|------|------|
| zh-cn | Simplified Chinese |
| zh-tw | Traditional Chinese |
| en | English |
| ja | Japanese |
| ko | Korean |
| fr | French |
| de | German |
| es | Spanish |
| ru | Russian |
| ar | Arabic |
For more language codes, refer to: https://cloud.google.com/translate/docs/languages
## Command-line Tool Parameters
```bash
python translate.py [options]
Options:
text Text to translate
-f, --file FILE File path to translate
-t, --target LANG Target language code (default: zh-cn)
-s, --source LANG Source language code (default: auto)
-o, --output FILE Output file path
-d, --delay SECONDS Request interval time (seconds, default 1.5)
```
## Usage Examples
### Example 1: Translate Single Text
```bash
source venv/bin/activate
python translate.py "This is a test" -t zh-cn
# Output:
# Original: This is a test
# Translated: 这是一个测试
# Language: en -> zh-cn
```
### Example 2: Translate File
```bash
source venv/bin/activate
python translate.py -f document.md -t zh-cn -o document_cn.md
```
### Example 3: Use 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"Translated: {result['translated']}")
```
### Example 4: Batch Translate Markdown Files
```bash
#!/bin/bash
source venv/bin/activate
# Translate all Markdown files in agents directory
for file in ../.claude/agents/*.md; do
filename=$(basename "$file")
echo "Translating: $filename"
python translate.py -f "$file" -t zh-cn
echo "---"
done
echo "✅ Batch translation completed!"
```
## Precautions
1. **Request Frequency**: Default 1.5 seconds/request, avoid being blocked by Google
2. **Network Requirements**: Need to access Google services
3. **Text Length**: Single translation recommended not exceeding 5000 characters
4. **Stability**: Although googletrans has not been updated for 2 years, it is still stable and usable
## Troubleshooting
### API Connection Failure
Ensure the service is started:
```bash
curl http://localhost:5000/health
```
### Translation Failure
1. Check network connection
2. Reduce request frequency (increase delay parameter)
3. Check text encoding is UTF-8
### Virtual Environment Issues
Recreate virtual environment:
```bash
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
## Development and Extension
### Modify Request Interval
Edit `app.py`:
```python
TRANSLATE_DELAY = 2.0 # Modify to 2 seconds
```
### Add Other Translation Engines
Can add other translation engines as backup in `translate.py`:
```python
# Example: Add Baidu Translation
from deep_translator import BaiduTranslator
```
## License
MIT License
## Acknowledgements
- [googletrans](https://github.com/ssut/py-googletrans) - Google Translate Python library
- [Flask](https://flask.palletsprojects.com/) - Web framework
### 3. Use as MCP Server
Please refer to `MCP Usage Guide.md` for complete installation, configuration, testing, and troubleshooting instructions. Provided `fastmcp.json` to avoid googletrans and fastmcp httpx dependency conflicts.
