Deployment guide

LibreTranslate on a VPS: Your Private Translation API

Deploy on a VPS Cloud →

Tutorial

Self-hosting

LibreTranslate on a VPS: Your Private Translation API

Translating product pages, notifications or support messages through an online API means sending every text to a third party and paying per character. LibreTranslate does the same job on your own server: an open-source machine translation JSON API built on the offline models of Argos Translate. This guide installs it on a VPS with Docker Compose, loads Arabic, French, English and Spanish, locks the instance with API keys, publishes it over HTTPS behind nginx and calls it from an application.

7 min read4 steps
Contents· What LibreTranslate does1/13
  1. 01What LibreTranslate does
  2. 02What LibreTranslate brings
  3. 03LibreTranslate versus online APIs
  4. 04Prerequisites
  5. 05Install LibreTranslate with Docker Compose
  6. 06Never publish an instance without keys
  7. 07Put LibreTranslate behind nginx over HTTPS
  8. 08Call the API from an application
  9. 09Manage API keys and limits
  10. 10Tune LibreTranslate for a small VPS
  11. 11What to know about quality
  12. 12Add languages, back up and update
  13. 13One-click install on ServOrbit

What LibreTranslate does

LibreTranslate exposes an HTTP API that receives a text, its source language and a target language, and returns the translation. The models are those of Argos Translate, a neural translation engine that works offline: once downloaded, they run on the VPS's CPU, with no GPU and no call to an external service.

The project is released under the AGPL-3.0 licence. It also provides a web interface to translate a text or a file by hand, language detection, and API key management with a request limit per key. On a VPS, it is the building block that lets a website, a SaaS or an internal tool speak several languages without depending on a vendor.

What LibreTranslate brings

  • A simple API — /translate, /detect and /languages, in JSON, callable from any language.
  • Arabic and French — together with English and Spanish, four languages loaded from the start, in every combination.
  • Language detection — an auto source for messages whose language you do not know.
  • File translation — txt, docx, odt, pptx, epub, html, srt and pdf.
  • API keys — one per application, each with its own requests-per-minute limit.
  • Confidentiality — texts stay on your server, and nothing is billed per character.

LibreTranslate versus online APIs

Scroll the table

LibreTranslateGoogle Cloud TranslationDeepL API
HostingYour VPSGoogle cloudDeepL cloud
Where texts goStay on the serverSent to the vendorSent to the vendor
BillingThe VPS onlyPer characterPer character
QualityFair, review advisedVery goodVery good
Source codeOpen (AGPL-3.0)ClosedClosed

Prerequisites

An Ubuntu 24.04 VPS with 2 GB of RAM and 2 vCPUs is enough for four languages and modest traffic; plan 4 GB if several applications translate at the same time. Allow about 750 MB of disk for the models of the four languages, then around a hundred megabytes per added pair.

You need Docker with the Compose plugin, nginx and certbot on the host, and a name (traduction.example.com in this guide) pointing to the VPS's IP.

Install LibreTranslate with Docker Compose

  1. Write the docker-compose.yml file

    In a dedicated folder (/opt/libretranslate), create this file. The port is published on the loopback interface only. LT_API_KEYS enables the key database, LT_UNDER_ATTACK refuses any request without a valid key, web interface included, and LT_LOAD_ONLY limits the download to the four useful languages.

    services:
      libretranslate:
        image: libretranslate/libretranslate:v1.9.6
        restart: unless-stopped
        ports:
          - "127.0.0.1:5000:5000"
        environment:
          LT_API_KEYS: "true"
          LT_UNDER_ATTACK: "true"
          LT_LOAD_ONLY: "en,fr,ar,es"
          LT_THREADS: "2"
        volumes:
          - lt-db:/app/db
          - lt-models:/home/libretranslate/.local
    
    volumes:
      lt-db:
      lt-models:
  2. Start and wait for the models

    On first start, LibreTranslate downloads the models before opening the port: follow the logs until the Listening at line.

    docker compose up -d
    docker compose logs -f libretranslate
  3. Create your first key

    The key database is created at startup. Add a key limited to 120 requests per minute; the command prints it only once.

    docker compose exec libretranslate ./venv/bin/ltmanage keys add 120
  4. Check that the key is required

    The first request, without a key, must be refused; the second returns translatedText.

    curl -s http://127.0.0.1:5000/translate -H "Content-Type: application/json" \
      -d '{"q":"Bonjour","source":"fr","target":"en"}'
    curl -s http://127.0.0.1:5000/translate -H "Content-Type: application/json" \
      -d '{"q":"Bonjour","source":"fr","target":"en","api_key":"YOUR_KEY"}'

