Traduzir Excel com Python e a API do ChatGPT (guia 2026)

Última atualização: junho de 2026 — testado com o SDK do Python da OpenAI v1.x e a Chat Completions API.

Este tutorial usa a Chat Completions API porque ela é simples e amplamente suportada. Para novas aplicações, você também pode considerar a Responses API da OpenAI e as saídas estruturadas (structured outputs).

Duas formas de traduzir um arquivo Excel

Antes de escrever uma única linha de código, vale a pena ser honesto sobre qual abordagem realmente combina com você:

• Escrever um script em Python (este guia). Ideal se você quer automatizar a tradução de muitos arquivos, executá-la de forma agendada ou integrá-la a um pipeline maior. Você vai precisar de uma chave de API da OpenAI e de algum conhecimento básico de Python.
• Usar uma ferramenta pronta. Se você só precisa traduzir uma planilha agora mesmo — com gráficos, fórmulas e estilos preservados automaticamente — enviar o arquivo para o tradutor de Excel do Doc2Lang é mais rápido e não exige código algum.

Este guia foca na abordagem com Python e oferece um código completo e funcional. Também vamos apontar exatamente onde o caminho do "faça você mesmo" fica complicado, para que você decida de olhos abertos. Há uma comparação completa perto do final.

Pré-requisitos

Antes de começar, você vai precisar de algumas coisas:

• Conhecimento básico de Python. Este artigo inclui código. Saber um pouco de Python ajuda, mas vamos explicar cada etapa.
• Python instalado. Se você ainda não tem, baixe-o no site oficial.
• pip. É o que instala bibliotecas Python. Se você tem Python 3, quase com certeza já tem o pip.
• Uma chave de API da OpenAI. Crie uma no painel da sua conta OpenAI. A mesma chave funciona com todos os modelos atuais (gpt-4o, gpt-4o-mini e assim por diante).
• Seu arquivo Excel. Tenha em mãos o arquivo .xlsx que você quer traduzir.

Defina sua chave de API como uma variável de ambiente para que ela nunca fique escrita no seu código:

macOS / Linux:

export OPENAI_API_KEY="your_api_key_here"

Windows PowerShell:

$env:OPENAI_API_KEY="your_api_key_here"

Como um arquivo .xlsx é estruturado (contexto opcional)

Quando você salva uma planilha como .xlsx, na verdade está empacotando vários arquivos em um único arquivo compactado. Esse formato se chama OpenXML. Se tiver curiosidade, você pode renomear o arquivo para .zip, descompactá-lo e olhar o que tem dentro:

• xl/worksheets/ — um arquivo XML por planilha (sheet1.xml, sheet2.xml, …). É aqui que suas linhas, colunas e dados das células realmente ficam.
• xl/styles.xml — todos os estilos da pasta de trabalho: quais células estão em negrito, quais são azuis, quais números estão formatados como moeda e assim por diante.
• xl/sharedStrings.xml — para economizar espaço, o Excel armazena cada texto único uma vez aqui e o referencia onde quer que ele seja usado. Se "Total" aparece 1.000 vezes, ele é armazenado apenas uma vez.
• xl/workbook.xml — o sumário: quais planilhas existem, sua ordem e propriedades como a proteção de planilha.

Bibliotecas como a openpyxl escondem a maior parte disso de você, mas entender a estrutura ajuda quando você precisa de operações avançadas ou tem que resolver problemas.

Um arquivo report.xlsx descompactado: as planilhas, as strings compartilhadas, os estilos e a estrutura da pasta de trabalho são apenas arquivos XML dentro de um arquivo zip.

Lendo e escrevendo arquivos Excel com a openpyxl

A openpyxl é uma biblioteca Python criada especificamente para ler e escrever arquivos Excel (.xlsx, .xlsm, .xltx, .xltm). Ela permite trabalhar diretamente com planilhas e células.

Um ponto que vale deixar claro desde já: a openpyxl é excelente para trabalho no nível das células, mas não é um motor de layout do Excel com fidelidade total. Formas (shapes), algumas imagens, gráficos, macros e o rich text dentro de uma única célula podem não ser preservados quando você abre e salva o arquivo novamente. Para arquivos com macros (.xlsm), carregue com load_workbook(..., keep_vba=True) e salve novamente como .xlsm, caso contrário as macros podem ser perdidas. Voltaremos a esses limites no final.

1. Instale a openpyxl

pip install openpyxl

2. Conceitos fundamentais

Alguns conceitos se mapeiam diretamente na openpyxl:

