Een WPML-export vertalen (XLIFF-bestanden in een ZIP)

Heb je net vertaalopdrachten uit WPML geëxporteerd en vraag je je af wat je met het ZIP-bestand moet doen? Dan is deze gids voor jou. Je hoeft het niet uit te pakken en je hoeft geen enkel XLIFF-bestand te openen.

Wat je precies in handen hebt

De export van WPML is een ZIP-archief met daarin één map, posts/ genaamd, en één .xliff-bestand per bericht. Verder niets.

De onderstaande aantallen zijn afkomstig uit een echte export van 44 berichten. Ze zijn gemeten, niet geschat, zodat je ze met je eigen aantallen kunt vergelijken.

Twee dingen aan dit archief verrassen de meeste mensen.

Elk bestand vermeldt zijn eigen taalpaar. Het <file>-element bovenaan elk XLIFF-bestand geeft aan uit welke taal de inhoud komt en naar welke taal die wordt vertaald:

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

Eén export kan dus vier doeltalen tegelijk bevatten, zoals in het voorbeeld: uit het Frans naar het Engels, Duits, Spaans en Italiaans. Het archief bevat niet één vertaalopdracht, maar vier opdrachten door elkaar.

WPML geeft aan hoe groot de vertaalopdracht is. Elk bestand bevat een eigen woordenaantal in een aangepast attribuut:

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

Tel ze bij elkaar op en je weet precies waar je aan begint voordat je ergens aan vastzit. In het voorbeeld gaat het om 34,829 woorden.

Wat er in één bestand staat

Een XLIFF-bestand is XML. Elk vertaalbaar tekstfragment staat in een <trans-unit> met een <source> en een <target>. De inhoud is verpakt in CDATA, zodat HTML in een bericht de omringende XML niet beschadigt.

Hier zie je één volledige unit. Deze was al verwerkt met vertaalgeheugen, zoals je kunt zien aan de state-attributen:

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

Units met die status vormden de uitzondering in het exportbestand: 18 van de 228. De overige 210 hebben helemaal geen state-attribuut en hun target bevat woord voor woord de brontekst.

En dit is het detail dat bepaalt hoe je de hele klus aanpakt.

WPML zet de brontekst als uitgangspunt in de target. Een XLIFF-bestand waarin elke <target> is ingevuld, is dus niet automatisch vertaald. In de daadwerkelijke export bevatte 217 van de 228 units nog woord voor woord de brontekst. Slechts 18 bevatten een echte suggestie uit het vertaalgeheugen, gemarkeerd met state="needs-review-translation".

Als je het bestand vluchtig bekijkt, denk je dat het al klaar is. Dat is niet zo.

Welke units je aantreft

WPML exporteert niet alleen de berichtinhoud. In het voorbeeld was de export als volgt verdeeld over 228 units:

Elke unit bevat ook een <tool:extradata>-tag met de naam en groep van de inhoud. Zo kun je zonder te gokken zien of iets een categorie of een titel is.

Let op de velden van de SEO-plug-ins. Je metatitels en metabeschrijvingen staan in dit archief. Dat is goed nieuws, maar vraagt ook om een keuze: een letterlijk vertaalde metabeschrijving levert in de doeltaal zelden de meeste klikken op.

Let ook op URL. Je kunt je slugs vertalen. In het voorbeeld waren ze bewust in de brontaal gelaten. Dat is een keuze met gevolgen voor je bestaande links, en alleen jij kunt die maken.

De shortcodes zijn al vastgelegd

Dit is het handigste wat WPML doet, en bijna niemand merkt het op. De header van elk bestand bevat een phase met alle shortcodes die op je site zijn geregistreerd:

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

Je eigen shortcodes staan er naast die van WordPress. Het is een machineleesbare lijst van elementen die de volledige uitwisseling ongewijzigd moeten doorstaan.

Waarom de voor de hand liggende aanpakken problemen opleveren

Ze een voor een openen betekent dat je de doellijnen in XML moet zoeken, rond HTML-tags en shortcodes moet vertalen, opslaan en dit nog 43 keer moet doen. Daarna doe je hetzelfde voor elk van de andere drie talen.

Ze naar een vertaler of een bureau sturen betekent dat het taalwerk goed zit, maar het bestandswerk niet. Je betaalt een deskundig uurtarief voor iemand die zorgvuldig met XML omgaat, en bij de volgende inhoudsupdate betaal je dat opnieuw. De coördinatie kost geld, niet het tarief per woord.

De inhoud in een chatassistent plakken werkt voor één bericht. Bij het tiende ben je het overzicht kwijt van welke bestanden klaar zijn, zijn de termen niet meer consistent en worden je keuzes niet meegenomen van het ene bestand naar het volgende.

Het hele traject, in vijf stappen

Alles tot en met stap vier is gratis. Dat is belangrijker dan het misschien klinkt: als een plan je archief verkeerd heeft begrepen, kost het niets om dat te corrigeren. Je hoeft dus niet te gokken.

Twee manieren om de tussenstappen uit te voeren

Stap twee tot en met vier kun je in een browser uitvoeren of volledig vanuit je terminal. De keuze bepaalt wie het typwerk doet, niet wat je terugkrijgt.

Kies wat past bij de manier waarop je al werkt. Lees je dit met een terminal open, dan kost optie B minder stappen. Zo niet, dan is optie A niet de mindere versie.

Route 1: stuur de ZIP zoals die is