Never publish an instance without keys

Without LT_API_KEYS and LT_UNDER_ATTACK, LibreTranslate translates for anyone who knows the address. An open instance is quickly found and used by bots: your CPU ends up working for them. Keep the port on 127.0.0.1 and let nginx alone face the Internet.

Put LibreTranslate behind nginx over HTTPS

Create a server block in /etc/nginx/sites-available/ and enable it. client_max_body_size sets the maximum size of a file sent for translation: without this line, nginx refuses any upload above 1 MB.

server {
    server_name traduction.example.com;
    client_max_body_size 20m;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}

Then check the configuration and request the certificate:

sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d traduction.example.com

Call the API from an application

Every request is a JSON POST with the text (q), the source language (source, or auto), the target language (target) and the key (api_key).

curl -s https://traduction.example.com/translate -H "Content-Type: application/json" \
  -d '{"q":"Your order has shipped.","source":"fr","target":"ar","api_key":"YOUR_KEY"}'

In Python, the same request takes a few lines:

import requests

r = requests.post(
    "https://traduction.example.com/translate",
    json={"q": "Your invoice is ready.", "source": "auto", "target": "es", "api_key": "YOUR_KEY"},
    timeout=30,
)
print(r.json()["translatedText"])

/languages lists the available pairs, /detect returns the language of a text with a confidence score, and /translate_file translates a file sent as multipart.

Manage API keys and limits

Create one key per application or per customer: you can revoke one without touching the others, and each key carries its own requests-per-minute limit. From the application folder:

docker compose exec libretranslate ./venv/bin/ltmanage keys
docker compose exec libretranslate ./venv/bin/ltmanage keys add 60
docker compose exec libretranslate ./venv/bin/ltmanage keys remove <key>

An unknown key receives Invalid API key, a request without a key Please contact the server operator to get an API key. In the web interface, the key icon ("Set API Key") at the top of the page stores the key in the browser.

Tune LibreTranslate for a small VPS

Four environment variables are enough to fit the instance to the size of the server. LT_THREADS sets the number of translation processes: each one loads the models in memory, hence the value of 2 on a 2 GB VPS; raise it if you have RAM and several applications translating in parallel. LT_CHAR_LIMIT caps the length of a text per request, so that a single call cannot hold a process for minutes. LT_DISABLE_FILES_TRANSLATION turns off file translation if you do not use it, and LT_DISABLE_WEB_UI removes the web interface to keep only the API.

After each change in docker-compose.yml, restart with docker compose up -d: the container is recreated, and the volumes — so the keys and the models — are kept. Watch memory with docker stats during a day of real use before settling these values.

What to know about quality

Argos Translate models are much smaller than those of commercial services. Translation stays reliable for understanding a message, sorting tickets, producing a first draft or translating everyday content; it is less dependable on idioms, highly specialised vocabulary and long literary texts.

A simple rule: machine-translate what helps you understand, and have a person review what will be published under your name — sales pages, terms and conditions, marketing emails. Also test your own sentences in both directions before plugging in an application: quality varies from one language pair to another, and English often serves as a pivot between two languages that are not English.

Add languages, back up and update

To add a language, append its code (de, it, pt, tr…) to LT_LOAD_ONLY and restart with docker compose up -d: the missing models download at startup.

What to back up: the lt-db volume only, which holds the key database. The models in lt-models download again on their own, and LibreTranslate does not keep translated texts. To update, change the image tag in docker-compose.yml after reading the release notes, then:

docker compose pull
docker compose up -d

One-click install on ServOrbit

On a ServOrbit VPS, LibreTranslate installs from the Marketplace: the script deploys the official image with Arabic, French, English and Spanish, generates your API key, locks the instance against any request without a key and sets up nginx over HTTPS. The address is a subdomain of one of your domains or the VPS's free subdomain, certificate included, and the key is shown in your client area.

Share this articleservorbit.com/ma-en/blog/self-host-libretranslate-vps-translation-api