Překlad JSON ve WordPressu: Překlad JavaScriptu v editoru bloků

Přeložili jste svůj plugin. Řetězce PHP se dokonale zobrazují v nastavení administrace, front-end šablonách, e-mailových oznámeních – vše je lokalizováno. Pak otevřete editor bloků a každý popisek ve vašem vlastním bloku Gutenberg je tvrdohlavě, posměšně anglicky. Tlačítko „Add Item“, nadpisy inspekčního panelu, zástupný text. Váš soubor .mo je načten. Proč se tedy tyto řetězce nepřekládají?

Protože od WordPressu 5.0 a příchodu Gutenbergu, řetězce JavaScriptu vůbec nepocházejí z vašeho souboru .mo. Potřebují zcela samostatný WordPress JSON překladový soubor pro každý skript – a pokud jej nevygenerujete, váš editor bloků zůstane v angličtině, bez ohledu na to, jak kompletní je váš soubor .po. Toto je jedna z nejčastějších a nejvíce matoucích mezer v lokalizaci v moderním vývoji WordPressu. Tento průvodce vysvětluje, proč se to děje, jak funguje systém překladu JSON, názvy souborů s MD5 hash, které všechny matou, a kompletní sadu nástrojů k nápravě.

Proč řetězce vašeho editoru bloků zůstávají v angličtině

Stručná odpověď: PHP a JavaScript používají ve WordPressu dva zcela odlišné systémy doručování překladů a váš soubor .mo napájí pouze ten PHP.

Dva překladové systémy, jeden plugin

Když WordPress spustí load_plugin_textdomain(), načte váš zkompilovaný soubor .mo do paměti PHP. Každé volání __(), _e() a _x() ve vašem PHP kódu tam vyhledá svůj překlad. To funguje, protože PHP vykresluje na straně serveru – data .mo jsou přímo tam ve stejném procesu.

JavaScript je jiný. Kód vašeho bloku běží v prohlížeči, dlouho poté, co PHP dokončí svou práci. Nemůže sahat do souboru .mo na straně serveru. Místo toho balíček @wordpress/i18n – JS ekvivalent Gettextu, který zpřístupňuje __(), _x() a sprintf() vašim skriptům – očekává, že překlady budou doručeny jako JSON datová zpráva připojená k specifickému skriptu, který je potřebuje.

Co se stane s nepřeloženým JS řetězcem

Takže blok s řetězci jako tento:

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

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

nikdy nenajde „Feature Box“ nebo „Add Item“ ve vašem souboru .mo, protože prohlížeč nikdy nečte soubory .mo. Tyto řetězce musí dorazit jako JSON, propojené s přesným identifikátorem skriptu. Pokud jste to nenastavili, volání JS __() jednoduše vrátí původní anglický text – tiše, bez chyby v konzoli.

Propojování JSON překladů pomocí wp_set_script_translations()

Most mezi vaším skriptem a jeho JSON překlady tvoří jediná PHP funkce: wp_set_script_translations(). Odpověď na otázku „jak WordPress ví, který soubor JSON patří ke kterému skriptu“ zní: vy mu to řeknete, registrací skriptu a následným deklarováním jeho textové domény a složky, kde se JSON nachází.

Registrace skriptu a jeho složky s překlady

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

Když editor načte myplugin-editor, WordPress nyní ví, že má hledat ve vaší složce languages/ soubor JSON, který odpovídá tomuto skriptu a lokalizaci aktuálního uživatele. Pokud ho najde, vloží překlady před spuštěním vašeho skriptu a volání JS __() se správně vyřeší. Identifikátor, který předáváte, se musí přesně shodovat s registrovaným skriptem – neshodný nebo chybějící identifikátor je druhým nejčastějším důvodem, proč překlady tiše selhávají.

Název souboru s MD5 hash, který nikdo neočekává

Zde je detail, který téměř každého vykolejí. Soubor JSON, který WordPress hledá, není pojmenován něco úhledného jako myplugin-fr_FR.json. Je pojmenován pomocí MD5 hashe zdrojové cesty skriptu:

Dekódování vzoru názvu souboru

myplugin-fr_FR-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.json

Vzor je {textdomain}-{locale}-{md5}.json, kde hash je MD5 relativní cesty k souboru skriptu (například build/index.js), jak je registrováno. WordPress vypočítá tento hash za běhu, aby našel správný JSON pro správný skript. Pokud pojmenujete soubor ručně, WordPress jej nenajde a vy budete přísahat, že systém je rozbitý, zatímco on jen hledá jiný název souboru.

Hash si nepočítáte sami. WP-CLI i18n příkaz to dělá za vás, a to je přesně důvod, proč musíte používat nástroje, spíše než vytvářet tyto soubory ručně. Nicméně pochopení, že hash existuje, je to, co vám ušetří hodiny, když je soubor JSON přítomen ve languages/, ale stále ignorován – téměř vždy se jedná o neshodu hashe názvu souboru, protože se změnila cesta skriptu.

Kompletní pracovní postup: od make-pot k make-json

