WordPress JSON Vertaling: JavaScript voor de Blok-editor Vertalen

Je hebt je plugin vertaald. De PHP-teksten verschijnen perfect in de admininstellingen, de frontend-sjablonen, de e-mailmeldingen – alles is gelokaliseerd. Dan open je de blok-editor, en elk label in je aangepaste Gutenberg-blok is koppig, spottend Engels. De knop "Item Toevoegen", de koppen van het inspectiepaneel, de placeholdertekst. Je .mo-bestand is geladen. Waarom worden deze teksten dan niet vertaald?

Omdat JavaScript-teksten sinds WordPress 5.0 en de komst van Gutenberg helemaal niet meer uit je .mo-bestand komen. Ze hebben een volledig apart, per-script WordPress JSON-vertalingsbestand nodig – en als je dat niet genereert, blijft je blok-editor in het Engels, hoe compleet je .po-bestand ook is. Dit is een van de meest voorkomende en verwarrende lokalisatiehiaten in de moderne WordPress-ontwikkeling. Deze gids legt precies uit waarom het gebeurt, hoe het JSON-vertalingssysteem werkt, de MD5-gehashte bestandsnamen die iedereen in de war brengen, en de complete toolchain om het probleem op te lossen.

Waarom de teksten in je blok-editor Engels blijven

Kort antwoord: PHP en JavaScript gebruiken twee volledig verschillende systemen voor het aanleveren van vertalingen in WordPress, en je .mo-bestand voedt alleen het PHP-systeem.

Twee vertaalsystemen, één plugin

Wanneer WordPress load_plugin_textdomain() uitvoert, leest het je gecompileerde .mo-bestand in het PHP-geheugen. Elke __(), _e() en _x() aanroep in je PHP-code zoekt de vertaling daarin op. Dit werkt omdat PHP server-side rendert – de .mo-data bevindt zich direct in hetzelfde proces.

JavaScript is anders. Je blokcode draait in de browser, lang nadat PHP klaar is. Het kan geen server-side .mo-bestand bereiken. In plaats daarvan verwacht het @wordpress/i18n pakket – het JS-equivalent van Gettext, dat __(), _x() en sprintf() beschikbaar stelt aan je scripts – dat vertalingen worden aangeleverd als een JSON payload, gekoppeld aan het specifieke script dat ze nodig heeft.

Wat gebeurt er met een onvertaalde JS-string

Dus een blok met teksten zoals dit:

import { __ } from '@wordpress/i18n';

registerBlockType( 'myplugin/feature-box', {
    title: __( 'Feature Box', 'myplugin' ),
    edit: () => {
        return <Button>{ __( 'Add Item', 'myplugin' ) }</Button>;
    },
} );

zal nooit "Feature Box" of "Add Item" vinden in je .mo-bestand, omdat de browser .mo-bestanden nooit leest. Die teksten moeten als JSON arriveren, gekoppeld aan deze exacte scripthandle. Als je dat niet hebt ingesteld, retourneren de JS __() aanroepen eenvoudigweg het originele Engels – stilzwijgend, zonder fout in de console.

JSON-vertalingen koppelen met wp_set_script_translations()

De brug tussen je script en zijn JSON-vertalingen is één PHP-functie: wp_set_script_translations(). Het antwoord op "hoe weet WordPress welk JSON-bestand bij welk script hoort" is: jij vertelt het, door het script te registreren en vervolgens zijn tekst-domein en de map waar de JSON zich bevindt, te declareren.

Het script en zijn vertalingsmap registreren

add_action( 'init', function () {
    wp_register_script(
        'myplugin-editor',
        plugins_url( 'build/index.js', __FILE__ ),
        array( 'wp-blocks', 'wp-i18n', 'wp-element' ),
        '1.0.0'
    );

    // Tell WordPress where this script's JSON translations live
    wp_set_script_translations(
        'myplugin-editor',        // the registered script handle
        'myplugin',               // text domain
        plugin_dir_path( __FILE__ ) . 'languages'
    );
} );

