Comment auto-héberger LibreTranslate en 2026 : modèles, limites de l’API et données persistantes

Si vous avez déjà essayé d’auto-héberger LibreTranslate, vous connaissez probablement cette situation frustrante : l’interface s’affiche, mais les modèles n’ont pas été téléchargés ou une paire de langues demandée n’est pas disponible. Recréer le conteneur résout rarement un désaccord entre les URL, l’état et les dépendances.

Cette procédure utilise un critère de validation concret : lister les langues installées, traduire une phrase fixe dans les deux sens et tester le quota des clés d’API ainsi que les réponses d’erreur. Chaque choix de configuration est évalué par rapport à ce critère, et non à la présence d’un badge de conteneur « opérationnel ».

Restaurer LibreTranslate sur un hôte vierge

Recensez l’état avant la création de la première véritable donnée : modèles téléchargés, base de données des clés d’API et configuration personnalisée. Montez /home/libretranslate/.local avant le bootstrap, écrivez des données d’exemple inoffensives, puis remplacez le conteneur pour prouver que ce chemin est réellement persistant. Confirmez le montage en écrivant des données inoffensives, en remplaçant LibreTranslate, puis en les relisant.

Les snapshots sont utiles pour effectuer un rollback rapide, mais une sauvegarde indépendante est nécessaire lorsque l’hôte ou le volume disparaît. Effectuez la restauration dans un environnement vide avec l’image figée et vérifiez que les modèles et l’état des clés d’API sont bien restaurés et que le corpus de régression s’exécute avec un résultat acceptable. Utilisez les volumes persistants et les snapshots pour distinguer clairement ces deux mécanismes de récupération.

Ports, processus et services privés

Ne laissez pas l’image LibreTranslate définir accidentellement l’architecture de production. L’image fournit un processus sur le port 5000 ; le stockage, le routage et les exigences externes nécessitent toujours des cycles de vie définis avec soin. L’exigence du runtime local concerne le stockage des modèles téléchargés ainsi qu’un CPU ou un GPU adapté aux paires de langues. Rendez son cycle de vie explicite afin qu’un déplacement de LibreTranslate entre plusieurs hôtes ne modifie pas son comportement en silence.

Le déploiement est prêt pour des tests plus poussés lorsqu’il peut lister les langues installées, traduire une phrase fixe dans les deux sens et tester le quota des clés d’API ainsi que les réponses d’erreur. Suivez la transaction dans les logs et surveillez les modèles de langues chargés, le temps d’inférence CPU, les requêtes parallèles et l’espace disque consommé par les téléchargements de modèles. Ces observations indiquent si la topologie actuelle isole le bon composant.

Valider le déploiement de LibreTranslate de bout en bout

Un gate de production pour LibreTranslate doit pouvoir être exécuté par une personne qui n’a pas construit le déploiement. Fournissez-lui la version figée, un compte de test non sensible et cette tâche : lister les langues installées, traduire une phrase fixe dans les deux sens et tester le quota des clés d’API ainsi que les réponses d’erreur. Si les instructions exigent un accès shell non documenté, le service n’est pas encore prêt sur le plan opérationnel.

Répétez le gate après avoir remplacé uniquement le conteneur. Restaurez ensuite les modèles téléchargés, la base de données des clés d’API et la configuration personnalisée dans une infrastructure vierge, puis prouvez que les modèles et l’état des clés d’API sont restaurés et que le corpus de régression s’exécute avec un résultat acceptable. Mesurez les modèles de langues chargés, le temps d’inférence CPU, les requêtes parallèles et l’espace disque consommé par les téléchargements de modèles pendant les deux exécutions réussies ; les différences inattendues révèlent souvent l’absence d’un cache, d’un index, d’un worker ou d’un montage de données.

Ajoutez un test de panne : envoyez une entrée inoffensive proche de la limite de ressources ou de format associée à cette limite : les modèles n’ont pas été téléchargés ou une paire de langues demandée n’est pas disponible. LibreTranslate doit produire une erreur utile, préserver l’état existant et récupérer lorsque la condition valide est rétablie. Enregistrez les horodatages et les lignes de log pertinentes, en masquant les secrets. Ces éléments deviennent la référence pour la prochaine modification d’image ou de configuration.

Paramètres du conteneur à vérifier

Utilisez une commande qui expose chaque choix important. Cette configuration de base lie LibreTranslate à la boucle locale de l’hôte, ajoute les montages de données connus et fournit le premier paramètre requis. Confirmez l’exigence locale avant toute exposition : le stockage des modèles téléchargés ainsi qu’un CPU ou un GPU adapté aux paires de langues.

docker run -d \
  --name libretranslate \
  --restart unless-stopped \
  -p 127.0.0.1:5000:5000 \
  -v libretranslate-data:/home/libretranslate/.local \
  -e LT_API_KEYS=true \
  libretranslate/libretranslate:latest

Remplacez les tags flottants par une version testée ou un digest. Après le démarrage, consultez docker logs --tail 200 libretranslate et confirmez que le processus écoute sur le port 5000. Exécutez ensuite l’action de validation de LibreTranslate ; une réponse de la page racine ne suffit pas à prouver que le scénario complet fonctionne : lister les langues installées, traduire une phrase fixe dans les deux sens et tester le quota des clés d’API ainsi que les réponses d’erreur.

Identifiants, rôles et surfaces exposées

