Como traduzir texto com o Azure AI Translator em Python

Traduzir texto automaticamente é uma das tarefas mais comuns em aplicações modernas — de chatbots a plataformas de e-commerce — e o Azure AI Translator resolve-a com poucas linhas de código. Este guia mostra, passo a passo, como traduzir texto com o Azure AI Translator em Python, desde a criação do recurso no Azure até ao primeiro pedido bem-sucedido à REST API v3.0.

Pré-requisitos

• Uma subscrição do Azure ativa (o escalão gratuito F0 do Translator é suficiente para testar).
• Python 3.9 ou superior instalado na tua máquina.
• A biblioteca requests, que instalamos já a seguir.
• Noções básicas de linha de comandos.

Passo 1: Criar o recurso Translator no portal do Azure

Começa por criar o serviço. No portal do Azure, procura por "Translator" e cria um novo recurso. Escolhe um grupo de recursos, uma região próxima dos teus utilizadores (por exemplo, West Europe) e o escalão de preço F0, que é gratuito e ideal para aprender. Quando o recurso estiver pronto, abre a secção Keys and Endpoint e copia dois valores essenciais: a chave e a região (o campo Location/Region). Vais usar ambos no código do passo 3.

Guarda a chave num local seguro. Nunca a escrevas diretamente em código que partilhas nem a envies para repositórios públicos.

Passo 2: Preparar o ambiente Python

Cria uma pasta para o projeto e instala a única dependência necessária, a biblioteca requests, que trata dos pedidos HTTP por ti:

pip install requests

Para não deixar a chave escrita no código (uma má prática de segurança), guarda-a numa variável de ambiente. No Windows e no macOS/Linux, respetivamente:

# Windows (PowerShell)
$env:TRANSLATOR_KEY = "YOUR_TRANSLATOR_KEY"
$env:TRANSLATOR_REGION = "westeurope"

# macOS / Linux
export TRANSLATOR_KEY="YOUR_TRANSLATOR_KEY"
export TRANSLATOR_REGION="westeurope"

Passo 3: Fazer o primeiro pedido de tradução

O Azure AI Translator disponibiliza o endpoint global https://api.cognitive.microsofttranslator.com. Para traduzir, envias um pedido POST ao caminho /translate, com o parâmetro api-version=3.0 e o idioma de destino em to. O texto a traduzir vai no corpo do pedido, em formato JSON. O exemplo seguinte traduz uma frase de português (from=pt) para inglês (to=en):

import os
import requests

key = os.environ["TRANSLATOR_KEY"]
region = os.environ["TRANSLATOR_REGION"]
endpoint = "https://api.cognitive.microsofttranslator.com"

params = {"api-version": "3.0", "from": "pt", "to": ["en"]}
headers = {
    "Ocp-Apim-Subscription-Key": key,
    "Ocp-Apim-Subscription-Region": region,
    "Content-Type": "application/json",
}
body = [{"Text": "Olá, bem-vindo ao Azure AI Translator!"}]

response = requests.post(endpoint + "/translate", params=params, headers=headers, json=body)
result = response.json()
print(result[0]["translations"][0]["text"])

Se tudo estiver correto, a consola mostra Hello, welcome to Azure AI Translator!. O cabeçalho Ocp-Apim-Subscription-Region é obrigatório quando usas um recurso regional; incluí-lo evita o erro de autenticação mais comum, o 401000.

Passo 4: Traduzir para vários idiomas ao mesmo tempo

Uma grande vantagem da API é traduzir para vários idiomas num único pedido: basta indicar mais do que um valor em to. Também podes omitir o from para que o serviço detete automaticamente o idioma de origem:

params = {"api-version": "3.0", "to": ["en", "es", "fr"]}
body = [{"Text": "A tradução automática poupa muito tempo."}]

response = requests.post(endpoint + "/translate", params=params, headers=headers, json=body)
for t in response.json()[0]["translations"]:
    print(t["to"], "->", t["text"])

O serviço devolve uma tradução por cada idioma pedido e, quando não indicas o from, acrescenta um campo detectedLanguage com a língua identificada e o respetivo grau de confiança.

Verificar o resultado

Para confirmar que está tudo a funcionar, verifica três sinais. Primeiro, o código de estado da resposta deve ser 200 (podes imprimir response.status_code). Segundo, o JSON devolvido contém uma lista translations com o texto já traduzido. Terceiro, ao omitir o from, aparece também o campo detectedLanguage. Se receberes um erro 401 ou 403, revê a chave e a região; se for um 400, confirma o formato do corpo — tem de ser uma lista de objetos, cada um com a propriedade Text.

Conclusão

Com um recurso do Azure e menos de vinte linhas de Python, já consegues traduzir texto para dezenas de idiomas através do Azure AI Translator. A partir daqui, experimenta integrar a função numa API web com Flask, traduzir ficheiros em lote ou treinar um glossário próprio com o Custom Translator para respeitar a terminologia da tua empresa. Qual vai ser o primeiro idioma para o qual vais traduzir o teu conteúdo?