Wanneer de editor myplugin-editor laadt, weet WordPress nu dat het in je languages/-map moet zoeken naar een JSON-bestand dat overeenkomt met dit script en de locale van de huidige gebruiker. Als het er een vindt, injecteert het de vertalingen voordat je script draait, en de JS __() aanroepen worden correct opgelost. De handle die je doorgeeft, moet exact overeenkomen met een geregistreerd script – een niet-overeenkomende of ontbrekende handle is de op één na meest voorkomende reden dat vertalingen stilzwijgend falen.

De MD5-gehashte bestandsnaam die niemand verwacht

Hier is het detail dat bijna iedereen van het spoor brengt. Het JSON-bestand waar WordPress naar zoekt, heeft geen nette naam zoals myplugin-fr_FR.json. Het is genoemd met een MD5-hash van het bronpad van het script:

Het bestandsnaam-patroon ontcijferen

myplugin-fr_FR-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.json

Het patroon is {textdomain}-{locale}-{md5}.json, waarbij de hash de MD5 is van het relatieve pad naar het scriptbestand (bijvoorbeeld build/index.js) zoals geregistreerd. WordPress berekent deze hash tijdens runtime om de juiste JSON te vinden voor het juiste script. Als je je bestand handmatig een naam geeft, zal WordPress het niet vinden, en zul je zweren dat het systeem kapot is, terwijl het gewoon op zoek is naar een andere bestandsnaam.

Je berekent de hash niet zelf. De WP-CLI i18n-opdracht doet dit voor jou, wat precies de reden is waarom je de tools moet gebruiken in plaats van deze bestanden handmatig te maken. Het begrijpen dat de hash bestaat, is echter wat je uren bespaart wanneer een JSON-bestand aanwezig is in languages/ maar toch wordt genegeerd – het is bijna altijd een bestandsnaam-hash mismatch omdat het scriptpad is gewijzigd.

De complete workflow: van make-pot naar make-json

Het goede nieuws is dat je je vertalingen bewaart in dezelfde .po-bestanden die je al gebruikt. De JSON is een afgeleid artefact dat aan het einde wordt gegenereerd. Het antwoord op "moet ik JS-teksten apart bijhouden" is nee – ze leven in dezelfde .pot/.po als je PHP-teksten, en één extra commando splitst de JS-teksten uit in JSON.

De vier-commando-pipeline

Hier is de complete pipeline:

# 1. Extract ALL translatable strings (PHP and JS) into one template
wp i18n make-pot . languages/myplugin.pot

# 2. Translate languages/myplugin-fr_FR.po as usual (Poedit, AI, etc.)

# 3. Compile the .mo for PHP strings (server-side, as always)
wp i18n make-mo languages/

# 4. Generate the MD5-hashed JSON files for JS strings
wp i18n make-json languages/ --no-purge

make-pot in stap 1 is slim genoeg om zowel je .php-bestanden als je .js/.jsx broncode te scannen, zodat één .po-bestand per locale alles bevat. make-json in stap 4 leest elk vertaald .po-bestand, vindt de vermeldingen die afkomstig zijn van JavaScript-bestanden en schrijft één correct gehashte JSON per script uit. De --no-purge vlag zorgt ervoor dat de JS-teksten ook in je .po blijven, zodat een latere make-mo ze niet verliest – zonder deze vlag verwijdert make-json JS-vermeldingen uit het .po-bestand, wat mensen verrast die de commando's in de verkeerde volgorde uitvoeren.

Een gegenereerd JSON-bestand ziet eruit als een Jed-formaat vertalingsset:

{
  "translation-revision-date": "2026-06-12 10:00+0000",
  "generator": "WP-CLI/2.x",
  "domain": "messages",
  "locale_data": {
    "messages": {
      "": { "domain": "messages", "lang": "fr_FR" },
      "Feature Box": [ "Bloc fonctionnalité" ],
      "Add Item": [ "Ajouter un élément" ]
    }
  }
}

