Deploying LibreTranslate

Introduction

LibreTranslate is a free, open-source machine translation API that you can self-host to translate text between languages without relying on proprietary services like Google Translate or DeepL. Built on the Argos Translate library, LibreTranslate provides accurate neural machine translation while keeping your data completely private.

The application offers a simple REST API that can be integrated into applications, websites, and workflows, along with a user-friendly web interface for interactive translation. LibreTranslate supports dozens of languages and can be extended with additional language pairs as the community develops new models.

Key highlights of LibreTranslate:

• Privacy-Focused: All translation happens on your server; no data leaves your infrastructure
• REST API: Simple HTTP API for easy integration with applications
• Web Interface: Clean, user-friendly interface for interactive translations
• Language Detection: Automatic source language detection
• Multiple Languages: Supports 30+ languages with community-contributed models
• No API Keys Required: Use without registration or authentication (optional)
• Rate Limiting: Configurable limits to prevent abuse
• Docker Ready: Official Docker images for easy deployment
• Offline Operation: Works completely offline after language models are downloaded
• Open Source: AGPLv3 licensed with active development

This guide walks through deploying LibreTranslate on Klutch.sh using Docker, configuring language models, and optimizing for production use.

Why Deploy LibreTranslate on Klutch.sh

Deploying LibreTranslate on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds LibreTranslate. Push to GitHub, and your translation service deploys automatically.

Persistent Storage: Attach persistent volumes for downloaded language models. Models survive container restarts without re-downloading.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure API access from anywhere.

GitHub Integration: Connect your repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Translation requires significant CPU/memory. Allocate resources based on expected load.

Environment Variable Management: Configure API keys and limits securely through environment variables.

Custom Domains: Assign a custom domain for your translation API endpoint.

Always-On Availability: Your translation service remains available 24/7.

Prerequisites

Before deploying LibreTranslate on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• Sufficient storage for language models (2-4 GB per language pair)
• (Optional) A custom domain for your API

Understanding LibreTranslate Architecture

LibreTranslate consists of:

Flask Web Server: Python Flask application serving the API and web interface.

Argos Translate: The underlying neural machine translation engine using OpenNMT.

Language Models: Downloaded packages containing translation models for language pairs.

SQLite Database: Optional database for API key management and request logging.

Cache Layer: In-memory caching for frequently translated phrases.

Preparing Your Repository

Repository Structure

libretranslate-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

FROM libretranslate/libretranslate:latest

# Environment configuration
ENV LT_HOST=0.0.0.0
ENV LT_PORT=5000
ENV LT_CHAR_LIMIT=5000
ENV LT_REQ_LIMIT=100
ENV LT_BATCH_LIMIT=10
ENV LT_GA_ID=
ENV LT_FRONTEND_LANGUAGE_SOURCE=auto
ENV LT_FRONTEND_LANGUAGE_TARGET=en
ENV LT_SUGGESTIONS=false
ENV LT_DISABLE_WEB_UI=false
ENV LT_UPDATE_MODELS=true

# Create data directory for models
RUN mkdir -p /home/libretranslate/.local/share/argos-translate

# Expose the API port
EXPOSE 5000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
  CMD curl -f http://localhost:5000/languages || exit 1

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
LT_HOST	No	0.0.0.0	Server binding address
LT_PORT	No	5000	API server port
LT_CHAR_LIMIT	No	5000	Maximum characters per request
LT_REQ_LIMIT	No	100	Requests per minute limit
LT_BATCH_LIMIT	No	10	Maximum batch translation size
LT_LOAD_ONLY	No	-	Comma-separated list of language codes to load
LT_API_KEYS	No	false	Enable API key requirement
LT_DISABLE_WEB_UI	No	false	Disable the web interface
LT_UPDATE_MODELS	No	false	Auto-update models on startup

Deploying LibreTranslate on Klutch.sh

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial LibreTranslate deployment configuration"
git remote add origin https://github.com/yourusername/libretranslate-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “libretranslate” or “translation”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your LibreTranslate repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 5000 (LibreTranslate’s default port)

Set Environment Variables

Add the following:

Variable	Value
LT_HOST	0.0.0.0
LT_CHAR_LIMIT	5000 (adjust as needed)
LT_REQ_LIMIT	100 (adjust based on usage)
LT_LOAD_ONLY	en,es,fr,de (optional: limit languages)

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/home/libretranslate/.local/share/argos-translate	20 GB	Language models storage

Deploy Your Application

Click Deploy to start the build process. The first deployment will download language models, which may take several minutes.

Access LibreTranslate

Once deployment completes, access the web interface at https://your-app.klutch.sh or use the API at https://your-app.klutch.sh/translate.

Using the API

Translation Endpoint

Translate text using a POST request:

curl -X POST "https://your-app.klutch.sh/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Hello, world!",
    "source": "en",
    "target": "es"
  }'

Response:

{
  "translatedText": "Hola, mundo!"
}

Auto-Detection

Let LibreTranslate detect the source language:

curl -X POST "https://your-app.klutch.sh/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Bonjour le monde",
    "source": "auto",
    "target": "en"
  }'

Language Detection

Detect the language of text:

curl -X POST "https://your-app.klutch.sh/detect" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Ciao mondo"
  }'

Available Languages

List supported languages:

curl "https://your-app.klutch.sh/languages"

Configuration Options

Limiting Languages

Load only specific language pairs to reduce memory usage:

ENV LT_LOAD_ONLY=en,es,fr,de

Enabling API Keys

Require authentication for API access:

1. Set LT_API_KEYS=true
2. Generate API keys through the admin interface
3. Include keys in requests via api_key parameter

Customizing Rate Limits

Adjust limits based on your needs:

ENV LT_CHAR_LIMIT=10000
ENV LT_REQ_LIMIT=200
ENV LT_REQ_LIMIT_STORAGE=redis://localhost:6379

Production Best Practices

Security Recommendations

• Enable API keys for production deployments
• Configure rate limiting to prevent abuse
• Use HTTPS for all API requests
• Monitor for unusual usage patterns

Performance Optimization

• Load only the languages you need
• Allocate sufficient CPU and memory (4GB+ recommended)
• Use the --threads option for parallel processing
• Consider GPU acceleration for high-volume deployments

Scaling Considerations

• Each language pair requires 2-4 GB of storage
• Translation is CPU-intensive; scale resources accordingly
• Consider multiple instances behind a load balancer for high traffic

Backup Strategy

1. Back up the language models directory
2. Save any custom configurations
3. Export API keys if using authentication

Troubleshooting

Slow Translation

• Check CPU allocation and increase if needed
• Limit loaded languages to reduce memory pressure
• Enable caching for repeated translations

Language Not Available

• Verify the language is supported by Argos Translate
• Check that models were downloaded successfully
• Review logs for download errors

Out of Memory

• Reduce the number of loaded languages
• Increase memory allocation
• Restart the container to free memory

API Errors

• Verify request format matches the documentation
• Check character limits
• Review rate limiting settings

Additional Resources

• Official LibreTranslate Website
• LibreTranslate GitHub Repository
• LibreTranslate API Documentation
• Argos Translate
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying LibreTranslate on Klutch.sh gives you a private, self-hosted translation API with automatic builds and secure HTTPS access. Unlike cloud translation services, your text never leaves your infrastructure, making it ideal for sensitive documents and privacy-conscious applications.

With a simple REST API, web interface, and support for dozens of languages, LibreTranslate provides enterprise-grade translation capabilities without per-character fees or data privacy concerns.