Come tradurre un export di WPML (file XLIFF in un ZIP)

Se hai appena esportato dei progetti di traduzione da WPML e ti trovi davanti a un file ZIP senza sapere come procedere, questa è la guida per te. Non è necessario scompattarlo, né aprire ogni singolo file XLIFF.

Cosa contiene esattamente l’archivio

L’export di WPML è un archivio ZIP che contiene una cartella chiamata posts/ e un file .xliff per ogni post. Nient’altro.

I numeri riportati di seguito provengono da un export reale di 44 post, misurati e non stimati, così puoi confrontarli con i tuoi.

Due aspetti di questo archivio sorprendono spesso gli utenti.

Ogni file dichiara la propria coppia linguistica. L’elemento <file> in cima a ogni XLIFF indica la lingua di origine e quella di destinazione:

<file original="103-3aeb85935a8505760aa368dc691898a7"
      source-language="fr"
      target-language="en"
      datatype="plaintext">

Quindi, un singolo export può contenere quattro lingue di destinazione diverse contemporaneamente, come nell’esempio: dal francese all’inglese, tedesco, spagnolo e italiano. L’archivio non è un unico progetto di traduzione, ma ne contiene quattro intrecciati.

WPML ti indica la dimensione del progetto. Ogni file riporta il proprio conteggio di parole in un attributo personalizzato:

tool:wpml-words-to-translate-count="843"

Sommandoli, saprai esattamente a cosa vai incontro prima di iniziare. Nell’esempio: 34.829 parole.

Cosa c’è dentro un singolo file

Un file XLIFF è un file XML. Ogni segmento di testo traducibile è un <trans-unit> con un <source> e un <target>, e il contenuto è racchiuso in CDATA affinché l’HTML all’interno di un post non interrompa la struttura XML.

Ecco un’unità completa. Questa era già stata elaborata tramite la memoria di traduzione, come indicato dagli attributi state:

<trans-unit resname="title" restype="string" datatype="html" id="title">
  <source><![CDATA[Bien ventiler son logement en hiver]]></source>
  <target state="needs-review-translation" state-qualifier="tm-suggestion">
    <![CDATA[Ventilating your home in winter]]>
  </target>
  <tool:extradata unit="Title" type="text" group="Main Content" group_id="Main_Content-0"/>
</trans-unit>

Le unità in quello stato erano l’eccezione nell’export: 18 su 228. Le altre 210 non hanno alcun attributo state e il loro target contiene il testo sorgente parola per parola.

Ed ecco il dettaglio che determina come affrontare l’intero lavoro.

WPML inserisce il testo sorgente nel campo target come punto di partenza. Pertanto, un file XLIFF in cui ogni <target> è compilato non è necessariamente un file tradotto. Nell’export reale, 217 delle 228 unità contenevano ancora il testo sorgente parola per parola. Solo 18 presentavano un suggerimento effettivo dalla memoria di traduzione, contrassegnato da state="needs-review-translation".

Se scorri velocemente il file, potresti concludere che sia già pronto. Non lo è.

Le unità che troverai

WPML non esporta solo il corpo del post. Nell’esempio, le 228 unità erano così suddivise:

Ogni unità contiene inoltre un tag <tool:extradata> che ne specifica la natura e il gruppo di appartenenza, permettendoti di distinguere una categoria da un titolo senza dover indovinare.

Nota i campi del plugin SEO. I tuoi meta titoli e le tue meta descrizioni sono in questo archivio, il che è un’ottima notizia ma implica una scelta: una meta descrizione tradotta letteralmente raramente è quella che genera il clic nella lingua di destinazione.

Nota anche URL. I tuoi slug sono traducibili e, nell’esempio di esportazione, erano stati lasciati deliberatamente nella lingua originale. Questa è una scelta reale con conseguenze per i tuoi link esistenti, e spetta solo a te prenderla.

Gli shortcode sono già dichiarati

Questa è la funzione migliore di WPML e quasi nessuno la nota. L’intestazione di ogni file contiene una frase che elenca ogni shortcode registrato sul tuo sito:

