Como usar a biblioteca traducao no seu projeto Python
Você provavelmente já caiu na tentação de fazer uma chamada direta à API do Google Tradutor ou do DeepL sem pensar nas consequências. Funciona até você atingir o limite de requisições e receber um erro 429. Aí que a library traducao entra como uma opção decente para scripts rápidos e automações internas. A instalação é simples. Roda um pip install traducao e pronto. A biblioteca depende do requests e do text-unidecode, mas o pip resolve isso automaticamente. Nada de configurações complicadas de chaves de API, pelo menos não na versão gratuita.
O que é library traducao e quando vale a pena
O pacote em si é um wrapper em torno do Google Translate gratuito. Não exige conta Google, não cobra nada e traduz entre mais de cem idiomas. O problema é que o Google altera a estrutura da página de tradução periodicamente, e toda vez que isso acontece a biblioteca quebra por algumas semanas até alguém no repositório do GitHub atualizar o parser. Usei ela por anos em projetos de análise de dados quando precisava traduzir colunas inteiras de um dataframe sem gastar nada. O fluxo típico envolve carregar os dados, aplicar a função translate.text com o idioma de destino e salvar. Para datasets pequenos, tipo menos de mil linhas, leva alguns minutos. Para datasets maiores, o tempo cresce linearmente porque cada requisição é independente e o Google rate-limits após certo volume.
Uma coisa que ninguém conta é que a biblioteca não lida bem com caracteres especiais de línguas com diacríticos pesados. Encontrei um caso concreto no qual texts em polonês com caracteres como ł e ń eram traduzidos de forma corrompida quando o idioma de saída era português. O resultado vinha com pontos de interrogação no lugar dos caracteres. A solução foi converter tudo para UTF-8 explicitamente antes de passar para a função, usando encode e decode apropriados. Ficou assim: texto.encode('utf-8').decode('utf-8') antes de cada chamada.
Instalação e primeiros passos
Rode o comando abaixo no terminal do seu ambiente virtual: pip install traducao
Depois, num script Python, importa o módulo e faz uma chamada básica. Um exemplo mínimo seria passar uma string e o código do idioma alvo. A função retorna uma string traduzida ou lança uma exceção se a tradução falhar. É importante tratar essa exceção porque, em produção, requisições mal formadas ou textos vazios geram erros silenciosos se você não usar try-except. Aqui vai um exemplo funcional simples:
👉 Clique no botão abaixo para saber mais sobre o assunto!
from traducao import translate
resultado = translate.text("hello world", dest="pt")
print(resultado) Isso imprime "olá mundo". Simples assim. Mas lembre-se de que a biblioteca não oferece batching, então se você precisa traduzir dez mil frases, vai precisar fazer um loop com pauses entre as chamadas para não ser bloqueado.
Limitações reais que todo mundo ignora
A primeira limitação é a falta de suporte a traduçõe contextuais. A biblioteca traduz frase por frase isoladamente. Se você tem um texto técnico com siglas ou termos que mudam de significado conforme o contexto, o resultado vai ser inconsistente. Já vi documentos de manuais técnicos ficarem piores depois da tradução automática porque termos como "build" foram traduzidos como "construir" em vez de "compilar" dependendo da frase. A segunda limitação é a instabilidade. O parser da biblioteca lê o conteúdo HTML da página de tradução do Google. Quando o Google muda o layout — e eles mudam frequentemente — a função para de retornar resultados por um tempo. Às vezes semanas. Não há como contornar isso além de monitorar o repositório e atualizar a versão quando lançarem um patch.
Se você precisa de algo mais robusto para uso profissional, considere o wrapper do DeepL ou até mesmo chamadas diretas à API do Google Cloud Translation. A diferença é que essas opções exigem cadastro, cartão de crédito e configuração de project ID. Para uso pessoal e scripts internos, a library traducao ainda é a opção mais prática que existe.
Como lidar com rate limiting na prática
O Google permite algumas dezenas de requisições por minuto antes de começar a retornar erros. Se seu script traduzir rápido demais, ele vai travar. A solução é adicionar um sleep entre as chamadas. Eu uso time.sleep(1) entre cada requisição, o que garante que não ultrapasso o limite. Para conjuntos grandes, isso aumenta significativamente o tempo total, mas evita perda de dados por erros de conexão. Outra técnica útil é processar os textos em lotes menores e reiniciar o script de onde parou caso haja falha. Salvo o índice de processamento em um arquivo JSON e uso esse número como ponto de retomada. Economiza horas de trabalho manual.
Download e recursos
O pacote está disponível no PyPI. Você pode baixar pela linha de comando com pip ou visitar o repositório oficial no GitHub para verificar issues abertas e pull requests recentes. Sempre confira a versão mais recente antes de instalar, porque a estabilidade depende diretamente do último commit do mantenedor. Se quiser testar rapidamente, crie um arquivo .py na pasta do seu projeto com o código de exemplo acima e execute. Se retornar a tradução corretamente, a instalação funcionou. Se lançar erro de importação, verifique se o ambiente virtual está ativo e se o pip está apontando para o Python correto.
A library traducao não é perfeita, mas para quem precisa de uma solução funcional sem pagar por APIs, ainda é uma das melhores opções disponíveis no ecossistema Python. O truque é saber quando usar e quando migrar para algo mais estável.
