WordPress JSON -käännös: Lohkoeditorin JavaScriptin kääntäminen

Olet kääntänyt lisäosasi. PHP-tekstit näkyvät täydellisesti hallintapaneelin asetuksissa, käyttöliittymän malleissa, sähköposti-ilmoituksissa – kaikki on lokalisoitu. Sitten avaat lohkoeditorin, ja jokainen mukautetun Gutenberg-lohkon teksti on itsepintaisesti, pilkallisesti englanniksi. Esimerkiksi "Lisää kohde" -painike, tarkastuspaneelin otsikot, paikkamerkkiteksti. .mo-tiedostosi on ladattu. Miksi nämä tekstit eivät siis käänny?

Koska WordPress 5.0:n ja Gutenbergin saapumisen jälkeen JavaScript-tekstit eivät enää tule .mo-tiedostostasi lainkaan. Ne tarvitsevat täysin erillisen, skriptikohtaisen WordPress JSON -käännöstiedoston – ja jos et luo sitä, lohkoeditorisi pysyy englanninkielisenä riippumatta siitä, kuinka kattava .po-tiedostosi on. Tämä on yksi yleisimmistä ja hämmentävimmistä lokalisointikatvealueista nykyaikaisessa WordPress-kehityksessä. Tämä opas selittää tarkalleen, miksi näin tapahtuu, miten JSON-käännösjärjestelmä toimii, MD5-hajautetut tiedostonimet, jotka hämmentävät kaikkia, ja täydellisen työkaluketjun sen korjaamiseen.

Miksi lohkoeditorisi tekstit pysyvät englanniksi

Lyhyt vastaus: PHP ja JavaScript käyttävät kaksi täysin erilaista käännösten toimitusjärjestelmää WordPressissä, ja .mo-tiedostosi syöttää vain PHP-järjestelmää.

Kaksi käännösjärjestelmää, yksi lisäosa

Kun WordPress suorittaa load_plugin_textdomain()-funktion, se lukee käännetyn .mo-tiedostosi PHP-muistiin. Jokainen __()-, _e()- ja _x()-kutsu PHP-koodissasi etsii käännöksensä sieltä. Tämä toimii, koska PHP renderöi palvelinpuolella – .mo-data on heti käytettävissä samassa prosessissa.

JavaScript on erilainen. Lohkokoodisi suoritetaan selaimessa, kauan sen jälkeen kun PHP on lopettanut toimintansa. Se ei voi tavoittaa palvelinpuolen .mo-tiedostoa. Sen sijaan @wordpress/i18n-paketti – Gettextin JS-vastine, joka tuo __()-, _x()- ja sprintf()-funktiot skripteihisi – odottaa käännösten toimitettavan JSON-hyötykuormana, joka on liitetty siihen skriptiin, joka niitä tarvitsee.

Mitä tapahtuu kääntämättömälle JS-tekstille

Lohko, jossa on tällaisia tekstejä:

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

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

ei koskaan löydä "Ominaisuuslaatikko" tai "Lisää kohde" -tekstejä .mo-tiedostostasi, koska selain ei koskaan lue .mo-tiedostoja. Nämä tekstit on toimitettava JSON-muodossa, kytkettynä tähän täsmälliseen skriptikahvaan. Jos et ole määrittänyt tätä, JS __()-kutsut palauttavat yksinkertaisesti alkuperäisen englanninkielisen tekstin – hiljaisesti, ilman virhettä konsolissa.

JSON-käännösten yhdistäminen wp_set_script_translations()-funktiolla

Skriptisi ja sen JSON-käännösten välinen silta on yksi PHP-funktio: wp_set_script_translations(). Vastaus kysymykseen "miten WordPress tietää, mikä JSON-tiedosto kuuluu millekin skriptille" on: kerrot sen rekisteröimällä skriptin ja ilmoittamalla sitten sen tekstidomainin ja kansion, jossa JSON sijaitsee.

Skriptin ja sen käännöskansion rekisteröinti

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

