Paulo H. R. Pinheiro | Levantando um serviço local de tradução Com libretranslate

A partir de pequenos textos em espanhol, que retirei de um grande relatório, para o projeto TumbaElBloqueo, precisei traduzí-los para vários idiomas (cinco). Pesquisei opções, e as com excelente reputação, são muito caras. E como pretendia automatizar essa tarefa, que será recorrente, me deparei com o LibreTranslate, pois além de ser uma ferramenta especializada, é OpenSouce.

Muito fácil instalar o pacote Python e usar, e até mesmo disponibilizar uma API e um site web local, mas eu queria um serviço permanente em minha máquina.

Costumo usar ASDF para gerir versões de linguagens de programação, mas, até por “conselho” recebido da LLM, usei o Python do sistema mesmo. Mas deixei o uso com ASDF explicado para referência.

Aqui segue uma espécie de logbook da minha instalação em um Fedora.

Um pequeno exemplo de uso

Aqui um exemplo bem simples de como usar (não usei requests) pra não complicar.

import json
from urllib.request import Request, urlopen

API_URL = "http://localhost:5000/translate"

TARGETS = {
    "pt": "Português",
    "en": "English",
    "fr": "Français",
    "it": "Italiano",
    "de": "Deutsch",
}


def translate(text, source, target):
    payload = json.dumps({
        "q": text,
        "source": source,
        "target": target,
    }).encode("utf-8")

    request = Request(
        API_URL,
        data=payload,
        headers={"Content-Type": "application/json"},
        method="POST",
    )

    with urlopen(request, timeout=30) as response:
        result = json.load(response)

    return result["translatedText"]


if __name__ == "__main__":
    text = "Hola, ¿cómo estás?"

    for code, language in TARGETS.items():
        translated = translate(text, source="es", target=code)
        print(f"{language:10} ({code}): {translated}")

Como saída, tem-se:

paulo@null ~> python t.py 
Português  (pt): Olá, como estás?
English    (en): Hey, how are you?
Français   (fr): Ça va ?
Italiano   (it): Ehi, come stai?
Deutsch    (de): Hey, wie geht es dir?

Estrutura de diretórios

/data/libtranslate/
├── venv/                          ← virtualenv isolado
│   ├── bin/
│   │   ├── python3.14 → /usr/bin/python3.14
│   │   ├── libretranslate         ← entrypoint
│   │   └── pip
│   └── lib/python3.14/site-packages/
├── .local/
│   └── share/argos-translate/packages/  ← modelos de tradução (~6,5 GB)
└── .config/
    └── argos-translate/

Instalação

1. Criar diretório

sudo mkdir -p /data/libtranslate

2. Ativar versão do Python com ASDF

asdf install python 3.14.6t
asdf set -u python 3.14.6t

3. Criar virtualenv apontando para o Python do sistema

O Python do ASDF fica em /home/$USER/.asdf/installs/python/ (inacessível para outros usuários). Por isso o venv é criado com o binário do sistema (/usr/bin/python3.14), garantindo que o usuário do serviço consiga executá-lo.

/usr/bin/python3.14 -m venv /data/libtranslate/venv

4. Instalar o LibreTranslate

/data/libtranslate/venv/bin/pip install libretranslate

Na primeira execução, o LibreTranslate baixa automaticamente os modelos de tradução (~6,5 GB). Os modelos ficam em ~/.local/share/argos-translate/packages/ (no caso, /data/libtranslate/.local/...).

5. Criar usuário dedicado

sudo useradd -r -s /usr/sbin/nologin -d /data/libtranslate libretranslate

6. Ajustar permissões

sudo chown -R libretranslate: /data/libtranslate

Configuração do serviço

7. Criar unit systemd

Arquivo: /etc/systemd/system/libretranslate.service

[Unit]
Description=LibreTranslate API
After=network.target

[Service]
Type=simple
User=libretranslate
Group=libretranslate
WorkingDirectory=/data/libtranslate
ExecStart=/data/libtranslate/venv/bin/libretranslate --host 127.0.0.1 --port 5000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

8. Corrigir contexto SELinux

Em sistemas com SELinux em modo enforcing, o contexto default_t do diretório /data/ impede a execução pelo systemd. É necessário ajustar o contexto para bin_t:

sudo chcon -t bin_t /data/libtranslate/venv/bin/libretranslate

9. Ativar e iniciar

sudo systemctl daemon-reload
sudo systemctl enable libretranslate
sudo systemctl start  libretranslate

Gerenciamento

Ação	Comando
Status	`sudo systemctl status libretranslate`
Iniciar	`sudo systemctl start libretranslate`
Parar	`sudo systemctl stop libretranslate`
Reiniciar	`sudo systemctl restart libretranslate`
Logs	`sudo journalctl -u libretranslate -f`
Habilitar no boot	`sudo systemctl enable libretranslate`
Desabilitar no boot	`sudo systemctl disable libretranslate`

Teste

# Verificar se a API responde
curl -X POST http://localhost:5000/translate \
  -d "q=Hello world&source=en&target=pt"

# Resposta esperada:
# {"translatedText":"Olá, mundo"}

Atualização do Python (ASDF)

Instalar nova versão:

asdf install python 3.14.7t     # exemplo
asdf set -u python 3.14.7t

Verificar se o novo Python está disponível em /usr/bin/python3.14. Se não, copiar:

sudo cp "$(asdf where python)/bin/python3.14" /usr/local/bin/

Recriar o virtualenv:

sudo systemctl stop libretranslate
sudo rm -rf /data/libtranslate/venv
/usr/bin/python3.14 -m venv /data/libtranslate/venv      # ou /usr/local/bin/python3.14
/data/libtranslate/venv/bin/pip install libretranslate
sudo chcon -t bin_t /data/libtranslate/venv/bin/libretranslate
sudo systemctl start libretranslate

Atualização do LibreTranslate

sudo systemctl stop libretranslate
sudo -u libretranslate /data/libtranslate/venv/bin/pip install --upgrade libretranslate
sudo systemctl start libretranslate

Para atualizar os modelos de tradução:

sudo -u libretranslate /data/libtranslate/venv/bin/pip install --upgrade argos-translate-lt argos-translate-files

Solução de problemas

Erro `203/EXEC` (Permission denied)

Causa: SELinux bloqueando a execução do binário (contexto default_t em vez de bin_t).

Solução:

sudo chcon -t bin_t /data/libtranslate/venv/bin/libretranslate
sudo systemctl restart libretranslate

Para verificar:

ls -Z /data/libtranslate/venv/bin/libretranslate
# Deve mostrar: system_u:object_r:bin_t:s0

Erro `203/EXEC` — python3.14 inacessível

Causa: o python3.14 do venv é um symlink para /home/$USER/.asdf/... (permissão 700).

Solução: recriar o venv com o Python do sistema:

sudo rm -rf /data/libtranslate/venv
/usr/bin/python3.14 -m venv /data/libtranslate/venv
/data/libtranslate/venv/bin/pip install libretranslate

Serviço não escuta na porta após iniciar

Causa: o LibreTranslate está baixando ou carregando modelos na primeira execução. Pode levar de 1 a 5 minutos e consumir vários GB de RAM.

Verificação:

sudo journalctl -u libretranslate -f

Modelos de tradução não aparecem

O diretório de modelos é relativo ao home do usuário do serviço:

sudo ls -la /data/libtranslate/.local/share/argos-translate/packages/

$ Levantando um serviço local de tradução Com libretranslate