Workbook (pasta de trabalho) — o arquivo Excel como um todo.

from openpyxl import load_workbook
 
workbook = load_workbook(filename="sample.xlsx")

Sheet (planilha) — uma pasta de trabalho contém uma ou mais planilhas.

sheet = workbook.active          # a planilha ativa
another_sheet = workbook["Sheet2"]  # uma planilha pelo nome

Cell (célula) — onde uma linha e uma coluna se encontram. É onde os dados ficam.

cell_value = sheet["A1"].value   # leitura
sheet["B1"] = "Hello, Excel!"    # escrita

Linhas e colunas — itere sobre elas com facilidade:

for row in sheet.iter_rows(values_only=True):
    for value in row:
        print(value)

Traduzindo texto com a API da OpenAI

Depois de carregar seus dados com a openpyxl, o próximo passo é traduzi-los com a API da OpenAI.

1. Instale a biblioteca Python da OpenAI

pip install openai

2. Uma função de tradução moderna (2026)

import os
from openai import OpenAI
 
# Lê a chave de uma variável de ambiente — nunca a escreva diretamente no script.
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
 
def translate_text(text, target_lang="Portuguese"):
    response = client.chat.completions.create(
        model="gpt-4o-mini",  # rápido e econômico; use "gpt-4o" para a melhor qualidade
        messages=[
            {
                "role": "system",
                "content": (
                    f"You are a professional translator. Translate the user's text "
                    f"into {target_lang}. Return only the translation, with no extra commentary."
                ),
            },
            {"role": "user", "content": text},
        ],
    )
    return response.choices[0].message.content.strip()

Atenção: muitos tutoriais antigos usam openai.ChatCompletion.create() com model="gpt-4". Essa sintaxe é do SDK anterior à versão 1.0 e não funciona mais com openai>=1.0. O código acima usa a interface atual client.chat.completions.create(). Escolha gpt-4o-mini para baixo custo e velocidade, ou gpt-4o quando precisar da máxima qualidade de tradução.

3. Uma primeira tentativa ingênua

A abordagem mais comum nos tutoriais é percorrer todas as células e sobrescrevê-las:

from openpyxl import load_workbook
 
workbook = load_workbook(filename="your_file.xlsx")
 
for sheet in workbook.worksheets:
    for row in sheet.iter_rows():
        for cell in row:
            if isinstance(cell.value, str):
                cell.value = translate_text(cell.value)
 
workbook.save("your_translated_file.xlsx")

Isso funciona em uma demonstração, mas tem problemas reais em planilhas de verdade: envia uma chamada de API por célula (lento e caro), traduz fórmulas e as quebra, e não tem nenhuma proteção contra limites de taxa. Vamos corrigir tudo isso.

Deixando o código pronto para produção

1. Não traduza fórmulas

Se uma célula contém uma fórmula como =SUM(A1:A10), traduzi-la vai corromper a planilha. Ignore fórmulas, células vazias e valores que não sejam texto:

def is_translatable(cell):
    # Ignora células vazias, números e células de fórmula.
    value = cell.value
    return (
        isinstance(value, str)
        and value.strip() != ""
        and cell.data_type != "f"   # "f" = fórmula
    )

A openpyxl só reescreve cell.value, então formatos numéricos, fontes, preenchimentos e a maior parte do estilo permanecem intactos, desde que você não mexa nas células que não são texto.

2. Faça cache de textos repetidos para reduzir custos

As planilhas repetem constantemente os mesmos rótulos ("Total", "Data", o nome de um departamento). Traduza cada texto único apenas uma vez:

cache = {}
 
def translate_cached(text, target_lang="Portuguese"):
    if text not in cache:
        cache[text] = translate_text(text, target_lang)
    return cache[text]

Em um relatório típico, só isso já pode reduzir bastante o número de chamadas de API — e a sua conta.

3. Agrupe células em uma única requisição

Uma chamada de API por célula é a maior fonte de lentidão. Em vez disso, envie vários textos em uma única requisição, pedindo ao modelo que retorne JSON para você mapear os resultados de volta com segurança:

import json
 
def translate_batch(texts, target_lang="Portuguese"):
    numbered = {str(i): t for i, t in enumerate(texts)}
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {
                "role": "system",
                "content": (
                    f"You are a professional translator. Translate each value in the "
                    f"JSON object into {target_lang}. Keep the same keys. "
                    f"Return only a JSON object."
                ),
            },
            {"role": "user", "content": json.dumps(numbered, ensure_ascii=False)},
        ],
        response_format={"type": "json_object"},
    )
    result = json.loads(response.choices[0].message.content)
    return [result[str(i)] for i in range(len(texts))]

