# 🚀 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** 🚀