Como hospedar o LibreTranslate por conta própria em 2026: modelos, limites da API e dados persistentes

Se você já tentou hospedar o LibreTranslate por conta própria, provavelmente conhece este estado frustrante: a UI aparece, mas os modelos não foram baixados ou um par de idiomas solicitado não está disponível. Recriar o container raramente corrige uma inconsistência entre URLs, estado e dependências.

Este guia usa um critério concreto de conclusão: listar os idiomas instalados, traduzir uma frase fixa nas duas direções e testar a cota de API key e as respostas de erro. Cada escolha de configuração é avaliada com base nesse critério, e não apenas pela presença de um indicador verde do container.

Restaurar o LibreTranslate em um host vazio

Liste o estado antes da criação do primeiro registro real: modelos baixados, banco de dados de API keys e configuração personalizada. Monte /home/libretranslate/.local antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Confirme o mount gravando dados inofensivos, substituindo o LibreTranslate e lendo-os novamente.

Snapshots são valiosos para um rollback rápido, mas é necessário ter um backup independente quando o host ou o volume desaparece. Restaure em um ambiente vazio com a imagem fixada e verifique se os modelos e o estado das API keys retornam e se o corpus de regressão é concluído com um resultado aceitável. Use volumes persistentes e snapshots para manter esses dois mecanismos de recuperação distintos.

Portas, processos e serviços privados

Não deixe que a imagem do LibreTranslate escolha acidentalmente a arquitetura de produção. A imagem fornece um processo na porta 5000; armazenamento, roteamento e requisitos externos ainda precisam de ciclos de vida definidos deliberadamente. O requisito do runtime local é armazenamento para o download dos modelos e CPU ou GPU adequada aos pares de idiomas. Mantenha o ciclo de vida explícito para que mover o LibreTranslate entre hosts não altere o comportamento silenciosamente.

O deployment está pronto para testes mais aprofundados quando consegue listar os idiomas instalados, traduzir uma frase fixa nas duas direções e testar a cota de API key e as respostas de erro. Acompanhe a transação nos logs e monitore os modelos de idioma carregados, o tempo de inferência da CPU, as requisições paralelas e o espaço em disco consumido pelos downloads dos modelos. Essas observações mostram se a topologia atual isola o componente correto.

Comprovar o deployment do LibreTranslate de ponta a ponta

Um gate de produção para o LibreTranslate deve poder ser executado por alguém que não criou o deployment. Forneça a essa pessoa a versão fixada, uma conta de teste sem dados sensíveis e esta tarefa: listar os idiomas instalados, traduzir uma frase fixa nas duas direções e testar a cota de API key e as respostas de erro. Se as instruções exigirem acesso shell não documentado, o serviço ainda não está pronto do ponto de vista operacional.

Repita o gate depois de substituir apenas o container. Em seguida, restaure os modelos baixados, o banco de dados de API keys e a configuração personalizada em uma infraestrutura vazia e comprove que os modelos e o estado das API keys retornam e que o corpus de regressão é concluído com um resultado aceitável. Meça os modelos de idioma carregados, o tempo de inferência da CPU, as requisições paralelas e o espaço em disco consumido pelos downloads dos modelos durante ambas as execuções bem-sucedidas; diferenças inesperadas geralmente revelam a ausência de um cache, índice, worker ou mount de dados.

Adicione um failure drill: envie uma entrada inofensiva próxima do limite de recurso ou formato associado a este cenário: os modelos não foram baixados ou um par de idiomas solicitado não está disponível. O LibreTranslate deve emitir um erro útil, preservar o estado existente e se recuperar quando a condição válida voltar a ocorrer. Salve os timestamps e as linhas de log relevantes, ocultando os secrets. Essas evidências se tornam a referência para a próxima alteração de imagem ou configuração.

Configurações do container que vale a pena revisar

Use um comando que exponha todas as escolhas importantes. Esta baseline vincula o LibreTranslate ao loopback do host, adiciona os mounts de dados conhecidos e fornece a primeira configuração necessária. Confirme o requisito local antes da exposição: armazenamento para o download dos modelos e CPU ou GPU adequada aos pares de idiomas.

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

Substitua tags flutuantes por uma versão testada ou por um digest. Após a inicialização, inspecione docker logs --tail 200 libretranslate e confirme que o processo está escutando na porta 5000. Em seguida, execute a ação de aceitação do LibreTranslate; uma resposta da página raiz não comprova que o cenário completo funciona: listar os idiomas instalados, traduzir uma frase fixa nas duas direções e testar a cota de API key e as respostas de erro.

Credenciais, funções e superfícies expostas

