Hoe een WordPress Plugin te Vertalen (Stap voor Stap)

Je hebt de perfecte WordPress plugin voor je project gevonden. Hij doet precies wat je nodig hebt, de recensies zijn lovend, en dan activeer je hem en realiseer je je dat elke knop, label en foutmelding in het Engels is. Je Duitse, Franse of Japanse bezoekers zullen tegen een muur van tekst aanlopen die ze niet kunnen lezen.

Het goede nieuws is dat de meeste goed gebouwde plugins translation-ready zijn, wat betekent dat de ontwikkelaar hun strings in Gettext-functies heeft gewikkeld, specifiek zodat mensen zoals jij ze kunnen vertalen. De uitdaging is om te weten waar de bestanden zich bevinden, hoe je je vertaling moet noemen en waar je deze moet plaatsen, zodat de volgende plugin-update je werk niet wist.

Deze gids laat je zien hoe je een WordPress plugin vertaalt van begin tot eind: het vinden van het tekstdomein en de taalfolder, het verkrijgen of genereren van de .pot-template, het bouwen van correct benoemde .po- en .mo-bestanden, en het plaatsen ervan waar WordPress ze betrouwbaar zal laden. We zullen ook het enige type plugin behandelen dat deze aanpak niet volledig kan vertalen, zodat je geen uren verspilt aan een onmogelijke zaak.

Hoe vind je de vertaalbestanden van een plugin?

Voordat je iets vertaalt, heb je twee stukjes informatie van de plugin nodig: het tekstdomein en de languages folder. Het tekstdomein is de unieke string die de plugin gebruikt om zijn eigen vertalingen te identificeren, en de languages folder is waar de brontemplate zich bevindt.

De languages folder en het tekstdomein lokaliseren

Open de plugin-directory op wp-content/plugins/your-plugin/ en zoek naar een submap /languages. Daarbinnen vind je meestal een .pot-bestand, de lege template die elke vertaalbare string bevat.

Om het tekstdomein te bevestigen, open je het hoofd-PHP-bestand van de plugin en kijk je naar het headerblok:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Hier is het tekstdomein awesome-plugin. Deze waarde is cruciaal, want je vertaalbestanden moeten deze in hun naam opnemen, anders zal WordPress ze nooit aan de plugin koppelen. Je zult het ook terugzien in elke string-aanroep door de code heen:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Dat tweede argument, awesome-plugin, is opnieuw het tekstdomein. Elke string die dit gebruikt, kan worden vertaald door je catalogus. Als een string in de interface van de plugin deze wrapper mist, bijvoorbeeld een ontwikkelaar die echo 'Save' zonder __() heeft hardcoded, dan is die string helemaal niet vertaalbaar, en geen enkel .po-bestand kan deze bereiken. De meeste gerenommeerde plugins wrappen alles correct, maar als je een of twee koppige strings opmerkt die weigeren te vertalen, is een ontbrekende Gettext-wrapper in de bron een waarschijnlijke oorzaak.

Een snelle manier om te peilen of een plugin echt translation-ready is, is door de vermelding op de WordPress.org-directory te controleren, die een vertaalpercentage toont en linkt naar een /languages-template. Een plugin met een actief vertaalproject heeft veel meer kans op schone, volledig gewrapte strings dan een verlaten plugin.

Wat als de plugin geen POT-bestand heeft?

Sommige plugins worden geleverd zonder een .pot-template. Als de /languages-map leeg is of ontbreekt, moet je zelf de template genereren door de broncode te scannen op vertaalbare strings.

Het standaardhulpmiddel hiervoor is WP-CLI, dat elke Gettext-aanroep extraheert naar een nieuwe .pot.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

Dit commando doorloopt de PHP- en JavaScript-bestanden van de plugin, vindt elke __(), _e(), _n(), en gerelateerde aanroep, en schrijft een complete template. Als je de voorkeur geeft aan een grafische route, kan Poedit Pro op dezelfde manier de broncode scannen. Hoe dan ook, het resultaat is een .pot dat alle bronstrings met lege vertalingen bevat, klaar om te worden omgezet in een echt taalbestand.

Het genereren van je eigen template heeft een verborgen voordeel: het vangt strings op die de oorspronkelijke ontwikkelaar mogelijk vergat op te nemen in een meegeleverde .pot. Plugins evolueren snel, en een template die bij versie 2.1 kwam, mist mogelijk strings die in 2.4 zijn toegevoegd. Regenereren vanuit de huidige bron garandeert dat je catalogus weerspiegelt wat de plugin vandaag de dag daadwerkelijk weergeeft, en niet wat het twee releases geleden weergaf. Als je vertalingen voor een plugin in de loop der tijd onderhoudt, is het opnieuw uitvoeren van make-pot na elke grote update een betrouwbare gewoonte.

De PO- en MO-bestanden aanmaken met de juiste naam

De meest voorkomende fout bij het vertalen van een plugin is de bestandsnaam. WordPress vindt pluginvertalingen door een zeer specifiek patroon te matchen, en één verkeerd teken betekent dat je vertaling volledig wordt genegeerd.

De bestandsnaamformule

Voor pluginvertalingen is het patroon text-domain-locale. Dus voor het awesome-plugin tekstdomein vertaald naar het Duits, moeten de bestanden de volgende naam hebben:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

