office_translator/QUICKSTART.md

🚀 Quick Start Guide - Document Translation API

Step-by-Step Setup (5 Minutes)

1️⃣ Open PowerShell in Project Directory

cd d:\Translate

2️⃣ Run the Startup Script

.\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:

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)

$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

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:

# 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:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Issue: "Module not found"

Solution:

.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

Issue: "Port 8000 already in use"

Solution: Edit main.py line 307:

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:

   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 🚀