O risco de segurança específico da aplicação é executar uma API pública sem limites que terceiros podem consumir por completo. A resposta operacional é habilitar API keys ou autenticação upstream, aplicar rate limiting aos clientes públicos e instalar apenas os pares de idiomas necessários. Conclua o bootstrap por uma rota restrita e remova imediatamente o acesso temporário de configuração.

LT_API_KEYS controla o comportamento, não a confidencialidade; valide seu tipo e valor e armazene as credenciais reais do LibreTranslate separadamente. Conceda ao processo do LibreTranslate apenas os mounts documentados e as rotas para as dependências; evite acesso à raiz do host e ao socket do Docker. Registre falhas de autenticação e erros de configuração, mas oculte tokens, connection strings e conteúdo dos usuários.

Mantenha as URLs internas e externas corretas

A emissão de TLS é apenas metade da rota do LibreTranslate. Sirva a API por HTTPS e documente o base path correto. Envie o tráfego internamente para a porta 5000 e encaminhe o scheme externo para que as URLs geradas e os cookies seguros permaneçam consistentes.

Use o cenário completo do LibreTranslate a partir de uma rede limpa, não apenas a página raiz. Um erro 502 ou de certificado pode ser isolado com a configuração automática de domínio e TLS. Se o tráfego chegar ao processo e os modelos não tiverem sido baixados ou um par de idiomas solicitado não estiver disponível, diagnostique essa condição no ponto em que ela ocorre, em vez de empilhar redirects.

Failure drills para o LibreTranslate

Os testes de capacidade devem exercitar os modelos de idioma carregados, o tempo de inferência da CPU, as requisições paralelas e o espaço em disco consumido pelos downloads dos modelos, não uma requisição repetida para /. Execute o cenário “listar os idiomas instalados, traduzir uma frase fixa nas duas direções e testar a cota de API key e as respostas de erro” com concorrência realista e registre latência, taxa de erros e crescimento do armazenamento.

O planejamento do upgrade deve considerar este risco: pacotes de modelos e releases do servidor podem alterar o resultado das traduções, portanto mantenha um pequeno corpus de regressão. Teste a nova release com entradas representativas, repita a transação de aceitação e compare o resultado. Se os modelos não tiverem sido baixados ou um par de idiomas solicitado não estiver disponível, capture a transação com falha e inspecione o primeiro boundary envolvido, em vez de presumir que o ingress é responsável.

Fazer o deployment do LibreTranslate no Dockup sem perder seus limites

Um template do Dockup deve codificar a imagem, a porta 5000, os mounts, o timing do health check, o domínio, o TLS e a entrega de secrets. O Dockup deve preservar as configurações de runtime do LibreTranslate enquanto o operador confirma este requisito local: armazenamento para o download dos modelos e CPU ou GPU adequada aos pares de idiomas. O mesmo deployment pode ter como destino servidores do Dockup ou capacidade conectada pelo cliente.

Depois que a rota estiver ativa, aplique a configuração pública e tente listar os idiomas instalados, traduzir uma frase fixa nas duas direções e testar a cota de API key e as respostas de erro. Faça backup dos modelos baixados, do banco de dados de API keys e da configuração personalizada e mantenha o exercício de restore no plano operacional; essas são responsabilidades do LibreTranslate que continuam visíveis após o provisionamento da infraestrutura.

Perguntas frequentes

O que o LibreTranslate precisa para um deployment de produção?

Encaminhe o container do LibreTranslate na porta 5000 por meio de uma única origem HTTPS. O requisito do runtime local é armazenamento para o download dos modelos e CPU ou GPU adequada aos pares de idiomas. Não considere o LibreTranslate pronto até conseguir listar os idiomas instalados, traduzir uma frase fixa nas duas direções e testar a cota de API key e as respostas de erro.

Quais dados do LibreTranslate devem fazer parte de um backup?

Mantenha /home/libretranslate/.local persistente e inclua os modelos baixados, o banco de dados de API keys e a configuração personalizada no mesmo manifesto de recuperação. Um restore limpo do LibreTranslate só é aprovado quando os modelos e o estado das API keys retornam e o corpus de regressão é concluído com um resultado aceitável.

O LibreTranslate exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do LibreTranslate e mantenha a porta 5000 na rota interna. Aplique corretamente a configuração do LibreTranslate: sirva a API por HTTPS e documente o base path correto. No LibreTranslate, o HTTPS protege credenciais ou conteúdo dos usuários durante o trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do LibreTranslate?

Restaure o estado atual do LibreTranslate em um deployment isolado, aplique a versão candidata e repita a transação de aceitação. Preste atenção especial porque pacotes de modelos e releases do servidor podem alterar o resultado das traduções, portanto mantenha um pequeno corpus de regressão. Mantenha a imagem anterior do LibreTranslate até entender os limites de migração de dados e rollback.