De locale code is de WordPress site taalcode: de_DE voor Duits, fr_FR voor Frans, es_ES voor Spaans, pt_BR voor Braziliaans Portugees. Als de locale verkeerd is, slaat WordPress je bestand stilzwijgend over. Je maakt deze vanuit de .pot-template in een editor zoals Poedit, die het binaire .mo automatisch compileert wanneer je opslaat. Als je nieuw bent met die editor, leidt de complete Poedit gids je stap voor stap door het maken van een vertaling vanuit een template.

Waar de bestanden te plaatsen zodat updates ze niet wissen

Er zijn twee mogelijke locaties, en het kiezen van de juiste is belangrijk.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Gebruik altijd wp-content/languages/plugins/. WordPress controleert deze override directory eerst, en omdat deze buiten de pluginmap ligt, tast het updaten van de plugin je vertalingen nooit aan. Bestanden die in de eigen map van de plugin worden geplaatst, worden overschreven zodra een nieuwe versie wordt geïnstalleerd.

Dit override-gedrag is een van de meest nuttige en minst bekende functies van WordPress-lokalisatie. Het betekent dat je aangepaste of gecorrigeerde vertalingen kunt leveren voor elke third-party plugin zonder deze ooit te forken, en je wijzigingen zijn volledig update-veilig. Als je meerdere client sites beheert die dezelfde plugin draaien, kun je zelfs één set override .mo-bestanden bewaren en deze overal implementeren, wetende dat elke site ze automatisch oppikt zolang de locale overeenkomt.

Hoe WordPress je vertaling laadt

Een translation-ready plugin vertelt WordPress om zijn catalogus te laden door load_plugin_textdomain() aan te roepen tijdens de initialisatie:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

Voor de meeste moderne plugins op WordPress 4.6 en later hoef je hier niets aan te doen. WordPress laadt automatisch vertalingen vanuit wp-content/languages/plugins/ zolang je bestandsnaam en site locale overeenkomen. Als je voltooide vertaling nog steeds niet verschijnt, is de oorzaak bijna altijd een onjuiste bestandsnaam, een verouderd .mo-bestand of een site taal die is ingesteld op de verkeerde locale. Onze troubleshooting gids voor vertalingen die niet verschijnen behandelt al deze faalpunten.

Plugins die strings in de database opslaan

Hier is de belangrijke beperking. De Gettext-aanpak vertaalt alleen strings die in de code van de plugin staan. Sommige plugins, met name formulierbouwers, page builders en e-commerce-extensies, laten je inhoud (formulierlabels, productattributen, aangepaste berichten) maken die wordt opgeslagen in de WordPress-database. Deze strings zijn door de gebruiker gegenereerde gegevens, geen onderdeel van de .pot, dus een .po-bestand kan ze niet bereiken. Voor database-inhoud heb je een meertalige plugin zoals WPML of Polylang nodig, of de eigen string-vertaalfunctie van de plugin. Test altijd of een bepaalde string in de code of in de database staat voordat je ervan uitgaat dat een .po-bestand het kan oplossen.

Een eenvoudige test vertelt je met welk soort string je te maken hebt. Als de tekst iets is dat je in een instellingenveld hebt getypt, een formulierlabel dat je hebt gemaakt, een aangepast bedankbericht, een productnaam, dan is het database-inhoud en kan een .po-bestand er niets mee doen. Als de tekst deel uitmaakt van de ingebouwde interface van de plugin, knoplabels, validatiefouten, admin-meldingen die met de plugin zelf worden geleverd, dan bevindt deze zich in de code en is een .po-bestand precies het juiste hulpmiddel. Het vroegtijdig trekken van deze lijn bespaart uren frustratie, want geen enkele hoeveelheid perfecte .po-bewerking zal ooit een string vertalen die de plugin tijdens runtime uit de database haalt.

Vertalen op schaal zonder handmatig werk

Eén plugin handmatig in één taal vertalen is beheersbaar. Het vertalen naar tien talen, of het vertalen van een hele stapel plugins voor een klantensite, verandert in dagen repetitief werk, en elke handmatige bewerking riskeert het verhaspelen van een placeholder zoals %s of %1$s en het breken van de uitvoer.

Hier verandert een cloud workflow de berekening. Upload de .po of .pot van de plugin naar SimplePoTranslate, kies je doeltalen, en context-aware AI vertaalt de hele catalogus terwijl Syntax Locking elke placeholder, HTML-tag en code-token bevriest, zodat er niets kan breken. Smart Batching verwerkt grote catalogi in één keer, en je downloadt een ZIP met daarin .po, .mo, .json, .php en .xliff samen, correct geformatteerd en klaar om in wp-content/languages/plugins/ te plaatsen. Het draait volledig in de cloud, dus er is geen desktopinstallatie en geen 'bloat' op je site.

Let op: het vertalen van een plugin verschilt van het vertalen van een thema, dat een iets andere mapconventie en laadfunctie gebruikt. Als een thema je doel is, volg dan in plaats daarvan onze speciale gids over het lokaliseren van elk WordPress-thema, zelfs als je geen ontwikkelaar bent.

Gebruik de handmatige weg als je één plugin en één taal hebt. Gebruik de cloud wanneer je snel veel talen nodig hebt, zonder in te boeten aan placeholder-veiligheid.

Klaar om je WordPress-plugin te vertalen in elke taal die je publiek spreekt, zonder één variabele te breken? Probeer SimplePoTranslate gratis — geen creditcard nodig. Met de gratis versie kun je binnen enkele minuten je eerste plugin .po-bestand vertalen, met Syntax Locking op elke string.