LibreTranslate Deployment and Usage Guide

1. Prerequisites

Before installing LibreTranslate, ensure you have:

• Python 3.8+ installed on your system
• pip (Python package manager)
• Git for cloning the repository
• At least 2GB RAM for running translation models
• Disk space for language models (varies by language, typically 200MB-1GB per language pair)

Optional but recommended:

• Docker and Docker Compose for containerized deployment
• Virtual environment tool (venv, conda, or virtualenv) for Python isolation

2. Installation

Method 1: Using pip (Recommended for most users)

# Install LibreTranslate globally
pip install libretranslate

# Or install in a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install libretranslate

Method 2: From Source

# Clone the repository
git clone https://github.com/LibreTranslate/LibreTranslate.git
cd LibreTranslate

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

Method 3: Using Docker

# Pull the official Docker image
docker pull libretranslate/libretranslate

# Or build from source
docker build -t libretranslate .

3. Configuration

LibreTranslate can be configured via command-line arguments or environment variables (prefixed with LT_).

Key Configuration Options

Example Configuration

Create a .env file:

LT_HOST=0.0.0.0
LT_PORT=8080
LT_CHAR_LIMIT=5000
LT_REQ_LIMIT=30
LT_API_KEYS=true
LT_LOAD_ONLY=en,es,fr,de

Or use command-line arguments:

libretranslate --host 0.0.0.0 --port 8080 --char-limit 5000 --req-limit 30 --api-keys --load-only en,es,fr,de

4. Build & Run

Running with pip installation

# Start the server with default settings
libretranslate

# Start with custom settings
libretranslate --host 0.0.0.0 --port 8080 --char-limit 5000

# Enable API keys
libretranslate --api-keys

Running from source

# Navigate to the project directory
cd LibreTranslate

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run the application
python -m libretranslate.main --host 0.0.0.0 --port 5000

Running with Docker

# Run with default settings
docker run -ti -p 5000:5000 libretranslate/libretranslate

# Run with custom settings
docker run -ti -p 8080:5000 \
  -e LT_HOST=0.0.0.0 \
  -e LT_PORT=5000 \
  -e LT_CHAR_LIMIT=5000 \
  libretranslate/libretranslate

# Mount a volume for persistent data
docker run -ti -p 5000:5000 \
  -v /path/to/data:/home/libretranslate/.local/share/argos-translate \
  libretranslate/libretranslate

Docker Compose Example

Create a docker-compose.yml file:

version: '3.8'

services:
  libretranslate:
    image: libretranslate/libretranslate
    container_name: libretranslate
    ports:
      - "5000:5000"
    environment:
      - LT_HOST=0.0.0.0
      - LT_PORT=5000
      - LT_CHAR_LIMIT=5000
      - LT_REQ_LIMIT=30
      - LT_LOAD_ONLY=en,es,fr,de
    volumes:
      - libretranslate_data:/home/libretranslate/.local/share/argos-translate
    restart: unless-stopped

volumes:
  libretranslate_data:

Run with:

docker-compose up -d

5. Deployment

Production Considerations

1. Reverse Proxy Setup: Use Nginx or Apache as a reverse proxy for SSL termination and load balancing:

   # Nginx configuration example
   server {
       listen 443 ssl;
       server_name translate.yourdomain.com;
       
       ssl_certificate /path/to/cert.pem;
       ssl_certificate_key /path/to/key.pem;
       
       location / {
           proxy_pass http://localhost:5000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }
   

2. Process Management: Use systemd for Linux deployments:

   # /etc/systemd/system/libretranslate.service
   [Unit]
   Description=LibreTranslate Service
   After=network.target
   
   [Service]
   Type=simple
   User=libretranslate
   WorkingDirectory=/opt/libretranslate
   Environment="PATH=/opt/libretranslate/venv/bin"
   ExecStart=/opt/libretranslate/venv/bin/libretranslate --host 0.0.0.0 --port 5000 --req-limit 30
   Restart=always
   
   [Install]
   WantedBy=multi-user.target
   

3. Container Orchestration: For scalable deployments:

   • Kubernetes: Deploy with Helm charts or Kubernetes manifests
   • Docker Swarm: Use Docker stack for multi-host deployments
   • Cloud Services: AWS ECS, Google Cloud Run, or Azure Container Instances

Recommended Deployment Platforms

• Self-hosted servers: Ubuntu/Debian with systemd
• Cloud VPS: DigitalOcean, Linode, AWS EC2, Google Compute Engine
• Container platforms: Docker Swarm, Kubernetes (k3s for lightweight deployments)
• Serverless: Not recommended due to model loading times and persistent storage needs

Scaling Considerations

• Memory: Each language model requires 200MB-1GB RAM. Plan memory accordingly.
• CPU: Translation is CPU-intensive. Consider CPU-optimized instances for production.
• Storage: Language models are stored locally. Use SSD storage for better performance.
• Caching: Implement Redis or similar caching for frequent translations.

6. Troubleshooting

Common Issues and Solutions

Issue: "No language models available"

# Download language models
libretranslate --install-langs en,es

# Or manually install via argostranslate
python -c "import argostranslate; argostranslate.update_package_index(); available_packages = argostranslate.get_available_packages(); package_to_install = next(filter(lambda x: x.from_code == 'en' and x.to_code == 'es', available_packages)); argostranslate.install_from_path(package_to_install.download())"

Issue: Server won't start on port 5000

# Check if port is already in use
sudo lsof -i :5000

# Use a different port
libretranslate --port 8080

# Or run as root/sudo if binding to privileged port (<1024)
sudo libretranslate --port 80

Issue: Memory errors with multiple languages

# Reduce number of loaded languages
libretranslate --load-only en,es,fr

# Increase swap space (Linux)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Issue: Slow translation performance

# Limit loaded languages to only needed ones
libretranslate --load-only en,es

# Use faster hardware (CPU optimization helps)
# Consider enabling hardware acceleration if available

Issue: Docker container exits immediately

# Check logs
docker logs <container_id>

# Run with interactive mode to see errors
docker run -it --rm libretranslate/libretranslate

# Ensure sufficient memory allocation
docker run -it --rm -m 2g libretranslate/libretranslate

Issue: API key authentication problems

# Enable API keys
libretranslate --api-keys

# Generate a new API key (if using database backend)
# Access the /keys endpoint to manage keys

# Check API key in request
curl -X POST "http://localhost:5000/translate" \
  -H "Content-Type: application/json" \
  -d '{"q":"Hello","source":"en","target":"es","api_key":"your_api_key"}'

Debug Mode

For detailed debugging, enable verbose logging:

# Set debug environment variable
export LT_DEBUG=true
libretranslate

# Or check application logs
tail -f /var/log/libretranslate.log

Getting Help

• Check the API Documentation
• Visit the Community Forum
• Review GitHub Issues
• Join discussions on Bluesky