WordPress JSON Fordítás: Blokkszerkesztő JavaScript fordítása

Lefordította a bővítményét. A PHP szövegek tökéletesen megjelennek az admin beállításokban, a frontend sablonokban, az e-mail értesítésekben – minden lokalizálva van. Aztán megnyitja a blokkszerkesztőt, és az egyéni Gutenberg blokkjában minden címke makacsul, gúnyosan angolul van. Az „Add Item” gomb, az ellenőrzőpanel fejléc, a helyőrző szöveg. A .mo fájlja betöltve van. Akkor miért nem fordítódnak ezek a szövegek?

Mivel a WordPress 5.0 és a Gutenberg megjelenése óta a JavaScript szövegek egyáltalán nem a .mo fájljából származnak. Teljesen különálló, szkriptenkénti WordPress JSON fordítási fájlra van szükségük – és ha nem generálja azt, a blokkszerkesztője angol marad, függetlenül attól, mennyire teljes a .po fájlja. Ez az egyik leggyakoribb és legzavaróbb lokalizációs hiányosság a modern WordPress fejlesztésben. Ez az útmutató pontosan elmagyarázza, miért történik ez, hogyan működik a JSON fordítási rendszer, az MD5-hash-elt fájlneveket, amelyek mindenkit megzavarnak, és a teljes eszköztárat a probléma megoldásához.

Miért maradnak angolok a blokkszerkesztő szövegei?

Rövid válasz: A PHP és a JavaScript két teljesen eltérő fordítási rendszert használ a WordPressben, és a .mo fájlja csak a PHP-t táplálja.

Két fordítási rendszer, egy bővítmény

Amikor a WordPress futtatja a load_plugin_textdomain()-t, beolvassa a lefordított .mo fájlját a PHP memóriájába. Minden __(), _e() és _x() hívás a PHP kódjában ott keresi a fordítását. Ez azért működik, mert a PHP szerveroldalon renderel – a .mo adatok ott vannak ugyanabban a folyamatban.

A JavaScript más. A blokk kódja a böngészőben fut, jóval azután, hogy a PHP befejezte. Nem fér hozzá egy szerveroldali .mo fájlhoz. Ehelyett az @wordpress/i18n csomag – a Gettext JS megfelelője, amely elérhetővé teszi a __(), _x() és sprintf() függvényeket a szkriptjei számára – elvárja, hogy a fordítások JSON tartalomként kerüljenek kézbesítésre, a konkrét szkripthez csatolva, amelynek szüksége van rájuk.

Mi történik egy lefordítatlan JS szöveggel?

Tehát egy ilyen szövegeket tartalmazó blokk:

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

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

soha nem fogja megtalálni a „Feature Box” vagy az „Add Item” szöveget a .mo fájljában, mert a böngésző soha nem olvassa a .mo fájlokat. Ezeknek a szövegeknek JSON-ként kell megérkezniük, pontosan ehhez a szkript azonosítóhoz (handle) kötve. Ha ezt nem állította be, a JS __() hívások egyszerűen az eredeti angolt adják vissza – csendben, konzolhiba nélkül.

JSON fordítások összekötése a wp_set_script_translations() függvénnyel

A szkriptje és a JSON fordításai közötti híd egyetlen PHP függvény: wp_set_script_translations(). Arra a kérdésre, hogy „honnan tudja a WordPress, melyik JSON fájl melyik szkripthez tartozik”, a válasz: Ön mondja meg neki, a szkript regisztrálásával, majd a szöveg tartományának és annak a mappának a deklarálásával, ahol a JSON található.

A szkript és a fordítási mappa regisztrálása

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'
    );
} );