4. Tente novamente em caso de limite de taxa (backoff exponencial)

Quando você atingir um limite de taxa, não deixe o programa quebrar — espere e tente de novo, dobrando o tempo de espera a cada tentativa:

import time
 
def with_retry(func, *args, retries=5, **kwargs):
    for attempt in range(retries):
        try:
            return func(*args, **kwargs)
        except Exception as e:
            wait = 2 ** attempt
            print(f"Error: {e}. Retrying in {wait}s...")
            time.sleep(wait)
    raise RuntimeError("Translation failed after several retries.")

5. Lide com arquivos não confiáveis de forma segura

Se você processa arquivos Excel enviados por outras pessoas, proteja-se contra XML malicioso. Instale a defusedxml, que a openpyxl usará automaticamente quando estiver presente, e valide o tamanho e o tipo do arquivo antes de carregá-lo:

pip install defusedxml

Isso é opcional para os seus próprios arquivos, mas fortemente recomendado para qualquer arquivo que você não tenha criado.

Script completo e funcional

Aqui está tudo combinado em um único script que você pode copiar e executar. Ele reúne os textos únicos, traduz em lotes com novas tentativas, faz cache dos resultados, ignora fórmulas e salva em um novo arquivo, para que o original fique a salvo.

import json
import os
import time
from openai import OpenAI
from openpyxl import load_workbook
 
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
 
TARGET_LANG = "Portuguese"
MODEL = "gpt-4o-mini"   # use "gpt-4o" para maior qualidade
BATCH_SIZE = 40
 
 
def is_translatable(cell):
    value = cell.value
    return (
        isinstance(value, str)
        and value.strip() != ""
        and cell.data_type != "f"   # "f" = fórmula
    )
 
 
def translate_batch(texts, target_lang=TARGET_LANG, retries=5):
    numbered = {str(i): t for i, t in enumerate(texts)}
    system = (
        f"You are a professional translator. Translate each value in the JSON object "
        f"into {target_lang}. Keep the same keys. Return only a JSON object."
    )
    for attempt in range(retries):
        try:
            response = client.chat.completions.create(
                model=MODEL,
                messages=[
                    {"role": "system", "content": system},
                    {"role": "user", "content": json.dumps(numbered, ensure_ascii=False)},
                ],
                response_format={"type": "json_object"},
            )
            result = json.loads(response.choices[0].message.content)
            return [result[str(i)] for i in range(len(texts))]
        except Exception as e:
            wait = 2 ** attempt
            print(f"Error: {e}. Retrying in {wait}s...")
            time.sleep(wait)
    raise RuntimeError("Translation failed after several retries.")
 
 
# 1. Carrega a pasta de trabalho
workbook = load_workbook(filename="your_file.xlsx")
 
# 2. Reúne todos os textos únicos e traduzíveis
unique_texts = set()
for sheet in workbook.worksheets:
    for row in sheet.iter_rows():
        for cell in row:
            if is_translatable(cell):
                unique_texts.add(cell.value)
unique_texts = list(unique_texts)
 
# 3. Traduz em lotes e monta um cache no formato {original: tradução}
cache = {}
for start in range(0, len(unique_texts), BATCH_SIZE):
    chunk = unique_texts[start:start + BATCH_SIZE]
    cache.update(dict(zip(chunk, translate_batch(chunk))))
 
# 4. Escreve as traduções de volta, sem tocar em fórmulas e estilos
for sheet in workbook.worksheets:
    for row in sheet.iter_rows():
        for cell in row:
            if is_translatable(cell):
                cell.value = cache[cell.value]
 
# 5. Salva em um novo arquivo
workbook.save("your_translated_file.xlsx")
print("Done!")

Esse é um tradutor completo e prático em bem menos de 100 linhas — rápido, seguro com fórmulas e muito mais barato do que a versão célula por célula.

Opcional: reforçando o código para cargas de trabalho reais

O script acima já é prático. Para tarefas maiores ou recorrentes, três proteções adicionais ajudam.

Não engula todas as exceções. Tentar novamente em qualquer exceção significa que uma chave de API inválida ou um nome de modelo errado também serão repetidos cinco vezes. Tente novamente apenas em caso de limite de taxa e falhe rapidamente em todo o resto:

from openai import RateLimitError
 