Dobrou zprávou je, že své překlady uchováváte ve stejných souborech .po, které již používáte. JSON je odvozený artefakt generovaný na konci. Odpověď na otázku „mám udržovat JS řetězce odděleně“ zní ne – žijí ve stejném .pot/.po jako vaše PHP řetězce a jeden další příkaz oddělí JS řetězce do JSONu.

Čtyř-příkazová pipeline

Zde je kompletní 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 v kroku 1 je dostatečně chytrý na to, aby skenoval jak vaše .php soubory, tak i váš .js/.jsx zdroj, takže jeden soubor .po pro každou lokalitu obsahuje vše. make-json v kroku 4 přečte každý přeložený .po soubor, najde záznamy, které pocházejí ze souborů JavaScriptu, a zapíše jeden správně-hashovaný JSON pro každý skript. Příznak --no-purge také uchovává JS řetězce ve vašem .po, takže pozdější make-mo je neztratí – bez něj make-json odstraňuje JS záznamy z .po, což překvapuje lidi, kteří spouštějí příkazy ve špatném pořadí.

Vygenerovaný soubor JSON vypadá jako sada překladů ve formátu Jed:

{
  "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 načte locale_data a předá jej @wordpress/i18n před spuštěním vašeho skriptu. Nyní __( 'Add Item', 'myplugin' ) v prohlížeči vrátí Ajouter un élément a váš editor bloků je konečně lokalizován.

Jak se to liší od i18next JSON

Oba systémy používají JSON, oba cílí na JavaScript, a tato povrchová podobnost způsobuje skutečné zmatky. Nejsou zaměnitelné. JSON editoru bloků WordPressu je Gettextem odvozená, MD5-hashovaná datová zpráva pro každý skript, kterou spotřebovává @wordpress/i18n. i18next JSON je plochý nebo vnořený soubor klíč-hodnota spotřebovávaný react-i18next nebo next-intl, s vlastní {{interpolation}} syntaxí a konvencemi pro množné klíče.

Pokud pracujete v čistém Reactu nebo Next.js mimo WordPress, chcete přístup i18next, který popisujeme v překladu i18next JSON v Reactu a Next.js. Uvnitř WordPressu chcete výše uvedený pracovní postup make-json. Jejich smíchání – například ruční psaní plochého JSONu ve stylu i18next a očekávání, že wp_set_script_translations() jej načte – prostě nebude fungovat, protože WordPress hledá hashovaný formát Jed, nikoli libovolné páry klíč-hodnota.

Jeden zdroj, všechny potřebné formáty

Křehkost celého tohoto procesu spočívá v kroku překladu uprostřed. Váš soubor .po napájí jak .mo (PHP), tak JSON (JavaScript), takže jediný zpackaný překlad – poškozený %s, rozbitý tag <strong>, přejmenovaná množná forma – znečistí oba výstupy najednou. A protože jsou JS řetězce načítány asynchronně v prohlížeči, strukturální chyba se tam často projevuje jako prázdný popisek nebo tvrdý pád, spíše než jako elegantní záložní řešení.

Jeden upload, pokryté PHP i JavaScript

Zde si zaslouží své místo překladová pipeline, která rozumí struktuře Gettextu. SimplePoTranslate vezme jeden zdrojový soubor .po nebo .pot a vytvoří čistý, přeložený výstup v mnoha formátech z jediného nahrání – .po, .mo, .json, .php a .xliff – takže nemusíte skládat dohromady samostatné nástroje pro vaše PHP a JavaScript vrstvy. Jeho Syntax Locking udržuje %s, %1$s, {count} a inline HTML na svém místě, což je dvojnásob důležité pro řetězce editoru bloků, kde poškozený zástupný symbol může shodit celý panel editoru. Hlouběji se modelu jednoho zdroje a mnoha výstupů věnujeme v článku jeden soubor dovnitř, pět formátů ven.

Stále spouštíte make-json k vytvoření hashovaných souborů, které WordPress očekává – tento krok je specifický pro WordPress a zůstává ve vašem buildu. Ale samotný překlad, část, která s největší pravděpodobností rozbije vaše JS řetězce, je zpracováván kontextově uvědomělým enginem namísto skriptu pro hledání a nahrazování.

Závěr

Důvod, proč váš editor bloků zůstává v angličtině, je strukturální, nikoli chyba: WordPress JSON překlad je samostatný doručovací systém od souboru .mo, vytvořený speciálně proto, že prohlížeče nemohou číst data Gettextu ze serveru. Jakmile pochopíte, že řetězce JavaScriptu potřebují pro každý skript MD5-hashovaný JSON generovaný wp i18n make-json a propojený s wp_set_script_translations(), oprava je mechanická. Udržujte své řetězce v jednom .po souboru, kompilujte .mo pro PHP a spusťte make-json pro JS.

Pokud krok překladu provedete správně, oba výstupy budou funkční. Pokud se spletete, budete celé odpoledne ladit prázdné panely editoru.

Jste připraveni překládat své WordPress JSON a PHP řetězce z jednoho čistého zdroje? Vyzkoušejte SimplePoTranslate zdarma — není vyžadována kreditní karta. Bezplatná úroveň překládá skutečné .po a .pot soubory s funkcí Syntax Locking, která chrání zástupné symboly, takže řetězce vašeho editoru bloků budou odeslány správně.