Guía de despliegue

LibreTranslate en un VPS: su API de traducción privada

Desplegar en un VPS Cloud →

LibreTranslate en un VPS: su API de traducción privada

Traducir fichas de producto, notificaciones o mensajes de soporte con una API en línea significa enviar cada texto a un tercero y pagar por carácter. LibreTranslate hace el mismo trabajo en su propio servidor: una API JSON de traducción automática, de código abierto, construida sobre los modelos sin conexión de Argos Translate. Esta guía la instala en un VPS con Docker Compose, carga árabe, francés, inglés y español, cierra la instancia con claves de API, la publica en HTTPS detrás de nginx y la llama desde una aplicación.

7 min de lectura4 pasos
Contenido· Qué hace LibreTranslate1/13
  1. 01Qué hace LibreTranslate
  2. 02Lo que aporta LibreTranslate
  3. 03LibreTranslate frente a las API en línea
  4. 04Requisitos previos
  5. 05Instalar LibreTranslate con Docker Compose
  6. 06No publique nunca una instancia sin claves
  7. 07Poner LibreTranslate detrás de nginx en HTTPS
  8. 08Llamar a la API desde una aplicación
  9. 09Gestionar las claves de API y los límites
  10. 10Ajustar LibreTranslate para un VPS pequeño
  11. 11Lo que hay que saber sobre la calidad
  12. 12Añadir idiomas, hacer copias y actualizar
  13. 13Instalación en un clic en ServOrbit

Qué hace LibreTranslate

LibreTranslate expone una API HTTP que recibe un texto, su idioma de origen y un idioma de destino, y devuelve la traducción. Los modelos son los de Argos Translate, un motor de traducción neuronal que funciona sin conexión: una vez descargados, se ejecutan en la CPU del VPS, sin tarjeta gráfica y sin llamadas a un servicio externo.

El proyecto se publica con licencia AGPL-3.0. También ofrece una interfaz web para traducir a mano un texto o un archivo, detección de idioma y gestión de claves de API con un límite de solicitudes por clave. En un VPS, es la pieza que permite a un sitio, a un SaaS o a una herramienta interna hablar varios idiomas sin depender de un proveedor.

Lo que aporta LibreTranslate

  • Una API sencilla — /translate, /detect y /languages, en JSON, invocables desde cualquier lenguaje.
  • Árabe y francés — junto con inglés y español, cuatro idiomas cargados desde el principio, en todas las combinaciones.
  • Detección de idioma — un origen auto para los mensajes cuyo idioma desconoce.
  • Traducción de archivos — txt, docx, odt, pptx, epub, html, srt y pdf.
  • Claves de API — una por aplicación, cada una con su límite de solicitudes por minuto.
  • Confidencialidad — los textos se quedan en su servidor y no se factura nada por carácter.

LibreTranslate frente a las API en línea

Desplace la tabla

LibreTranslateGoogle Cloud TranslationDeepL API
AlojamientoSu VPSNube de GoogleNube de DeepL
Destino de los textosSe quedan en el servidorEnviados al proveedorEnviados al proveedor
FacturaciónSolo el VPSPor carácterPor carácter
CalidadCorrecta, revisión aconsejadaMuy buenaMuy buena
Código fuenteAbierto (AGPL-3.0)CerradoCerrado

Requisitos previos

Un VPS Ubuntu 24.04 con 2 GB de RAM y 2 vCPU basta para cuatro idiomas y un tráfico moderado; prevea 4 GB si varias aplicaciones traducen a la vez. Cuente unos 750 MB de disco para los modelos de los cuatro idiomas y luego un centenar de megabytes por par añadido.

Necesita Docker con el plugin Compose, nginx y certbot en el host, y un nombre (traduction.example.com en esta guía) que apunte a la IP del VPS.

Instalar LibreTranslate con Docker Compose

  1. Escribir el archivo docker-compose.yml

    En una carpeta dedicada (/opt/libretranslate), cree este archivo. El puerto se publica solo en la interfaz de bucle local. LT_API_KEYS activa la base de claves, LT_UNDER_ATTACK rechaza cualquier solicitud sin clave válida, interfaz web incluida, y LT_LOAD_ONLY limita la descarga a los cuatro idiomas útiles.

    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. Arrancar y esperar los modelos

    En el primer arranque, LibreTranslate descarga los modelos antes de abrir el puerto: siga los registros hasta la línea Listening at.

    docker compose up -d
    docker compose logs -f libretranslate
  3. Crear su primera clave

    La base de claves se crea al arrancar. Añada una clave limitada a 120 solicitudes por minuto; el comando la muestra una sola vez.

    docker compose exec libretranslate ./venv/bin/ltmanage keys add 120
  4. Comprobar que se exige la clave

    La primera solicitud, sin clave, debe ser rechazada; la segunda devuelve 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":"SU_CLAVE"}'