def translate_batch(texts, target_lang=TARGET_LANG, retries=5):
    numbered = {str(i): t for i, t in enumerate(texts)}
    system = (
        f"You are a professional translator. Translate each value in the JSON object "
        f"into {target_lang}. Keep the same keys. Return only a JSON object."
    )
    for attempt in range(retries):
        try:
            response = client.chat.completions.create(
                model=MODEL,
                messages=[
                    {"role": "system", "content": system},
                    {"role": "user", "content": json.dumps(numbered, ensure_ascii=False)},
                ],
                response_format={"type": "json_object"},
            )
            result = json.loads(response.choices[0].message.content)
            missing = [str(i) for i in range(len(texts)) if str(i) not in result]
            if missing:
                raise ValueError(f"Missing translations for keys: {missing}")
            return [result[str(i)] for i in range(len(texts))]
        except RateLimitError:
            wait = 2 ** attempt
            print(f"Rate limited. Retrying in {wait}s...")
            time.sleep(wait)
    raise RuntimeError("Translation failed after several retries.")

Essa versão também valida que o modelo retornou todas as chaves que recebeu, então uma resposta truncada ou malformada falha de forma evidente em vez de descartar células silenciosamente.

Mantenha a ordem ao remover duplicatas. Use a remoção de duplicatas com ordem preservada em vez de um set, para que logs e mensagens de erro permaneçam previsíveis:

# antes: unique_texts = list(unique_texts)  com um set()
unique_texts = list(dict.fromkeys(collected_texts))

Script em Python vs. Doc2Lang: qual você deve usar?

Escrever o seu próprio script é poderoso, mas tem limites reais. Aqui vai uma comparação honesta:

Um relatório financeiro em inglês traduzido para o português pelo Doc2Lang: gráficos de colunas e de linhas, fórmulas, formatos numéricos e larguras de coluna ficam todos preservados (os nomes das abas permanecem no idioma original, sem tradução).

→ Experimente o tradutor de Excel — sem chave de API, sem código.

A regra geral: se você quer automatizar tarefas de tradução recorrentes, construa o script acima. Se você só precisa traduzir uma planilha agora mesmo, sem escrever código, use o tradutor de Excel — envie, traduza, baixe, com a formatação mantida intacta.

Guias relacionados

• Traduzir um arquivo do Excel para inglês: o caminho sem código e o que se preserva
• Automatizando a tradução de documentos Word com Python e ChatGPT
• Tradução fácil de PDF com Python e OpenAI

Perguntas frequentes

E se eu receber um erro de limite de taxa?
A OpenAI impõe limites de taxa com base no nível da sua conta. Use a nova tentativa com backoff exponencial mostrada acima, reduza o tamanho do lote ou faça upgrade do nível da sua conta se você processa grandes volumes.

Como faço para traduzir para vários idiomas de uma vez?
Percorra uma lista de idiomas de destino e execute todo o processo uma vez para cada idioma, salvando cada resultado em seu próprio arquivo (por exemplo, report_pt.xlsx, report_de.xlsx).

Usar a API da OpenAI tem custo?
Sim. Você paga por token usado. Fazer cache de textos repetidos e agrupar requisições (ambos mostrados acima) mantêm os custos baixos. O gpt-4o-mini é drasticamente mais barato do que os modelos maiores para tradução do dia a dia.

Isso vai preservar minha formatação e minhas fórmulas?
O script só altera os valores das células de texto, então os estilos básicos das células — fontes, preenchimentos, bordas, alinhamento e formatos numéricos — geralmente são preservados, e as fórmulas são ignoradas. No entanto, a openpyxl não é um motor de layout do Excel com fidelidade total. Macros, formas (shapes), gráficos, imagens, rich text dentro de uma única célula e recursos complexos da pasta de trabalho podem não ser preservados perfeitamente. Para arquivos .xlsm, carregue com keep_vba=True e salve novamente como .xlsm. Se o layout pixel-perfect importa mais do que a automação, uma ferramenta dedicada lida com esses casos automaticamente.

Conclusão

Com a openpyxl e a API da OpenAI, você pode construir um tradutor de Excel rápido e seguro com fórmulas em bem menos de 100 linhas de código — uma ótima opção quando você precisa automatizar a tradução em escala.

Se a sua prioridade é a preservação do layout em vez da automação, uma ferramenta dedicada de tradução de Excel pode ser uma escolha melhor — ela lida com gráficos, formas e estilos que a openpyxl não consegue.

→ Traduza um arquivo Excel sem escrever código