231 lines
6.3 KiB
Markdown
231 lines
6.3 KiB
Markdown
# 🚀 Quick Start Guide - Document Translation API
|
||
|
||
## Step-by-Step Setup (5 Minutes)
|
||
|
||
### 1️⃣ Open PowerShell in Project Directory
|
||
```powershell
|
||
cd d:\Translate
|
||
```
|
||
|
||
### 2️⃣ Run the Startup Script
|
||
```powershell
|
||
.\start.ps1
|
||
```
|
||
|
||
This will automatically:
|
||
- Create a virtual environment
|
||
- Install all dependencies
|
||
- Create necessary directories
|
||
- Start the API server
|
||
|
||
### 3️⃣ Test the API
|
||
|
||
**Open another PowerShell window** and run:
|
||
```powershell
|
||
python test_api.py
|
||
```
|
||
|
||
Or visit in your browser:
|
||
- **API Documentation**: http://localhost:8000/docs
|
||
- **API Status**: http://localhost:8000/health
|
||
|
||
## 📤 Translate Your First Document
|
||
|
||
### Using cURL (PowerShell)
|
||
```powershell
|
||
$file = Get-Item "your_document.xlsx"
|
||
Invoke-RestMethod -Uri "http://localhost:8000/translate" `
|
||
-Method Post `
|
||
-Form @{
|
||
file = $file
|
||
target_language = "es"
|
||
} `
|
||
-OutFile "translated_document.xlsx"
|
||
```
|
||
|
||
### Using Python
|
||
```python
|
||
import requests
|
||
|
||
with open('document.docx', 'rb') as f:
|
||
response = requests.post(
|
||
'http://localhost:8000/translate',
|
||
files={'file': f},
|
||
data={'target_language': 'fr'}
|
||
)
|
||
|
||
with open('translated_document.docx', 'wb') as out:
|
||
out.write(response.content)
|
||
```
|
||
|
||
### Using the Interactive API Docs
|
||
|
||
1. Go to http://localhost:8000/docs
|
||
2. Click on **POST /translate**
|
||
3. Click **"Try it out"**
|
||
4. Upload your file
|
||
5. Enter target language (e.g., `es` for Spanish)
|
||
6. Click **"Execute"**
|
||
7. Download the translated file
|
||
|
||
## 🌍 Supported Languages
|
||
|
||
Use these language codes in the `target_language` parameter:
|
||
|
||
| Code | Language | Code | Language |
|
||
|------|----------|------|----------|
|
||
| `es` | Spanish | `fr` | French |
|
||
| `de` | German | `it` | Italian |
|
||
| `pt` | Portuguese | `ru` | Russian |
|
||
| `zh` | Chinese | `ja` | Japanese |
|
||
| `ko` | Korean | `ar` | Arabic |
|
||
| `hi` | Hindi | `nl` | Dutch |
|
||
|
||
**Full list**: http://localhost:8000/languages
|
||
|
||
## 📋 Supported File Types
|
||
|
||
| Format | Extension | What's Preserved |
|
||
|--------|-----------|------------------|
|
||
| **Excel** | `.xlsx` | Formulas, merged cells, colors, borders, images |
|
||
| **Word** | `.docx` | Styles, tables, headers/footers, images |
|
||
| **PowerPoint** | `.pptx` | Layouts, animations, transitions, media |
|
||
|
||
## 🔧 Configuration
|
||
|
||
Edit `.env` file to customize:
|
||
|
||
```env
|
||
# Translation service: google (free) or deepl (requires API key)
|
||
TRANSLATION_SERVICE=google
|
||
|
||
# For DeepL (premium translation)
|
||
DEEPL_API_KEY=your_api_key_here
|
||
|
||
# Maximum file size in MB
|
||
MAX_FILE_SIZE_MB=50
|
||
```
|
||
|
||
## ⚠️ Troubleshooting
|
||
|
||
### Issue: "Virtual environment activation failed"
|
||
**Solution**:
|
||
```powershell
|
||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||
```
|
||
|
||
### Issue: "Module not found"
|
||
**Solution**:
|
||
```powershell
|
||
.\venv\Scripts\Activate.ps1
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### Issue: "Port 8000 already in use"
|
||
**Solution**:
|
||
Edit `main.py` line 307:
|
||
```python
|
||
uvicorn.run(app, host="0.0.0.0", port=8001, reload=True)
|
||
```
|
||
|
||
### Issue: "Translation quality is poor"
|
||
**Solution**:
|
||
1. Get a DeepL API key from https://www.deepl.com/pro-api
|
||
2. Update `.env`:
|
||
```env
|
||
TRANSLATION_SERVICE=deepl
|
||
DEEPL_API_KEY=your_key_here
|
||
```
|
||
|
||
## 📦 Project Structure
|
||
|
||
```
|
||
Translate/
|
||
├── main.py # FastAPI application (START HERE)
|
||
├── config.py # Configuration management
|
||
├── start.ps1 # Startup script (RUN THIS FIRST)
|
||
├── test_api.py # Testing script
|
||
│
|
||
├── services/ # Translation service layer
|
||
│ ├── __init__.py
|
||
│ └── translation_service.py # Pluggable translation backend
|
||
│
|
||
├── translators/ # Document-specific translators
|
||
│ ├── __init__.py
|
||
│ ├── excel_translator.py # Excel (.xlsx) handler
|
||
│ ├── word_translator.py # Word (.docx) handler
|
||
│ ├── pptx_translator.py # PowerPoint (.pptx) handler
|
||
│ └── excel_advanced.py # Advanced Excel features
|
||
│
|
||
├── utils/ # Utility modules
|
||
│ ├── __init__.py
|
||
│ ├── file_handler.py # File operations
|
||
│ └── exceptions.py # Error handling
|
||
│
|
||
├── requirements.txt # Python dependencies
|
||
├── README.md # Full documentation
|
||
├── ARCHITECTURE.md # Technical architecture
|
||
└── DEPLOYMENT.md # Production deployment guide
|
||
```
|
||
|
||
## 🎯 Next Steps
|
||
|
||
### For Development
|
||
1. ✅ Run `start.ps1` to start the server
|
||
2. ✅ Test with `test_api.py`
|
||
3. ✅ Try translating sample documents
|
||
4. Read `ARCHITECTURE.md` for technical details
|
||
|
||
### For Production
|
||
1. Read `DEPLOYMENT.md` for production setup
|
||
2. Configure environment variables
|
||
3. Set up Docker container
|
||
4. Enable authentication and rate limiting
|
||
|
||
### For MCP Integration
|
||
1. Install MCP requirements: `pip install -r requirements-mcp.txt`
|
||
2. Review `mcp_server_example.py`
|
||
3. Configure MCP server in your AI assistant
|
||
|
||
## 📞 API Endpoints Reference
|
||
|
||
| Endpoint | Method | Description |
|
||
|----------|--------|-------------|
|
||
| `/` | GET | API information |
|
||
| `/health` | GET | Health check |
|
||
| `/languages` | GET | Supported languages |
|
||
| `/translate` | POST | Translate single document |
|
||
| `/translate-batch` | POST | Translate multiple documents |
|
||
| `/download/{filename}` | GET | Download translated file |
|
||
| `/cleanup/{filename}` | DELETE | Delete translated file |
|
||
|
||
## 💡 Tips & Best Practices
|
||
|
||
1. **File Size**: Keep files under 50MB for best performance
|
||
2. **Format Preservation**: More complex formatting = longer processing time
|
||
3. **Language Codes**: Use ISO 639-1 codes (2 letters)
|
||
4. **Cleanup**: Enable cleanup to save disk space
|
||
5. **Batch Translation**: Use batch endpoint for multiple files
|
||
|
||
## 🌟 Features Highlights
|
||
|
||
✨ **Zero Data Loss**: All formatting, colors, styles preserved
|
||
✨ **Formula Intelligence**: Translates text in formulas, keeps logic
|
||
✨ **Image Preservation**: Embedded media stays in exact positions
|
||
✨ **Smart Translation**: Auto-detects source language
|
||
✨ **MCP Ready**: Designed for AI assistant integration
|
||
|
||
## 📄 License
|
||
|
||
MIT License - Free to use and modify
|
||
|
||
## 🤝 Support
|
||
|
||
- **Documentation**: See `README.md` for full details
|
||
- **Issues**: Open an issue on the repository
|
||
- **Architecture**: Read `ARCHITECTURE.md` for technical depth
|
||
|
||
---
|
||
|
||
**Ready to translate? Run `.\start.ps1` and visit http://localhost:8000/docs** 🚀
|