Amikor a szerkesztő betölti a myplugin-editor-t, a WordPress most már tudja, hogy a languages/ mappában keressen egy JSON fájlt, amely megfelel ennek a szkriptnek és a jelenlegi felhasználó területi beállításának. Ha talál ilyet, beadja a fordításokat, mielőtt a szkript futna, és a JS __() hívások helyesen oldódnak fel. Az átadott azonosítónak (handle) pontosan meg kell egyeznie egy regisztrált szkriptével – az illesztés nélküli vagy hiányzó azonosító a második leggyakoribb ok, amiért a fordítások csendben elbuknak.

Az MD5-hash-elt fájlnév, amire senki sem számít

Itt van az a részlet, ami szinte mindenkit megzavar. A JSON fájl, amit a WordPress keres, nem valami szépen elnevezett, mint myplugin-fr_FR.json. Hanem a szkript forrásútvonalának egy MD5 hash-ével van elnevezve:

A fájlnév minta dekódolása

myplugin-fr_FR-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.json

A minta {textdomain}-{locale}-{md5}.json, ahol a hash a szkriptfájl (például build/index.js) regisztrált relatív útvonalának MD5-je. A WordPress futásidőben számítja ki ezt a hasht, hogy megtalálja a megfelelő JSON-t a megfelelő szkripthez. Ha kézzel nevezi el a fájlt, a WordPress nem fogja megtalálni, és esküdni fog, hogy a rendszer elromlott, miközben az csak egy másik fájlnevet keres.

Nem Ön számolja ki a hasht. A WP-CLI i18n parancs megteszi Ön helyett, pontosan ezért kell az eszközöket használnia, ahelyett, hogy kézzel készítené ezeket a fájlokat. Annak megértése azonban, hogy a hash létezik, órákat spórol meg Önnek, amikor egy JSON fájl jelen van a languages/ mappában, de mégis figyelmen kívül hagyják – szinte mindig fájlnév-hash eltérésről van szó, mert a szkript útvonala megváltozott.

A teljes munkafolyamat: make-pot-tól make-json-ig

A jó hír az, hogy a fordításokat ugyanazokban a .po fájlokban tarthatja, amelyeket már használ. A JSON egy származtatott, a végén generált műtermék. Arra a kérdésre, hogy „külön kell-e tartanom a JS szövegeket”, a válasz nem – ugyanabban a .pot/.po fájlban élnek, mint a PHP szövegei, és egy extra parancs szétválasztja a JS-eket JSON-ba.

A négyparancsos folyamat

Íme a teljes folyamat:

# 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

Az 1. lépésben lévő make-pot elég okos ahhoz, hogy beolvassa mind a .php fájlokat, mind a .js/.jsx forrást, így egyetlen .po fájl területi beállításonként mindent tartalmaz. A 4. lépésben lévő make-json beolvassa az egyes lefordított .po fájlokat, megkeresi a JavaScript fájlokból származó bejegyzéseket, és minden szkripthez kiír egy helyesen hash-elt JSON-t. A --no-purge jelző a JS szövegeket is megtartja a .po fájlban, így egy későbbi make-mo nem veszíti el őket – anélkül a make-json eltávolítja a JS bejegyzéseket a .po fájlból, ami meglepi azokat, akik rossz sorrendben futtatják a parancsokat.

Egy generált JSON fájl így néz ki, mint egy Jed-formátumú fordítási készlet:

{
  "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" ]
    }
  }
}

A WordPress beolvassa a locale_data-t, és átadja az @wordpress/i18n-nek, mielőtt a szkriptje futna. Most a __( 'Add Item', 'myplugin' ) a böngészőben Ajouter un élément értéket ad vissza, és a blokkszerkesztője végre lokalizálva van.

Miben tér el ez az i18next JSON-tól?

Mindkét rendszer JSON-t használ, mindkettő JavaScriptet céloz meg, és ez a felületi hasonlóság valós zavart okoz. Nem felcserélhetők. A WordPress blokkszerkesztő JSON egy Gettext-ből származó, MD5-hash-elt, szkriptenkénti tartalom, amelyet az @wordpress/i18n fogyaszt el. Az i18next JSON egy lapos vagy beágyazott kulcs-érték fájl, amelyet a react-i18next vagy next-intl fogyaszt el, saját {{interpolation}} szintaxissal és többes számú kulcskonvenciókkal.