No publique nunca una instancia sin claves

Sin LT_API_KEYS ni LT_UNDER_ATTACK, LibreTranslate traduce para cualquiera que conozca la dirección. Una instancia abierta la encuentran y la usan rápidamente los robots: su CPU acaba trabajando para ellos. Mantenga el puerto en 127.0.0.1 y deje que solo nginx dé la cara a Internet.

Poner LibreTranslate detrás de nginx en HTTPS

Cree un server block en /etc/nginx/sites-available/ y actívelo. client_max_body_size fija el tamaño máximo de un archivo enviado a traducir: sin esta línea, nginx rechaza cualquier envío de más de 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;
    }
}

Después compruebe la configuración y solicite el certificado:

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

Llamar a la API desde una aplicación

Cada solicitud es un POST JSON con el texto (q), el idioma de origen (source, o auto), el idioma de destino (target) y la clave (api_key).

curl -s https://traduction.example.com/translate -H "Content-Type: application/json" \
  -d '{"q":"Su pedido ha sido enviado.","source":"fr","target":"ar","api_key":"SU_CLAVE"}'

En Python, la misma solicitud cabe en pocas líneas:

import requests

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

/languages lista los pares disponibles, /detect devuelve el idioma de un texto con un índice de confianza y /translate_file traduce un archivo enviado en multipart.

Gestionar las claves de API y los límites

Cree una clave por aplicación o por cliente: podrá revocar una sin tocar las demás, y cada clave lleva su propio límite de solicitudes por minuto. Desde la carpeta de la aplicación:

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 <clave>

Una clave desconocida recibe Invalid API key y una solicitud sin clave Please contact the server operator to get an API key. En la interfaz web, el icono de la llave («Set API Key») en la parte superior de la página guarda la clave en el navegador.

Ajustar LibreTranslate para un VPS pequeño

Cuatro variables de entorno bastan para adaptar la instancia al tamaño del servidor. LT_THREADS fija el número de procesos de traducción: cada uno carga los modelos en memoria, de ahí el valor 2 en un VPS de 2 GB; súbalo si tiene RAM y varias aplicaciones traducen en paralelo. LT_CHAR_LIMIT limita la longitud de un texto por solicitud, para que una sola llamada no ocupe un proceso durante minutos. LT_DISABLE_FILES_TRANSLATION desactiva la traducción de archivos si no la usa, y LT_DISABLE_WEB_UI retira la interfaz web para dejar solo la API.

Tras cada cambio en docker-compose.yml, reinicie con docker compose up -d: el contenedor se recrea y los volúmenes — es decir, las claves y los modelos — se conservan. Vigile la memoria con docker stats durante un día de uso real antes de fijar estos valores.

Lo que hay que saber sobre la calidad

Los modelos de Argos Translate son mucho más pequeños que los de los servicios comerciales. La traducción sigue siendo fiable para entender un mensaje, clasificar tickets, producir un primer borrador o traducir contenido habitual; es menos segura con los giros idiomáticos, el vocabulario muy especializado y los textos largos y literarios.

Una regla sencilla: traduzca automáticamente lo que sirve para entender y haga revisar por una persona lo que se publicará con su nombre — páginas de venta, condiciones generales, correos de marketing. Pruebe también sus propias frases en ambos sentidos antes de conectar una aplicación: la calidad varía de un par de idiomas a otro, y el inglés sirve a menudo de pivote entre dos idiomas que no son el inglés.

Añadir idiomas, hacer copias y actualizar

Para añadir un idioma, complete LT_LOAD_ONLY con su código (de, it, pt, tr…) y reinicie con docker compose up -d: los modelos que faltan se descargan al arrancar.

Qué copiar: solo el volumen lt-db, que contiene la base de claves. Los modelos de lt-models se vuelven a descargar solos y LibreTranslate no conserva los textos traducidos. Para actualizar, cambie la etiqueta de la imagen en docker-compose.yml tras leer las notas de la versión y luego:

docker compose pull
docker compose up -d

Instalación en un clic en ServOrbit

En un VPS de ServOrbit, LibreTranslate se instala desde el Marketplace: el script despliega la imagen oficial con árabe, francés, inglés y español, genera su clave de API, cierra la instancia a cualquier solicitud sin clave y configura nginx en HTTPS. La dirección es un subdominio de uno de sus dominios o el subdominio gratuito del VPS, certificado incluido, y la clave aparece en su área de cliente.

Compartir este artículoservorbit.com/ma-es/blog/autoalojar-libretranslate-vps-api-traduccion