LibreTranslate

What it's good for#

Online translators are handy, but everything you paste into them goes to someone else's servers: letters, messages, work documents. LibreTranslate does the translating on your own machine, using open language models it downloads once. The results are good for getting the gist of something and for everyday text, though not up to a professional translator.

There are two ways to use it. Its web page is a simple two-box translator, with a second tab for translating whole files. Its API lets scripts and other apps ask for translations, which is how it sits behind Mastodon's Translate button, and how it could answer translation searches in SearXNG.

Choosing languages#

The install asks which languages to load, because each one costs memory and a download. The four offered to start with are English, Spanish, French and German, which settles at about 1.1 GB of memory once they've all been used. English and Spanish alone is about 0.6 GB; adding Italian, Portuguese, Dutch and Polish brings it to about 1.8 GB.

On the first start LibreTranslate downloads a model for each pair of languages, roughly 100 MB each, and the install waits for it, showing each download as it goes. On a slow connection that can take several minutes, and LibrePortal gives it up to half an hour before it stops waiting.

To change the list later, edit Languages on the Config tab (for example en,sv for English and Swedish) and press Update Configuration. The codes are the usual two-letter ones, separated by commas, and you need at least two. A new language is downloaded on the next start. A language you take out has its models deleted, so it stops using memory and disk.

Using the web page#

Open it with the Web Interface button. There's no sign-in: anyone who can open the page can translate with it. That's why LibrePortal installs it private, reachable only from your trusted places and your devices on the LibrePortal VPN. Keep it that way unless you mean to run a translator for strangers.

Choose the languages at the top, or let it detect the source language, and type. The files tab takes whole documents, such as text, Word, OpenDocument, PowerPoint, EPUB and HTML files, and gives you back a translated copy in the same format.

With a domain and Traefik, the page is also at translate.<your domain>.

API keys for scripts and other apps#

With Require API Keys on (it is to start with), a script or app is expected to send a key when it uses the API. A key gives each one its own allowance of requests. Keys are made on the app's Tools tab:

The card only ever holds the most recent key, so copy each one before you make the next. List API Keys shows every key by its first eight characters, with its limit, which is enough to tell them apart. Delete API Key takes that start and stops the key working within half a minute; anything still using it can no longer translate. Deleting the newest key takes it off the card too.

A key goes in the body of the request. From a terminal on your network it looks like this, with your own server address, port and key:

curl -s http://192.168.1.50:5210/translate \
  -H 'Content-Type: application/json' \
  -d '{"q": "Where is the station?", "source": "en", "target": "fr", "api_key": "YOUR-KEY"}'

The answer is a little JSON with translatedText in it. Use "source": "auto" to let it work out the language itself. The same API has /languages, which lists the languages you've loaded, and /detect.

Browser extensions and desktop apps that let you choose a LibreTranslate server can use yours in the same way: give them the address you open it at and, if they ask, a key.

Works with#

LibreTranslate's Works with list shows Mastodon and SearXNG, and whether each one is using this server yet. LibrePortal doesn't connect either for you.

Mastodon has settings for it. On Mastodon's Config tab, set Translation Server to http://libretranslate-service:5000 and Translation API Key to a key from Create API Key, then press Update Configuration. Posts in other languages then get a Translate button. The Mastodon page has the details.

SearXNG can use LibreTranslate for searches like en-fr hello, but there's no setting for it in LibrePortal yet.

To check: document how to point SearXNG's libretranslate engine at LibreTranslate through LibrePortal once there is a supported way that doesn't mean hand-editing its settings.yml

Good to know#

• Memory grows as you use it. It starts near 150 MB and loads each language pair the first time someone translates with it, up to the figures above. Workers (under Advanced) lets it handle more requests at once, but each worker holds its own copy of the models, so memory goes up with it. Leave it at 1 for a household.
• Backups skip the models. They're a download, not your data, so backups keep only the API keys and LibreTranslate fetches the models again after a restore.
• Keys made with 0.4.6 or earlier were printed in full in the task output. If that matters to you, delete them with Delete API Key and make new ones, which go to the card instead.
• Updates are automatic, with a backup first.
• One per server.