Tradurre Excel con Python e l'API ChatGPT (guida 2026)

Ultimo aggiornamento: giugno 2026 — testato con l'SDK Python di OpenAI v1.x e l'API Chat Completions.

Questo tutorial usa l'API Chat Completions perché è semplice e ampiamente supportata. Per le nuove applicazioni puoi anche considerare l'API Responses di OpenAI e gli output strutturati.

Due modi per tradurre un file Excel

Prima di scrivere una sola riga di codice, è utile essere onesti su quale approccio faccia davvero al caso tuo:

• Scrivere uno script Python (questa guida). È la scelta migliore se vuoi automatizzare la traduzione su molti file, eseguirla in modo pianificato o integrarla in una pipeline più grande. Ti servono una chiave API OpenAI e qualche nozione di base di Python.
• Usare uno strumento già pronto. Se devi semplicemente tradurre un foglio di calcolo subito — mantenendo automaticamente grafici, formule e stili — caricarlo sul traduttore di Excel di Doc2Lang è più veloce e non richiede alcun codice.

Questa guida si concentra sull'approccio Python e ti fornisce codice completo e funzionante. Indicheremo anche con precisione dove la strada del fai-da-te si complica, così potrai decidere con cognizione di causa. Verso la fine trovi un confronto completo.

Prerequisiti

Prima di iniziare, ti serviranno alcune cose:

• Conoscenze di base di Python. Questo articolo contiene codice. Conoscere un po' di Python aiuta, ma spiegheremo ogni passaggio.
• Python installato. Se non lo hai ancora, scaricalo dal sito ufficiale.
• pip. Serve a installare le librerie Python. Se hai Python 3, quasi certamente hai già pip.
• Una chiave API OpenAI. Creane una nella dashboard del tuo account OpenAI. La stessa chiave funziona con tutti i modelli attuali (gpt-4o, gpt-4o-mini e così via).
• Il tuo file Excel. Tieni pronto il file .xlsx che vuoi tradurre.

Imposta la chiave API come variabile d'ambiente, così non finisce mai nel tuo codice:

macOS / Linux:

export OPENAI_API_KEY="your_api_key_here"

Windows PowerShell:

$env:OPENAI_API_KEY="your_api_key_here"

Com'è strutturato un file .xlsx (approfondimento facoltativo)

Quando salvi un foglio di calcolo come .xlsx, in realtà stai impacchettando diversi file in un unico archivio. Il formato si chiama OpenXML. Se ti incuriosisce, puoi rinominare il file in .zip, scompattarlo e dare un'occhiata al suo interno:

• xl/worksheets/ — un file XML per ogni foglio (sheet1.xml, sheet2.xml, …). È qui che risiedono davvero righe, colonne e dati delle celle.
• xl/styles.xml — ogni stile della cartella di lavoro: quali celle sono in grassetto, quali sono blu, quali numeri sono formattati come valuta e così via.
• xl/sharedStrings.xml — per risparmiare spazio, Excel memorizza una sola volta ciascuna stringa unica e la richiama ovunque venga usata. Se "Totale" compare 1.000 volte, viene memorizzato una volta sola.
• xl/workbook.xml — l'indice: quali fogli esistono, il loro ordine e proprietà come la protezione dei fogli.

Librerie come openpyxl nascondono gran parte di tutto questo, ma capire la struttura aiuta quando devi eseguire operazioni avanzate o risolvere problemi.

Un file report.xlsx decompresso: fogli di lavoro, stringhe condivise, stili e struttura della cartella di lavoro sono semplici file XML dentro un archivio zip.

Leggere e scrivere file Excel con openpyxl

openpyxl è una libreria Python pensata appositamente per leggere e scrivere file Excel (.xlsx, .xlsm, .xltx, .xltm). Ti permette di lavorare direttamente con fogli e celle.

Mettiamo in chiaro subito una cosa: openpyxl è eccellente per il lavoro a livello di cella, ma non è un motore di layout Excel a piena fedeltà. Forme, alcune immagini, grafici, macro e testo formattato all'interno di una singola cella potrebbero non essere preservati quando apri e risalvi un file. Per i file .xlsm con macro, carica con load_workbook(..., keep_vba=True) e risalva come .xlsm, altrimenti le macro potrebbero andare perse. Torneremo su questi limiti alla fine.

1. Installa openpyxl

pip install openpyxl

2. Concetti fondamentali

Alcuni concetti corrispondono direttamente a openpyxl:

