README.md

---
title: Document Translator
emoji: 📄
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
license: mit
---

# 📄 Document Translator - Hugging Face Space

A powerful document translation service that converts PDF and DOCX files using AI models from OpenRouter. Built with FastAPI and a simple HTML interface (no Gradio dependency).

## ✨ Features

- **File Support**: Upload PDF or DOCX documents
- **AI Translation**: Uses Google Gemini 2.5 Pro model from OpenRouter
- **Format Preservation**: Maintains original document formatting
- **Batch Processing**: Translates documents paragraph by paragraph
- **Multiple Languages**: Support for 12+ languages including Arabic, English, Spanish, French, German, etc.
- **Download Options**: Get both original and translated files
- **Translation Reports**: Detailed statistics on processed content

## 🔧 Fixed Issues

### Docker Build Permissions
The original Docker build was failing due to permission issues when creating directories as a non-root user. This has been fixed by:
- Creating directories before switching to non-root user
- Properly setting ownership of the `/app` directory
- Simplified Dockerfile structure for better reliability

### Python Dependencies
- Removed conflicting `pathlib` dependency (built into Python 3.11)
- Updated requirements.txt with compatible versions
- Added proper Python path handling in main.py

## 🚀 Quick Start

### Environment Variables

Set your OpenRouter API key:
```bash
export OPENROUTER_API_KEY="your_api_key_here"
```

### Local Development

1. **Quick Setup** (recommended):
   ```bash
   python setup.py
   ```

2. **Manual Setup**:
   ```bash
   # Set your API key
   export OPENROUTER_API_KEY="your_key_here"
   
   # Install dependencies
   pip install -r requirements.txt
   
   # Run the app
   python app.py
   ```

### Docker Deployment

1. **Build the Image**:
   ```bash
   docker build -t document-translator .
   ```

2. **Run the Container**:
   ```bash
   docker run -p 7860:7860 -e OPENROUTER_API_KEY="your_api_key" document-translator
   ```

### Hugging Face Spaces Deployment

1. **Create a new Space** on Hugging Face
2. **Upload all files** from this repository
3. **Set the environment variable**:
   - Go to Settings → Repository secrets
   - Add `OPENROUTER_API_KEY` with your API key
4. **Your Space will be automatically built and deployed**

## 📁 Project Structure

```
.
├── app/
│   └── main.py              # FastAPI backend application
├── web/
│   ├── index.html           # Frontend interface
│   ├── style.css            # Styling
│   └── app.js              # Frontend logic
├── translator.py            # Translation logic and OpenRouter integration
├── Dockerfile              # Container configuration
├── requirements.txt         # Python dependencies
└── README.md               # This file
```

## 🔧 How It Works

### Translation Process

1. **File Upload**: User uploads PDF or DOCX file through web interface
2. **Format Detection**: System identifies file type and validates
3. **Conversion** (if needed): PDF files are converted to DOCX using LibreOffice
4. **Text Extraction**: Document content is extracted paragraph by paragraph
5. **AI Translation**: Each paragraph is sent to OpenRouter API for translation
6. **Document Reconstruction**: Translated text replaces original while preserving formatting
7. **Final Conversion**: If original was PDF, translated DOCX is converted back to PDF
8. **Download**: User receives both original and translated files plus translation report

### Translation Model

The application uses **Google Gemini 2.5 Pro** (`google/gemini-2.5-pro-exp-03-25`) as the default translation model through OpenRouter. This model provides:
- High-quality translation accuracy
- Support for multiple languages
- Advanced context understanding
- Optimized performance for document translation

### Supported Languages

- **Auto-detect** source language
- **Target languages**: English, Arabic, Spanish, French, German, Italian, Portuguese, Russian, Japanese, Korean, Chinese, Hindi

## 🔑 OpenRouter Setup

1. **Sign up** at [OpenRouter](https://openrouter.ai)
2. **Get your API key** from the dashboard
3. **Add credits** to your account for model usage
4. **Set the environment variable** `OPENROUTER_API_KEY`

## 📊 API Endpoints

### GET `/`
Serves the main HTML interface

### GET `/models`
Returns available translation models

### POST `/translate`
Translates a document
- **file**: PDF or DOCX file
- **model**: Model ID from OpenRouter
- **source_language**: Source language code (default: "auto")
- **target_language**: Target language code (default: "en")

### GET `/download/{file_path}`
Downloads processed files

### GET `/health`
Health check endpoint

## 🔒 Security & Limits

- **File size limit**: 50MB maximum
- **Supported formats**: PDF, DOCX only
- **Rate limiting**: Built-in delays to respect API limits
- **File cleanup**: Temporary files are automatically removed
- **Error handling**: Comprehensive error handling and user feedback

## 🛠 Development

### Adding New Languages

Edit the language options in `web/index.html` and ensure the language codes are supported by your chosen translation models.

### Custom Models

Add new models in the `_get_default_models()` method in `translator.py` or they will be automatically fetched from OpenRouter.

### Styling

Modify `web/style.css` to customize the appearance. The current theme uses a gradient background with a clean, modern interface.

## 📝 License

This project is open source and available under the MIT License.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📞 Support

For issues and questions:
1. Check the application logs for error details
2. Verify your OpenRouter API key is valid
3. Ensure LibreOffice is properly installed
4. Check network connectivity for API calls

## 🔄 Version History

- **v1.0.0**: Initial release with PDF/DOCX support, OpenRouter integration, and web interface