<phase phase-name="shortcodes" process-name="Shortcodes identification">
  <note>wp_caption,caption,gallery,playlist,audio,video,embed,
  wpml_language_switcher,product_brand,...</note>
</phase>

I tuoi shortcode personalizzati sono presenti insieme a quelli di WordPress. È un elenco leggibile dalla macchina di elementi che devono rimanere intatti dopo il processo di traduzione.

Perché le strade ovvie sono problematiche

Aprirli uno alla volta significa cercare le righe di destinazione all’interno dell’XML, tradurre attorno ai tag HTML e agli shortcode, salvare e ripetere l’operazione altre 43 volte. E poi fare lo stesso per ognuna delle altre tre lingue.

Inviarli a un traduttore o a un’agenzia significa che il lavoro linguistico sarà impeccabile, ma quello sui file no. Pagheresti la tariffa oraria di un esperto affinché faccia attenzione all’XML, e lo pagheresti di nuovo al prossimo aggiornamento dei contenuti. Il costo è il coordinamento, non la tariffa per parola.

Incollare il corpo del testo in un assistente chat funziona per un singolo post. Al decimo avrai perso il conto di quali file sono stati completati, la terminologia sarà diventata incoerente e nulla garantirà che le tue decisioni siano applicate uniformemente da un file all’altro.

L’intero processo, in cinque passaggi

Tutto ciò che precede il quarto passaggio è gratuito. Questo è più importante di quanto sembri: un piano che ha interpretato male il tuo archivio non costa nulla da correggere, quindi non c’è motivo di andare a intuito.

Due modi per gestire la fase intermedia

I passaggi da due a quattro possono essere eseguiti in un browser o interamente dal terminale. La scelta cambia solo chi digita i comandi, non il risultato finale.

Scegli in base al tuo modo di lavorare. Se stai leggendo queste righe con un terminale aperto, l’opzione B richiede meno passaggi. In caso contrario, l’opzione A non è affatto una versione ridotta.

Strada 1: invia il ZIP così com’è

AI Glot accetta sia XLIFF che ZIP, quindi un export di WPML può essere caricato senza essere aperto. Carica l’archivio, poi descrivi il lavoro in una frase.

L’istruzione è un testo libero, ed è qui che le particolarità dell’export diventano semplici invece che fastidiose:

Translate every trans-unit into the target language declared in each file.
Only translate units where the target still holds the same text as the source.
Leave the URL units exactly as they are.
Keep every shortcode, HTML tag and CDATA wrapper untouched.

Rileggi quella seconda riga, perché è quella fondamentale. “Traduci solo le unità in cui il testo di destinazione è ancora identico a quello di origine” descrive esattamente la situazione 217-su-228 menzionata sopra, e significa che non pagherai per rifare le 18 unità già gestite dalla tua memoria di traduzione.

Riceverai un piano prima di spendere qualsiasi credito: le lingue trovate, l’ambito, il conteggio delle parole e il costo. Se il piano ha interpretato male qualcosa, correggilo in una frase e verrà ricalcolato. Poi scarichi un unico ZIP con la stessa struttura, pronto per l’importazione.

Strada 2: lascia fare al tuo agente AI

Se lavori con Claude, ChatGPT, Cursor o qualsiasi altro agente di coding, non devi nemmeno toccare il browser. Il nostro strumento a riga di comando effettua l’accesso tramite OAuth e gestisce i file direttamente, così un agente può eseguire l’intero lavoro.

Installa ed effettua l’accesso una sola volta:

npm install -g @ai-glot/cli
aiglot auth login

Questo aprirà il browser per autorizzare la macchina. Su un server senza browser, usa aiglot auth login --device per il flusso tramite codice dispositivo, oppure aiglot auth login --key <key> in CI.

Poi indica al tuo agente la posizione del file e lascialo lavorare. Basta qualcosa di simile a questo:

My WPML export is at ~/Downloads/my-site-export.zip. It is a ZIP of XLIFF
files, one per WordPress post, and each file declares its own target
language.