Workbook — un file Excel nel suo insieme.

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

Sheet — una cartella di lavoro contiene uno o più fogli.

sheet = workbook.active          # il foglio attivo
another_sheet = workbook["Sheet2"]  # un foglio per nome

Cell — il punto in cui si incontrano una riga e una colonna. È qui che risiedono i dati.

cell_value = sheet["A1"].value   # lettura
sheet["B1"] = "Hello, Excel!"    # scrittura

Righe e colonne — si scorrono facilmente:

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

Tradurre il testo con l'API OpenAI

Dopo aver caricato i dati con openpyxl, il passo successivo è tradurli con l'API OpenAI.

1. Installa la libreria Python di OpenAI

pip install openai

2. Una funzione di traduzione moderna (2026)

import os
from openai import OpenAI
 
# Leggi la chiave da una variabile d'ambiente — non scriverla mai a mano nello script.
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
 
def translate_text(text, target_lang="Italian"):
    response = client.chat.completions.create(
        model="gpt-4o-mini",  # veloce ed economico; usa "gpt-4o" per la qualità migliore
        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()

Attenzione: molti tutorial più vecchi usano openai.ChatCompletion.create() con model="gpt-4". Quella sintassi appartiene all'SDK precedente alla versione 1.0 e non funziona più con openai>=1.0. Il codice qui sopra usa l'interfaccia attuale client.chat.completions.create(). Scegli gpt-4o-mini per costi bassi e velocità, oppure gpt-4o quando ti serve la massima qualità di traduzione.

3. Un primo tentativo ingenuo

L'approccio più comune nei tutorial è scorrere ogni cella e sovrascriverla:

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")

Funziona in una demo, ma sui fogli di calcolo reali presenta problemi concreti: invia una chiamata API per ogni cella (lento e costoso), traduce le formule rompendole e non ha alcuna protezione contro i limiti di frequenza. Risolviamo tutto questo.

Renderlo pronto per la produzione

1. Non tradurre le formule

Se una cella contiene una formula come =SUM(A1:A10), tradurla danneggerà il foglio di calcolo. Salta formule, celle vuote e valori non testuali:

def is_translatable(cell):
    # Salta celle vuote, numeri e celle con formule.
    value = cell.value
    return (
        isinstance(value, str)
        and value.strip() != ""
        and cell.data_type != "f"   # "f" = formula
    )

openpyxl riscrive solo cell.value, quindi formati numerici, font, riempimenti e gran parte della formattazione restano intatti, a patto di non toccare le celle non testuali.

2. Memorizza in cache le stringhe ripetute per ridurre i costi

I fogli di calcolo ripetono di continuo le stesse etichette ("Totale", "Data", il nome di un reparto). Traduci una sola volta ciascuna stringa unica:

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

In un report tipico, questo da solo può ridurre notevolmente le chiamate API — e la tua bolletta.

3. Raggruppa le celle in un'unica richiesta

Una chiamata API per ogni cella è la principale fonte di lentezza. Invia invece molte stringhe in un'unica richiesta, chiedendo al modello di restituire JSON così da poter ricollegare i risultati in modo affidabile:

import json
 
def translate_batch(texts, target_lang="Italian"):
    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. Riprova in caso di limiti di frequenza (backoff esponenziale)

Quando raggiungi un limite di frequenza, non andare in crash: aspetta e riprova, raddoppiando ogni volta il ritardo:

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. Gestisci in sicurezza i file non attendibili

Se elabori file Excel caricati da altre persone, proteggiti dall'XML malevolo. Installa defusedxml, che openpyxl userà automaticamente quando è presente, e verifica la dimensione e il tipo del file prima di caricarlo:

pip install defusedxml

Questo è facoltativo per i tuoi file, ma vivamente consigliato per qualsiasi file che non hai creato tu.

Script completo e funzionante

Ecco tutto unito in un unico script che puoi copiare ed eseguire. Raccoglie le stringhe uniche, le traduce in batch con i tentativi di ripetizione, memorizza i risultati in cache, salta le formule e salva in un nuovo file, così l'originale resta al sicuro.

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 = "Italian"
MODEL = "gpt-4o-mini"   # usa "gpt-4o" per una qualità superiore
BATCH_SIZE = 40
 
 
def is_translatable(cell):
    value = cell.value
    return (
        isinstance(value, str)
        and value.strip() != ""
        and cell.data_type != "f"   # "f" = formula
    )
 
 
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. Carica la cartella di lavoro
workbook = load_workbook(filename="your_file.xlsx")
 
# 2. Raccogli ogni stringa unica e traducibile
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. Traduci in batch e costruisci una cache {originale: traduzione}
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. Riscrivi le traduzioni, lasciando intatti formule e formattazione
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 in un nuovo file
workbook.save("your_translated_file.xlsx")
print("Done!")

Ecco un traduttore completo e pratico in ben meno di 100 righe: veloce, sicuro per le formule e molto più economico della versione cella per cella.

Facoltativo: irrobustire lo script per carichi di lavoro reali

Lo script qui sopra è già pratico. Per lavori più grandi o ricorrenti, tre ulteriori accorgimenti aiutano.

Non inghiottire ogni eccezione. Riprovare a ogni eccezione significa che anche una chiave API non valida o un nome di modello errato verrebbero ritentati cinque volte. Riprova solo in caso di limiti di frequenza e fallisci subito su tutto il 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.")

Questa versione verifica anche che il modello abbia restituito tutte le chiavi ricevute, così una risposta troncata o malformata fallisce in modo evidente invece di perdere celle in silenzio.

Mantieni l'ordine durante la deduplicazione. Usa una deduplicazione che preserva l'ordine invece di un set, così log e messaggi di errore restano prevedibili:

# era: unique_texts = list(unique_texts)  con un set()
unique_texts = list(dict.fromkeys(collected_texts))

Script Python vs. Doc2Lang: quale conviene usare?

Scrivere il proprio script è potente, ma ha limiti concreti. Ecco un confronto onesto:

Un report finanziario in inglese tradotto in italiano da Doc2Lang: i grafici a colonne e a linee, le formule, i formati numerici e le larghezze delle colonne restano tutti preservati (i nomi delle schede rimangono nella lingua originale, senza traduzione).

→ Prova il traduttore di Excel — niente chiave API, niente codice.

La regola pratica: se vuoi automatizzare lavori di traduzione ricorrenti, costruisci lo script qui sopra. Se devi semplicemente tradurre un foglio di calcolo subito senza scrivere codice, usa il traduttore di Excel — carica, traduci, scarica, con la formattazione mantenuta intatta.

Guide correlate

• Tradurre un file Excel in inglese: la strada senza codice e che cosa resta intatto
• Automatizzare la traduzione di documenti Word con Python e ChatGPT
• Tradurre facilmente i PDF con Python e OpenAI

Domande frequenti

Cosa faccio se ricevo un errore di limite di frequenza?
OpenAI applica limiti di frequenza in base al livello del tuo account. Usa i tentativi di ripetizione con backoff esponenziale mostrati sopra, riduci la dimensione del batch oppure aumenta il livello del tuo account se elabori grandi volumi.

Come traduco in più lingue contemporaneamente?
Scorri un elenco di lingue di destinazione ed esegui l'intero processo una volta per lingua, salvando ogni risultato in un proprio file (per esempio report_ja.xlsx, report_de.xlsx).

Usare l'API OpenAI ha un costo?
Sì. Paghi in base ai token utilizzati. Memorizzare in cache le stringhe ripetute e raggruppare le richieste (entrambe mostrate sopra) mantiene bassi i costi. gpt-4o-mini è drasticamente più economico dei modelli più grandi per la traduzione di tutti i giorni.

Questo preserverà la mia formattazione e le mie formule?
Lo script modifica solo i valori delle celle di testo, quindi gli stili di base delle celle — font, riempimenti, bordi, allineamento e formati numerici — vengono di solito preservati, e le formule sono saltate. Tuttavia, openpyxl non è un motore di layout Excel a piena fedeltà. Macro, forme, grafici, immagini, testo formattato all'interno di una singola cella e funzionalità complesse della cartella di lavoro potrebbero non essere preservati alla perfezione. Per i file .xlsm, carica con keep_vba=True e risalva come .xlsm. Se un layout perfetto al pixel conta più dell'automazione, uno strumento dedicato gestisce questi casi automaticamente.

Conclusione

Con openpyxl e l'API OpenAI puoi costruire un traduttore di Excel veloce e sicuro per le formule in ben meno di 100 righe di codice — perfetto quando devi automatizzare la traduzione su larga scala.

Se la tua priorità è preservare il layout più che automatizzare, uno strumento di traduzione Excel dedicato potrebbe essere la scelta migliore: gestisce grafici, forme e stili che openpyxl non riesce a mantenere.

→ Traduci un file Excel senza scrivere codice