Initial commit: Document Translation API with Excel, Word, PowerPoint support

2025-11-30 10:48:58 +01:00
commit 793d94c93e
41 changed files with 3617 additions and 0 deletions
--- a/QUICK_REFERENCE.md
+++ b/QUICK_REFERENCE.md
@@ -0,0 +1,214 @@
+# 📋 QUICK REFERENCE CARD
+
+## 🚀 Start Server
+```powershell
+.\start.ps1
+```
+Or manually:
+```powershell
+.\venv\Scripts\Activate.ps1
+python main.py
+```
+
+## 🌐 API URLs
+| Endpoint | URL |
+|----------|-----|
+| Swagger Docs | http://localhost:8000/docs |
+| ReDoc | http://localhost:8000/redoc |
+| Health Check | http://localhost:8000/health |
+| Languages | http://localhost:8000/languages |
+
+## 📤 Translate Document
+
+### PowerShell
+```powershell
+$file = Get-Item "document.xlsx"
+Invoke-RestMethod -Uri "http://localhost:8000/translate" `
+  -Method Post `
+  -Form @{file=$file; target_language="es"} `
+  -OutFile "translated.xlsx"
+```
+
+### Python
+```python
+import requests
+with open('doc.xlsx', 'rb') as f:
+    r = requests.post('http://localhost:8000/translate',
+                      files={'file': f},
+                      data={'target_language': 'es'})
+with open('translated.xlsx', 'wb') as out:
+    out.write(r.content)
+```
+
+### cURL
+```bash
+curl -X POST "http://localhost:8000/translate" \
+  -F "file=@document.xlsx" \
+  -F "target_language=es" \
+  --output translated.xlsx
+```
+
+## 🌍 Language Codes
+| 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 Formats
+- `.xlsx` - Excel (formulas, formatting, images)
+- `.docx` - Word (styles, tables, images)
+- `.pptx` - PowerPoint (layouts, animations, media)
+
+## ⚙️ Configuration (.env)
+```env
+TRANSLATION_SERVICE=google    # or: deepl, libre
+DEEPL_API_KEY=your_key       # if using DeepL
+MAX_FILE_SIZE_MB=50          # max upload size
+```
+
+## 📁 Project Structure
+```
+Translate/
+├── main.py              # API application
+├── config.py            # Configuration
+├── start.ps1            # Startup script
+│
+├── services/            # Translation services
+│   └── translation_service.py
+│
+├── translators/         # Format handlers
+│   ├── excel_translator.py
+│   ├── word_translator.py
+│   └── pptx_translator.py
+│
+├── utils/               # Utilities
+│   ├── file_handler.py
+│   └── exceptions.py
+│
+└── [docs]/              # Documentation
+    ├── README.md
+    ├── QUICKSTART.md
+    ├── ARCHITECTURE.md
+    └── DEPLOYMENT.md
+```
+
+## 🧪 Testing
+```powershell
+# Test API
+python test_api.py
+
+# Run examples
+python examples.py
+```
+
+## 🔧 Troubleshooting
+
+### Port in use
+```python
+# Edit main.py line 307:
+uvicorn.run(app, host="0.0.0.0", port=8001)
+```
+
+### Module not found
+```powershell
+.\venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+```
+
+### Execution policy (Windows)
+```powershell
+Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+## 📊 API Response Headers
+```
+X-Original-Filename: document.xlsx
+X-File-Size-MB: 2.5
+X-Target-Language: es
+```
+
+## 🎯 Common Tasks
+
+### Check API Status
+```powershell
+curl http://localhost:8000/health
+```
+
+### List Languages
+```powershell
+curl http://localhost:8000/languages
+```
+
+### Download File
+```powershell
+curl http://localhost:8000/download/filename.xlsx -o local.xlsx
+```
+
+### Cleanup File
+```powershell
+curl -X DELETE http://localhost:8000/cleanup/filename.xlsx
+```
+
+## 💡 Tips
+- Use `auto` for source language auto-detection
+- Set `cleanup=true` to delete uploads automatically
+- Max file size: 50MB (configurable)
+- Processing time: ~1-5 seconds per document
+
+## 📚 Documentation Files
+| File | Purpose |
+|------|---------|
+| `QUICKSTART.md` | 5-minute setup guide |
+| `README.md` | Complete documentation |
+| `ARCHITECTURE.md` | Technical design |
+| `DEPLOYMENT.md` | Production setup |
+| `CHECKLIST.md` | Feature checklist |
+| `PROJECT_SUMMARY.md` | Project overview |
+
+## 🔌 MCP Integration
+```powershell
+# Install MCP dependencies
+pip install -r requirements-mcp.txt
+
+# Run MCP server
+python mcp_server_example.py
+```
+
+## 📞 Quick Commands
+
+| Command | Purpose |
+|---------|---------|
+| `.\start.ps1` | Start API server |
+| `python test_api.py` | Test API |
+| `python examples.py` | Run examples |
+| `pip install -r requirements.txt` | Install deps |
+
+## 🎨 Format Preservation
+
+### Excel
+✅ Formulas, merged cells, fonts, colors, borders, images
+
+### Word
+✅ Styles, headings, lists, tables, headers/footers, images
+
+### PowerPoint
+✅ Layouts, animations, transitions, media, positioning
+
+---
+
+## 🚀 QUICK START
+```powershell
+cd d:\Translate
+.\start.ps1
+# Visit: http://localhost:8000/docs
+```
+
+---
+
+**Print this card for quick reference! 📋**