WordPress leest locale_data en voedt dit aan @wordpress/i18n voordat je script draait. Nu retourneert __( 'Add Item', 'myplugin' ) in de browser Ajouter un élément, en is je blok-editor eindelijk gelokaliseerd.

Hoe dit verschilt van i18next JSON

Beide systemen gebruiken JSON, beide zijn gericht op JavaScript, en die oppervlakkige gelijkenis veroorzaakt echte verwarring. Ze zijn niet uitwisselbaar. WordPress blok-editor JSON is een van Gettext afgeleide, MD5-gehashte, per-script payload die wordt geconsumeerd door @wordpress/i18n. i18next JSON is een plat of genest key-value bestand dat wordt geconsumeerd door react-i18next of next-intl, met zijn eigen {{interpolation}} syntaxis en meervoudssleutelconventies.

Als je werkt in puur React of Next.js buiten WordPress, wil je de i18next-aanpak, die we behandelen in i18next JSON vertalen in React en Next.js. Binnen WordPress wil je de make-json-workflow hierboven. Ze door elkaar halen – bijvoorbeeld door handmatig platte i18next-stijl JSON te schrijven en te verwachten dat wp_set_script_translations() het laadt – zal simpelweg niet werken, omdat WordPress zoekt naar het gehashte Jed-formaat, niet naar willekeurige key-value-paren.

Eén bron, elk formaat dat je nodig hebt

De kwetsbaarheid hiervan zit in de vertaalstap in het midden. Je .po-bestand voedt zowel de .mo (PHP) als de JSON (JavaScript), dus één mislukte vertaling – een verminkte %s, een kapotte <strong>-tag, een hernoemde meervoudsvorm – vergiftigt beide outputs tegelijk. En omdat JS-teksten asynchroon in de browser worden geladen, uit zich een structurele fout daar vaak als een leeg label of een harde crash in plaats van een elegante fallback.

Eén upload, PHP en JavaScript gedekt

Dit is waar een vertaalpipeline die de Gettext-structuur begrijpt, zijn plaats verdient. SimplePoTranslate neemt één bron-.po of .pot en produceert schone, vertaalde uitvoer in meerdere formaten vanuit één upload – .po, .mo, .json, .php en .xliff – zodat je geen aparte tools voor je PHP- en JavaScript-lagen hoeft samen te voegen. De Syntax Locking houdt %s, %1$s, {count} en inline HTML op hun plaats, wat extra belangrijk is voor blok-editor teksten waar een kapotte placeholder het hele editorpaneel kan uitschakelen. We gaan dieper in op het 'één bron, veel outputs'-model in één bestand erin, vijf formaten eruit.

Je voert nog steeds make-json uit om de gehashte bestanden te produceren die WordPress verwacht – die stap is WordPress-specifiek en blijft in je build. Maar de vertaling zelf, het deel dat het meest waarschijnlijk je JS-teksten zal breken, wordt afgehandeld door een context-bewuste engine in plaats van een zoek-en-vervang-script.

Conclusie

De reden dat je blok-editor Engels blijft, is structureel, geen bug: WordPress JSON-vertaling is een apart leveringssysteem van het .mo-bestand, specifiek gebouwd omdat browsers geen server-side Gettext-data kunnen lezen. Zodra je begrijpt dat JavaScript-teksten per-script, MD5-gehashte JSON nodig hebben, gegenereerd door wp i18n make-json en gekoppeld met wp_set_script_translations(), is de oplossing mechanisch. Bewaar je teksten in één .po, compileer de .mo voor PHP, en voer make-json uit voor JS.

Doe de vertaalstap goed en beide outputs volgen. Doe het fout en je debugt een middag lang lege editorpanelen.

Klaar om je WordPress JSON- en PHP-teksten vanuit één schone bron te vertalen? Probeer SimplePoTranslate gratis – geen creditcard vereist. De gratis laag vertaalt echte .po- en .pot-bestanden met placeholder-veilige Syntax Locking, zodat de teksten van je blok-editor correct worden geleverd.