Initial commit: Document Translation API with Excel, Word, PowerPoint support
This commit is contained in:
230
QUICKSTART.md
Normal file
230
QUICKSTART.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# 🚀 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** 🚀
|
||||
Reference in New Issue
Block a user