Ha sima React vagy Next.js környezetben dolgozik a WordPressen kívül, akkor az i18next megközelítést szeretné, amelyet a translating i18next JSON in React and Next.js cikkben tárgyalunk. A WordPressen belül a fenti make-json munkafolyamatot szeretné. Összekeverni őket – például kézzel írni lapos i18next-stílusú JSON-t, és elvárni, hogy a wp_set_script_translations() betöltse azt – egyszerűen nem fog működni, mert a WordPress a hash-elt Jed formátumot keresi, nem tetszőleges kulcs-érték párokat.

Egy forrás, minden szükséges formátum

Ennek az egésznek a gyenge pontja a középen lévő fordítási lépés. A .po fájlja táplálja mind a .mo (PHP), mind a JSON (JavaScript) kimenetet, így egyetlen elrontott fordítás – egy eltorzult %s, egy törött <strong> tag, egy átnevezett többes számú forma – egyszerre mérgezi mindkét kimenetet. És mivel a JS szövegek aszinkron módon töltődnek be a böngészőben, egy strukturális hiba ott gyakran üres címkeként vagy teljes összeomlásként jelentkezik, nem pedig elegáns visszalépésként.

Egy feltöltés, PHP és JavaScript lefedve

Itt nyeri el a helyét egy olyan fordítási folyamat, amely megérti a Gettext struktúrát. SimplePoTranslate egyetlen forrás .po vagy .pot fájlból tiszta, lefordított kimenetet produkál több formátumban egyetlen feltöltésből – .po, .mo, .json, .php és .xliff – így nem kell külön eszközöket összefűznie a PHP és JavaScript rétegeihez. A Syntax Locking funkciója a helyén tartja a %s, %1$s, {count} és az inline HTML elemeket, ami kétszeresen fontos a blokkszerkesztő szövegei esetében, ahol egy hibás helyőrző az egész szerkesztőpanelt tönkreteheti. Mélyebben belemerülünk az egy forrás, több kimenet modellbe a one file in, five formats out cikkünkben.

Továbbra is futtatja a make-json-t, hogy előállítsa a WordPress által elvárt hash-elt fájlokat – ez a lépés WordPress-specifikus, és a buildjében marad. De maga a fordítás, az a rész, amely a leginkább tönkreteheti a JS szövegeit, egy kontextus-tudatos motor kezeli, nem pedig egy keresés-és-csere szkript.

Konklúzió

Az ok, amiért a blokkszerkesztője angol marad, strukturális, nem hiba: a WordPress JSON fordítás egy különálló kézbesítési rendszer a .mo fájltól, amelyet kifejezetten azért hoztak létre, mert a böngészők nem tudják olvasni a szerveroldali Gettext adatokat. Amint megérti, hogy a JavaScript szövegeknek szkriptenkénti, MD5-hash-elt JSON-ra van szükségük, amelyet a wp i18n make-json generál, és a wp_set_script_translations()-szal kapcsolódnak, a javítás mechanikus. Tartsa a szövegeit egyetlen .po fájlban, fordítsa le a .mo-t PHP-hez, és futtassa a make-json-t JS-hez.

Végezze el helyesen a fordítási lépést, és mindkét kimenet rendben lesz. Ha elrontja, akkor egy délutánon át üres szerkesztőpaneleket fog debuggolni.

Készen áll, hogy egyetlen tiszta forrásból fordítsa WordPress JSON és PHP szövegeit? Próbálja ki ingyen a SimplePoTranslate-et – hitelkártya nélkül. Az ingyenes szint valós .po és .pot fájlokat fordít helyőrző-biztos Syntax Locking funkcióval, így a blokkszerkesztő szövegei hibátlanul jelennek meg.