Le risque de sécurité propre à l’application consiste à exécuter une API publique sans limite que des tiers peuvent épuiser. La réponse opérationnelle consiste à activer les clés d’API ou l’authentification en amont, à appliquer une limitation de débit aux clients publics et à installer uniquement les paires de langues nécessaires. Terminez le bootstrap via une route restreinte et supprimez immédiatement l’accès temporaire une fois cette étape terminée.

LT_API_KEYS contrôle le comportement, pas la confidentialité ; validez son type et sa valeur, et stockez les véritables identifiants LibreTranslate séparément. Accordez au processus LibreTranslate uniquement ses montages documentés et ses routes vers les dépendances ; évitez tout accès à la racine de l’hôte et au socket Docker. Journalisez les échecs d’authentification et les erreurs de configuration, mais masquez les tokens, les chaînes de connexion et le contenu utilisateur.

Ne confondez pas les URL internes et externes

L’émission du TLS ne constitue que la moitié du routage de LibreTranslate. Servez l’API via HTTPS et documentez le chemin de base correct. Acheminez le trafic en interne vers le port 5000 et transmettez le schéma externe afin que les URL générées et les cookies sécurisés restent cohérents.

Utilisez le scénario LibreTranslate complet depuis un réseau vierge, et pas uniquement la page racine. Une erreur 502 ou un échec de certificat peut être isolé avec la configuration automatique du domaine et du TLS. Si le trafic atteint le processus et que les modèles n’ont pas été téléchargés ou qu’une paire de langues demandée n’est pas disponible, diagnostiquez cette condition à l’endroit où elle se produit au lieu d’empiler les redirections.

Tests de panne pour LibreTranslate

Les tests de capacité doivent solliciter les modèles de langues chargés, le temps d’inférence CPU, les requêtes parallèles et l’espace disque consommé par les téléchargements de modèles, et non répéter une requête vers /. Exécutez le scénario « lister les langues installées, traduire une phrase fixe dans les deux sens et tester le quota des clés d’API ainsi que les réponses d’erreur » avec un niveau de concurrence réaliste, puis consignez la latence, le taux d’erreur et la croissance du stockage.

La planification des mises à niveau doit tenir compte de ce risque : les packages de modèles et les versions du serveur peuvent modifier le résultat des traductions ; conservez donc un petit corpus de régression. Testez la nouvelle version avec des entrées représentatives, puis répétez la transaction de validation et comparez son résultat. Si les modèles n’ont pas été téléchargés ou qu’une paire de langues demandée n’est pas disponible, capturez la transaction en échec et inspectez la première limite concernée au lieu de supposer que l’ingress est responsable.

Déployer LibreTranslate sur Dockup sans perdre ses limites

Un template Dockup doit définir l’image, le port 5000, les montages, le timing des health checks, le domaine, le TLS et la fourniture des secrets. Dockup doit préserver les paramètres du runtime LibreTranslate tandis que l’opérateur confirme l’exigence locale : le stockage des modèles téléchargés ainsi qu’un CPU ou un GPU adapté aux paires de langues. Le même déploiement peut cibler des serveurs Dockup ou une capacité attachée par le client.

Une fois la route active, appliquez le paramètre public et essayez de lister les langues installées, de traduire une phrase fixe dans les deux sens et de tester le quota des clés d’API ainsi que les réponses d’erreur. Sauvegardez les modèles téléchargés, la base de données des clés d’API et la configuration personnalisée, et intégrez l’exercice de restauration au plan d’exploitation ; ces éléments relèvent de LibreTranslate et restent visibles après le provisioning de l’infrastructure.

Questions fréquentes

De quoi LibreTranslate a-t-il besoin pour un déploiement en production ?

Acheminez le conteneur LibreTranslate sur le port 5000 via une origine HTTPS unique. L’exigence du runtime local concerne le stockage des modèles téléchargés ainsi qu’un CPU ou un GPU adapté aux paires de langues. Ne considérez pas LibreTranslate comme prêt avant de pouvoir lister les langues installées, traduire une phrase fixe dans les deux sens et tester le quota des clés d’API ainsi que les réponses d’erreur.

Quelles données LibreTranslate doivent être incluses dans une sauvegarde ?

Rendez /home/libretranslate/.local persistant et incluez les modèles téléchargés, la base de données des clés d’API et la configuration personnalisée dans le même manifest de récupération. Une restauration LibreTranslate vierge n’est réussie que lorsque les modèles et l’état des clés d’API sont restaurés et que le corpus de régression s’exécute avec un résultat acceptable.

LibreTranslate nécessite-t-il HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origine publique de LibreTranslate et conservez le port 5000 sur la route interne. Appliquez correctement le paramètre LibreTranslate : servez l’API via HTTPS et documentez le chemin de base correct. Pour LibreTranslate, HTTPS protège les identifiants ou le contenu utilisateur pendant leur transit et garantit un comportement cohérent des clients dépendant de l’origine.

Comment tester une mise à niveau de LibreTranslate ?

Restaurez l’état actuel de LibreTranslate dans un déploiement isolé, appliquez la version candidate et répétez sa transaction de validation. Soyez particulièrement attentif, car les packages de modèles et les versions du serveur peuvent modifier le résultat des traductions ; conservez donc un petit corpus de régression. Gardez l’image LibreTranslate précédente jusqu’à ce que les limites de migration des données et de rollback soient comprises.