Use the aiglot CLI to translate it. Run `aiglot batches create --help` and
`aiglot batches approve --help` first so you use the real flags. Create the
batch from the ZIP with an instruction that translates only the units whose
target still equals the source, and leaves the URL units alone. Show me the
plan and the cost before you approve anything. Use the lite quality tier.
Then poll until it is done and download the result next to the original.

Due elementi rendono efficace quel prompt, ed entrambi vale la pena copiarli.

Istruisce l’agente a leggere prima l’aiuto. Un agente che indovina i nomi dei flag fallirà alla prima chiamata e poi inventerà una scusa. aiglot help --json esporta ogni comando, flag e codice di uscita in un colpo solo se l’agente preferisce una struttura.

Inserisce un blocco prima della spesa. aiglot batches approve è l’unico comando che consuma crediti. Tutto ciò che precede è gratuito, quindi chiedere di vedere prima il piano non costa nulla e previene i tipi di malintesi più costosi.

Per riferimento, ecco la sequenza che l’agente finirà per eseguire:

# 1. Create the batch. Free. Returns a plan and an id.
aiglot batches create ~/Downloads/my-site-export.zip \
  --instruction "Translate every trans-unit into the target language declared in each file. Only translate units whose target still holds the same text as the source. Leave URL units unchanged. Keep shortcodes, HTML and CDATA intact." \
  --json

# 2. Approve. This is the only step that spends credits.
aiglot batches approve <batch-id> --quality lite

# 3. Poll until it finishes.
aiglot batches get <batch-id> --json

# 4. Download the translated archive.
aiglot batches download <batch-id> --output ~/Downloads/my-site-export.translated.zip

Esiste anche un server MCP (aiglot mcp) se il tuo agente preferisce i tool rispetto a una shell. La CLI è il punto di partenza migliore: funziona in uno script, funziona in CI e ti permette di vedere esattamente cosa è stato eseguito.

Integrare il tuo glossario

Se il tuo sito ha termini che non devono variare, come un nome di prodotto o la traduzione ufficiale di una frase ricorrente, inseriscili una volta nel glossario dello spazio di lavoro. Verranno quindi applicati a ogni file dell’archivio e anche all’esportazione successiva.

Questa è la parte che un traduttore automatico gestisce male. Il suo glossario sostituisce un termine ovunque appaia. Qui un glossario è trattato come un lemma, quindi si flette e si coniuga all’interno della frase invece di inserire una stringa fissa a metà testo.

Importazione in WPML

L’archivio tradotto ritorna con la stessa struttura: la stessa cartella posts/, gli stessi nomi di file, le stesse unità nello stesso ordine, con i target compilati. La schermata dei job di traduzione di WPML lo riaccetta esattamente come te lo ha fornito.

Due suggerimenti basati sulla struttura del file stesso. Importa prima un singolo file e controlla il post in WordPress prima di confermare l’intero archivio, perché una stringa di un page builder nel posto sbagliato è molto più facile da individuare nel rendering che in XML. E decidi i slug prima di importare, non dopo: cambiare un URL pubblicato comporta un redirect che dovrai gestire.

L’ambito reale di questo strumento

Usa questo sistema per il grosso del lavoro. Quarantaquattro post in quattro lingue sono esattamente il tipo di compito che è estenuante a mano e banale in un unico passaggio. Poi riserva la revisione umana dove serve davvero: per le pagine a più traffico e per tutto ciò in cui il wording è il prodotto stesso. Molti team usano AI Glot per una prima bozza e poi fanno revisionare l’output da un esperto, che è un ottimo modo di impiegare un professionista e un pessimo modo di spendere un pomeriggio dentro i file XML.

Per una homepage, assumi un traduttore. Per l’archivio di 44 post che hai esportato stamattina, non dedicarci l’intera settimana.

La struttura di esportazione qui descritta è stata rilevata da un export reale di WPML di 44 post in quattro coppie linguistiche. Il tuo export potrebbe differire se il sito usa un page builder o un plugin SEO diverso, e gli ID delle unità rifletteranno i tuoi plugin. La cartella posts/, il formato XLIFF 1.2, la coppia linguistica per file e i target copiati dalla sorgente sono le parti che sono risultate coerenti in tutti i 44 file.