AI Glot accepteert zowel XLIFF als ZIP, dus je kunt een WPML-export ongeopend uploaden. Upload het archief en beschrijf de opdracht vervolgens in één zin.

Je kunt de instructie vrij formuleren. Zo worden de eigenaardigheden van je export eenvoudig in plaats van vervelend:

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.

Lees die tweede regel nog eens, want die is belangrijk. “Vertaal alleen eenheden waarvan de doeltekst nog hetzelfde is als de brontekst” beschrijft precies de situatie met 217 van de 228 hierboven. Zo hoef je niet opnieuw te betalen voor de 18 eenheden die je vertaalgeheugen al had verwerkt.

Je krijgt eerst een plan, voordat er iets wordt uitgegeven: de gevonden talen, de omvang, het aantal woorden en de kosten. Heeft het plan iets verkeerd begrepen, corrigeer dat dan in één zin en het wordt opnieuw opgesteld. Daarna download je één ZIP-bestand met dezelfde structuur, klaar om te importeren.

Route 2: laat je AI-agent het doen

Als je met Claude, ChatGPT, Cursor of een andere codeeragent werkt, hoef je helemaal geen browser te gebruiken. Onze opdrachtregeltool meldt je aan via OAuth en verwerkt een bestand rechtstreeks, zodat een agent de hele klus kan uitvoeren.

Installeer de tool en meld je één keer aan:

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

Er wordt een browser geopend om de computer te autoriseren. Gebruik op een server zonder browser aiglot auth login --device voor de apparaatcodeprocedure, of aiglot auth login --key <key> in CI.

Geef je agent vervolgens de locatie van het bestand en laat hem aan de slag gaan. Dit is bijvoorbeeld voldoende:

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.

Twee dingen zorgen ervoor dat deze prompt werkt. Beide zijn het waard om over te nemen.

De prompt vraagt de agent om eerst de Help te lezen. Een agent die de namen van opties gokt, loopt al bij de eerste aanroep vast en verzint vervolgens een reden. Met aiglot help --json worden alle opdrachten, opties en afsluitcodes in één keer weergegeven, als de agent liever met een gestructureerd overzicht werkt.

De prompt laat de agent stoppen voordat er kosten worden gemaakt. aiglot batches approve is de enige opdracht die credits kost. Alles daarvoor is gratis. Eerst het plan opvragen kost dus niets en voorkomt de dure vorm van misverstanden.

Ter referentie: dit is de reeks opdrachten die de agent uiteindelijk uitvoert:

# 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

Er is ook een MCP-server (aiglot mcp) als je agent liever met tools werkt dan met een shell. De CLI is een beter startpunt: die werkt in scripts en in CI, en je kunt precies zien wat er is uitgevoerd.

Je woordenlijst gebruiken

Heeft je site termen die niet mogen veranderen, zoals een productnaam of een vaste vertaling van een terugkerende frase? Voeg ze één keer toe aan de woordenlijst van je werkruimte. Ze worden dan toegepast op elk bestand in het archief en ook op de volgende export.

Dit is precies waar automatische vertaling tekortschiet. De woordenlijst daarvan vervangt een term overal waar die voorkomt. Hier wordt een woordenlijst behandeld als een lemma, dat wordt verbogen en vervoegd zodat het in de zin past, in plaats van dat er een vaste tekst midden in de zin wordt geplakt.

Terug importeren in WPML

Het vertaalde archief heeft dezelfde structuur als het origineel: dezelfde map posts/, dezelfde bestandsnamen en dezelfde eenheden in dezelfde volgorde, met de vertalingen ingevuld. Je kunt het op dezelfde manier terugzetten via het scherm met vertaalopdrachten van WPML als waarop je het hebt geëxporteerd.

Twee aanbevelingen op basis van de bestandsstructuur. Importeer eerst één bestand en controleer het bericht in WordPress voordat je het hele archief vastlegt. Een verkeerd geplaatste tekst van een pagebuilder valt namelijk veel makkelijker op wanneer je de pagina bekijkt dan in XML. En bepaal vóór het importeren wat je met de slugs doet, niet erna: als je een gepubliceerde URL wijzigt, moet je de omleiding blijven onderhouden.

Waarvoor dit wel en niet geschikt is

Gebruik dit voor het bulkwerk. Vierenvijftig? Nee: 44 berichten in vier talen is precies het soort klus dat met de hand ellendig is en in één keer heel gewoon. Laat mensen daarna controleren waar dat echt iets oplevert: je pagina’s met het meeste verkeer en alles waarbij de formulering zelf het product is. Veel teams gebruiken AI Glot voor een eerste vertaalronde en laten de uitvoer daarna nakijken. Zo zet je een expert goed in, in plaats van die een middag in XML te laten doorbrengen.

Schakel voor een homepage een vertaler in. Maar besteed niet je hele week aan het archief van 44 berichten dat je vanochtend hebt geëxporteerd.

De exportstructuur die hier wordt beschreven, is vastgesteld aan de hand van een echte WPML-export van 44 berichten in vier taalcombinaties. Je export kan afwijken als je site een andere paginabouwer of SEO-plugin gebruikt. Ook hangen de unit-id’s af van je eigen plugins. De map posts/, het XLIFF 1.2-formaat, de taalcombinatie per bestand en de doelen die zijn gekopieerd uit de brontekst, kwamen in alle 44 bestanden overeen.