Hoe maak je een .pot-bestand voor een thema of plugin?

Je hebt net een WordPress-plugin voltooid die je met de wereld wilt delen. De code werkt, de functies zijn solide en iemand uit Duitsland vraagt per e-mail hoe hij deze naar het Duits kan vertalen. Je wijst ze naar de map languages en realiseert je dat er niets is. Geen sjabloon, geen strings, geen enkele manier voor een vertaler om zelfs maar te weten wat er vertaald moet worden. Je plugin is technisch gezien alleen in naam "translation-ready".

Elk vertaalbaar WordPress-project begint met één bestand: het .pot-sjabloon. Voordat iemand een Duitse, Franse of Japanse versie kan produceren, moet je een POT-bestand maken dat elke gebruikergerichte string in je code opsomt. Sla deze stap over en vertalers moeten je bronregel voor regel lezen, waarbij ze raden welke strings überhaupt zichtbaar moeten zijn.

Deze gids behandelt de twee helften van de taak: je broncode voorbereiden zodat strings vindbaar zijn, en vervolgens het .pot-bestand zelf genereren met drie verschillende tools. We zullen WP-CLI, Poedit en de legacy makepot/grunt-aanpak gebruiken, met echte commando's die je kunt kopiëren. Aan het einde heb je een schoon sjabloon dat klaar is om aan elke vertaler te geven.

Stap één: Markeer je strings als vertaalbaar

Voordat je een POT-bestand kunt maken, moet elke string die een gebruiker mogelijk ziet, worden omhuld door een Gettext-functie. Een scanner kan alleen strings extraheren die hij herkent, en hij herkent ze aan deze functieaanroepen — gewone stringliteralen zijn voor hem onzichtbaar.

WordPress biedt een reeks lokalisatiefuncties, elk voor een iets andere context:

// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );

// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );

// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );

// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );

Het tweede argument in elke aanroep — 'my-plugin' — is het tekstdomein. Het groepeert alle strings van een plugin of thema onder één namespace, zodat WordPress weet welk .mo-bestand ervoor geladen moet worden. Elke vertaalbare string in je project moet exact hetzelfde tekstdomein delen, anders worden sommige strings nooit vertaald.

Gebruik _x() wanneer een woord dubbelzinnig is. Het Engelse "Post" kan een zelfstandig naamwoord of een werkwoord zijn, en veel talen vertalen ze anders. Context-strings laten vertalers ze onderscheiden. En gebruik de esc_html__() en esc_attr__() varianten wanneer de vertaalde string in HTML wordt afgedrukt, zodat je tegelijkertijd veilig en gelokaliseerd blijft.

Er zijn een paar gewoonten die je strings extraheerbaar houden. Geef altijd een gewone stringliteraal door als het eerste argument — nooit een variabele of een concatenatie zoals __( 'Hello ' . $name, 'my-plugin' ), omdat de scanner de brontekst statisch leest en geen runtime-waarden kan oplossen. Gebruik voor zinnen met een getal _n() zodat meervoudsvormen correct worden vastgelegd, en voor zinnen met een dynamische waarde gebruik je sprintf() rond een placeholder zoals %s in plaats van strings aan elkaar te plakken. Consistentie hierin zorgt ervoor dat de volgende stap — het genereren van het sjabloon — een compleet, bruikbaar resultaat oplevert.

Stap twee: Declareer het tekstdomein in je header

WordPress heeft twee header-velden nodig om te weten waar je vertalingen zich bevinden: het Tekstdomein en het Domeinpad. Stel deze in het hoofdbestand van je plugin of de style.css van je thema in, en WordPress zal automatisch het juiste .mo-bestand laden tijdens runtime.

<?php
/**
 * Plugin Name:       My Plugin
 * Description:        A perfectly localized WordPress plugin.
 * Version:            1.0.0
 * Requires at least: 6.4
 * Text Domain:       my-plugin
 * Domain Path:       /languages
 */

Het Tekstdomein moet overeenkomen met de string die je aan elke __() en _e() aanroep hebt doorgegeven — hier my-plugin. Het Domeinpad vertelt WordPress welke submap de vertaalbestanden bevat, relatief ten opzichte van de plugin- of themahoofdmap. De conventie is /languages, en dat is precies waar je gegenereerde .pot zou moeten staan.

Met ingepakte strings en gedeclareerde header is je code klaar om te scannen. Het bredere plaatje van het voorbereiden van een project voor vertaling — inclusief thema's die niet van jou zijn — wordt behandeld in hoe je elk WordPress-thema lokaliseert, zelfs als je geen ontwikkelaar bent.

Hoe genereer je het .pot-bestand? Drie methoden

Je genereert een .pot-bestand door een scanner over je broncode te laten lopen die elke Gettext-aanroep vindt en de strings naar een sjabloon schrijft. Hier zijn drie betrouwbare manieren om dit te doen, van de moderne standaard tot de legacy-aanpak.

Methode 1: WP-CLI (aanbevolen)

De officiële, moderne manier om een POT-bestand te maken is WP-CLI met het i18n-commando. Het wordt geleverd als onderdeel van de kern-tools van WordPress, begrijpt PHP- en JavaScript-strings en produceert een standaarden-conform sjabloon in één regel.

# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot

# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin

# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules

Het eerste argument is de bronmap (. voor de huidige map), en het tweede is het uitvoerpad. WP-CLI doorzoekt je bestanden, extraheert elke ingepakte string, registreert het bronbestand en regelnummer als een opmerking, en schrijft het .pot-bestand. Het is snel, scriptbaar en de juiste keuze voor elk serieus project.

Het gegenereerde sjabloon bevat nuttige metadata die je kunt afstemmen met extra vlaggen. Geef --headers door om de projectnaam, versie en het contactadres van de vertalers in te stellen, zodat het .pot-headerblok correct wordt ingevuld in plaats van als placeholders te blijven staan. WP-CLI extraheert ook automatisch JavaScript-strings uit wp_set_script_translations()-aanroepen, wat belangrijk is voor moderne blokthema's en Gutenberg-plugins waar de helft van de gebruikergerichte tekst in JavaScript in plaats van PHP leeft. Eén commando dekt beide werelden.

Methode 2: Poedit (grafisch)

Als je de voorkeur geeft aan een desktop-app, kan Poedit je bron scannen en het sjabloon genereren via de interface. Open Poedit, kies ervoor om een nieuwe vertaling te maken van POT of scan bronnen direct, wijs naar je projectmap en configureer de bronzoekwoorden (__, _e, _x, esc_html__) onder de cataloguseigenschappen.

Poedit's functies voor bron-scanning en .pot-generatie zijn beschikbaar in de Pro-editie, maar de workflow is vriendelijk voor ontwikkelaars die liever klikken dan commando's typen. Het is ook een solide editor voor de vertaalfase die volgt. Poedit en verschillende andere desktopopties worden vergeleken in top 5 gratis tools om PO-bestanden te bewerken en vertalen op Mac en Windows.

Methode 3: makepot / grunt (legacy)

Vóór WP-CLI was de standaardtool het makepot.php-script uit de WordPress i18n-tools repository, vaak gekoppeld aan een Grunt build-taak met grunt-wp-i18n. Je zult het nog steeds tegenkomen in oudere plugins en thema's.

# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot

Het werkt, maar het wordt minder onderhouden dan WP-CLI en is langzamer om in te stellen. Gebruik het alleen als je een legacy-project onderhoudt dat er al van afhankelijk is; voor iets nieuws, geef de voorkeur aan wp i18n make-pot.

Houd het sjabloon up-to-date als je code verandert

Een .pot-bestand is een momentopname van je strings. Elke keer dat je een functie toevoegt, een label wijzigt of een typfout in een zichtbare string corrigeert, wordt het sjabloon verouderd en missen vertalers de nieuwe formulering.

Maak regeneratie onderdeel van je release-routine. Voer wp i18n make-pot opnieuw uit vóór elke versie-update, en voeg vervolgens het vernieuwde sjabloon samen met bestaande vertalingen met wp i18n update-po of msgmerge, zodat vertalers hun voltooide werk behouden en alleen de nieuwe hiaten zien. Behandel het .pot-bestand als een build-artefact dat je regenereert, niet als een bestand dat je handmatig bewerkt.

Een verouderd sjabloon veroorzaakt een subtiele, frustrerende storing: nieuwe strings verschijnen in het Engels, zelfs op een "volledig vertaalde" site, omdat ze nooit in het .pot-bestand stonden waarmee de vertaler werkte. Dit voorkomen is net zo eenvoudig als het scripten van de regeneratie in je build, zodat het sjabloon nooit achterop kan raken bij de code. Sommige teams voegen een CI-check toe die de build laat mislukken als het regenereren van het .pot-bestand een verschil produceert, wat garandeert dat het gecommitte sjabloon altijd overeenkomt met de huidige bron.

Zodra vertalers voltooide .po-bestanden terugsturen, moeten deze nog steeds worden gecompileerd naar het binaire .mo-bestand dat WordPress daadwerkelijk laadt — en als je de hele download-vertaal-hercompileer-lus liever wilt overslaan, kan een cloudtool dit van begin tot eind afhandelen. SimplePoTranslate accepteert je .pot direct, vertaalt het met Context-Aware AI die begrijpt wat elke string betekent in je interface, en retourneert een enkele ZIP met de .po, .mo en meer die al zijn gebouwd en benoemd. De Syntax Locking bevriest placeholders zoals %s en %1$s, zodat je variabelen nooit breken in de vertaling.

Samenvatting

Om op de juiste manier een POT-bestand te maken, moet je eerst je code vindbaar maken — wikkel elke zichtbare string in __(), _e(), _x() of een escaping-variant, allemaal met hetzelfde tekstdomein, en declareer dat domein plus het Domain Path in je header. Genereer vervolgens het sjabloon met WP-CLI voor nieuwe projecten, Poedit als je de voorkeur geeft aan een GUI, of makepot alleen bij het onderhouden van legacy-code.

Genereer vroeg, regenereer vaak, en laat je sjabloon nooit achterop raken bij je code. Een actueel .pot-bestand is het verschil tussen een plugin die echt klaar is voor de wereld en een die alleen beweert dat te zijn.

Klaar om je .pot-sjabloon om te zetten in voltooide vertalingen zonder het handmatige compileerwerk? Probeer SimplePoTranslate gratis — geen creditcard nodig. Upload je sjabloon op de gratis laag en download kant-en-klare vertaalbestanden in enkele minuten.