README.md

metadata

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:

export OPENROUTER_API_KEY="your_api_key_here"

Local Development

1. Quick Setup (recommended):

   python setup.py
   

2. Manual Setup:

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

   docker build -t document-translator .
   

2. Run the Container:

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