Kun editori lataa myplugin-editor-skriptin, WordPress tietää nyt etsiä languages/-kansiostasi JSON-tiedostoa, joka vastaa tätä skriptiä ja nykyisen käyttäjän kieliasetusta. Jos se löytää sellaisen, se injektoi käännökset ennen skriptisi suorittamista, ja JS __()-kutsut ratkeavat oikein. Antamasi kahvan on vastattava täsmällisesti rekisteröityä skriptiä – väärä tai puuttuva kahva on toiseksi yleisin syy, miksi käännökset epäonnistuvat hiljaisesti.

MD5-hajautettu tiedostonimi, jota kukaan ei odota

Tässä on yksityiskohta, joka suistaa lähes kaikki raiteiltaan. JSON-tiedosto, jota WordPress etsii, ei ole nimetty siististi kuten myplugin-fr_FR.json. Se on nimetty skriptin lähdepolun MD5-hajautuksella:

Tiedostonimen mallin purkaminen

myplugin-fr_FR-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.json

Mallina on {textdomain}-{locale}-{md5}.json, missä hajautus on skriptitiedoston suhteellisen polun (esimerkiksi build/index.js) MD5-arvo rekisteröidyssä muodossa. WordPress laskee tämän hajautuksen suorituksen aikana löytääkseen oikean JSON-tiedoston oikealle skriptille. Jos nimeät tiedostosi käsin, WordPress ei löydä sitä, ja vannoisit järjestelmän olevan rikki, kun se vain etsii eri tiedostonimeä.

Et laske hajautusta itse. WP-CLI i18n -komento tekee sen puolestasi, ja juuri siksi sinun on käytettävä työkaluja näiden tiedostojen käsin luomisen sijaan. Hajautuksen olemassaolon ymmärtäminen kuitenkin säästää sinulta tunteja, kun JSON-tiedosto on languages/-kansiossa, mutta se silti jätetään huomiotta – se johtuu lähes aina tiedostonimen hajautusarvon yhteensopimattomuudesta, koska skriptipolku on muuttunut.

Täydellinen työnkulku: make-potista make-jsoniin

Hyvä uutinen on, että säilytät käännöksesi samoissa .po-tiedostoissa, joita jo käytät. JSON on johdettu artefakti, joka luodaan lopussa. Vastaus kysymykseen "pitääkö minun ylläpitää JS-tekstejä erikseen" on ei – ne ovat samassa .pot-/.po-tiedostossa kuin PHP-tekstisi, ja yksi lisäkomento erottaa JS-tekstit JSONiksi.

Neljän komennon putki

Tässä on täydellinen putki:

# 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

Vaiheen 1 make-pot on tarpeeksi älykäs skannaamaan sekä .php-tiedostosi että .js-/.jsx-lähteensi, joten yksi .po-tiedosto kielikohtaisesti sisältää kaiken. Vaiheen 4 make-json lukee jokaisen käännetyn .po-tiedoston, etsii JavaScript-tiedostoista peräisin olevat merkinnät ja kirjoittaa yhden oikein hajautetun JSON-tiedoston skriptiä kohti. --no-purge-lippu pitää JS-tekstit myös .po-tiedostossasi, jotta myöhempi make-mo ei kadota niitä – ilman sitä make-json poistaa JS-merkinnät .po-tiedostosta, mikä yllättää ihmisiä, jotka suorittavat komennot väärässä järjestyksessä.

Luotu JSON-tiedosto näyttää Jed-muotoiselta käännösjoukolta:

{
  "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 lukee locale_data-tiedot ja syöttää ne @wordpress/i18n-paketille ennen skriptisi suorittamista. Nyt __( 'Add Item', 'myplugin' ) selaimessa palauttaa Ajouter un élément, ja lohkoeditorisi on vihdoin lokalisoitu.

Miten tämä eroaa i18next JSONista

Molemmat järjestelmät käyttävät JSONia, molemmat kohdistuvat JavaScriptiin, ja tämä pinnallinen samankaltaisuus aiheuttaa todellista sekaannusta. Ne eivät ole vaihdettavissa keskenään. WordPressin lohkoeditorin JSON on Gettextistä johdettu, MD5-hajautettu, skriptikohtainen hyötykuorma, jota @wordpress/i18n kuluttaa. i18next JSON on tasainen tai sisäkkäinen avain-arvo-tiedosto, jota react-i18next tai next-intl kuluttaa, ja sillä on oma {{interpolation}}-syntaksinsa ja monikkomuotoisten avainten käytäntönsä.

Jos työskentelet pelkän Reactin tai Next.js:n parissa WordPressin ulkopuolella, haluat i18next-lähestymistavan, jota käsittelemme artikkelissa i18next JSONin kääntäminen Reactissa ja Next.js:ssä. WordPressin sisällä haluat yllä mainitun make-json-työnkulun. Niiden sekoittaminen – esimerkiksi käsin kirjoittamalla tasaista i18next-tyylistä JSONia ja odottamalla wp_set_script_translations()-funktion lataavan sen – ei yksinkertaisesti toimi, koska WordPress etsii hajautettua Jed-muotoa, ei mielivaltaisia avain-arvo-pareja.

Yksi lähde, kaikki tarvitsemasi formaatit

Kaiken tämän haavoittuvuus piilee käännösvaiheessa keskellä. .po-tiedostosi syöttää sekä .mo:ta (PHP) että JSONia (JavaScript), joten yksikin epäonnistunut käännös – turmeltunut %s, rikkinäinen <strong>-tagi tai uudelleennimetty monikkomuoto – pilaa molemmat tuotokset kerralla. Ja koska JS-tekstit ladataan asynkronisesti selaimessa, rakenteellinen virhe ilmenee usein tyhjänä tekstinä tai laitteiston kaatumisena sulavan vararatkaisun sijaan.

Yksi lataus, PHP ja JavaScript katettu

Tässä kohtaa käännöstyönkulku, joka ymmärtää Gettext-rakennetta, ansaitsee paikkansa. SimplePoTranslate ottaa yhden lähde-.po- tai .pot-tiedoston ja tuottaa puhtaan, käännetyn tulosteen useassa muodossa yhdellä latauksella – .po, .mo, .json, .php ja .xliff – joten sinun ei tarvitse yhdistellä erillisiä työkaluja PHP- ja JavaScript-kerroksiisi. Sen Syntax Locking pitää %s, %1$s, {count} ja rivin sisäisen HTML:n paikoillaan, mikä on erityisen tärkeää lohkoeditorin tekstien osalta, joissa rikkinäinen paikkamerkki voi kaataa koko editoripaneelin. Syvennymme yhden lähteen, monen tulosteen malliin artikkelissa Yksi tiedosto sisään, viisi formaattia ulos.

Suoritat edelleen make-json-komennon tuottaaksesi hajautetut tiedostot, joita WordPress odottaa – tämä vaihe on WordPress-kohtainen ja pysyy osana rakennusprosessiasi. Mutta itse käännöksen, sen osan, joka todennäköisimmin rikkoo JS-tekstisi, hoitaa kontekstitietoinen moottori etsi ja korvaa -skriptin sijaan.

Yhteenveto

Syy siihen, että lohkoeditorisi pysyy englanninkielisenä, on rakenteellinen, ei virhe: WordPress JSON -käännös on erillinen toimitusjärjestelmä .mo-tiedostosta, ja se on rakennettu nimenomaan siksi, että selaimet eivät voi lukea palvelinpuolen Gettext-dataa. Kun ymmärrät, että JavaScript-tekstit tarvitsevat skriptikohtaisen, MD5-hajautetun JSONin, jonka wp i18n make-json luo ja joka kytketään wp_set_script_translations()-funktiolla, korjaus on mekaaninen. Säilytä tekstit yhdessä .po-tiedostossa, kokoa .mo PHP:lle ja suorita make-json JS:lle.

Tee käännösvaihe oikein, ja molemmat tuotokset seuraavat perässä. Tee se väärin, ja etsit virheitä tyhjistä editoripaneeleista koko iltapäivän.

Oletko valmis kääntämään WordPress JSON- ja PHP-tekstisi yhdestä selkeästä lähteestä? Kokeile SimplePoTranslatea ilmaiseksi – luottokorttia ei tarvita. Ilmainen taso kääntää oikeita .po- ja .pot-tiedostoja paikkamerkkivarman Syntax Lockingin avulla, joten lohkoeditorisi tekstit toimitetaan oikein.