Μετάφραση JSON στο WordPress: Μετάφραση JavaScript του Block Editor

Μεταφράσατε το πρόσθετό σας. Οι συμβολοσειρές PHP εμφανίζονται τέλεια στις ρυθμίσεις διαχείρισης, στα πρότυπα frontend, στις ειδοποιήσεις email – όλα μεταφρασμένα. Στη συνέχεια, ανοίγετε τον επεξεργαστή μπλοκ και κάθε ετικέτα στο προσαρμοσμένο σας μπλοκ Gutenberg είναι επίμονα, χλευαστικά στα Αγγλικά. Το κουμπί "Add Item", οι επικεφαλίδες του πίνακα επιθεωρητή, το κείμενο placeholder. Το αρχείο σας .mo έχει φορτωθεί. Γιατί λοιπόν αυτές οι συμβολοσειρές δεν μεταφράζονται;

Επειδή από το WordPress 5.0 και την άφιξη του Gutenberg, οι συμβολοσειρές JavaScript δεν προέρχονται καθόλου από το αρχείο σας .mo. Χρειάζονται ένα εντελώς ξεχωριστό, ανά σενάριο, αρχείο μετάφρασης JSON στο WordPress – και αν δεν το δημιουργήσετε, ο επεξεργαστής μπλοκ σας παραμένει στα Αγγλικά, ανεξάρτητα από το πόσο πλήρες είναι το αρχείο σας .po. Αυτό είναι ένα από τα πιο κοινά και συγκεχυμένα κενά εντοπισμού στη σύγχρονη ανάπτυξη του WordPress. Αυτός ο οδηγός εξηγεί ακριβώς γιατί συμβαίνει, πώς λειτουργεί το σύστημα μετάφρασης JSON, τα ονόματα αρχείων με κατακερματισμό MD5 που μπερδεύουν τους πάντες και την πλήρη εργαλειοθήκη για να το διορθώσετε.

Γιατί οι συμβολοσειρές του Block Editor παραμένουν στα Αγγλικά

Σύντομη απάντηση: Η PHP και η JavaScript χρησιμοποιούν δύο εντελώς διαφορετικά συστήματα παράδοσης μεταφράσεων στο WordPress, και το αρχείο σας .mo τροφοδοτεί μόνο το σύστημα της PHP.

Δύο Συστήματα Μετάφρασης, Ένα Πρόσθετο

Όταν το WordPress εκτελεί το load_plugin_textdomain(), διαβάζει το μεταγλωττισμένο αρχείο .mo στη μνήμη της PHP. Κάθε κλήση __(), _e() και _x() στον κώδικα PHP σας αναζητά τη μετάφρασή της εκεί. Αυτό λειτουργεί επειδή η PHP κάνει render server-side – τα δεδομένα .mo βρίσκονται ακριβώς στην ίδια διαδικασία.

Η JavaScript είναι διαφορετική. Ο κώδικας του μπλοκ σας εκτελείται στο πρόγραμμα περιήγησης, πολύ αφότου έχει τελειώσει η PHP. Δεν μπορεί να έχει πρόσβαση σε ένα αρχείο .mo από την πλευρά του διακομιστή. Αντίθετα, το πακέτο @wordpress/i18n – το ισοδύναμο του Gettext σε JS, εκθέτοντας τις __(), _x() και sprintf() στα σενάριά σας – αναμένει οι μεταφράσεις να παραδοθούν ως ένα JSON payload συνδεδεμένο με το συγκεκριμένο σενάριο που τις χρειάζεται.

Τι συμβαίνει σε μια αμετάφραστη συμβολοσειρά JS

Έτσι, ένα μπλοκ με συμβολοσειρές όπως αυτή:

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

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

δεν θα βρει ποτέ "Feature Box" ή "Add Item" στο αρχείο σας .mo, επειδή το πρόγραμμα περιήγησης δεν διαβάζει ποτέ αρχεία .mo. Αυτές οι συμβολοσειρές πρέπει να φτάσουν ως JSON, συνδεδεμένες με αυτό ακριβώς το script handle. Αν δεν το έχετε ρυθμίσει, οι κλήσεις JS __() απλώς επιστρέφουν το αρχικό αγγλικό κείμενο – αθόρυβα, χωρίς σφάλμα στην κονσόλα.

Σύνδεση Μεταφράσεων JSON με το wp_set_script_translations()

Η γέφυρα μεταξύ του σεναρίου σας και των μεταφράσεων JSON είναι μία μόνο συνάρτηση PHP: wp_set_script_translations(). Η απάντηση στο "πώς γνωρίζει το WordPress ποιο αρχείο JSON ανήκει σε ποιο σενάριο" είναι: εσείς το λέτε, καταχωρώντας το σενάριο και στη συνέχεια δηλώνοντας το text domain του και τον φάκελο όπου βρίσκεται το JSON.

Καταχώρηση του Σεναρίου και του Φακέλου Μετάφρασής του

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

Όταν ο επεξεργαστής φορτώνει το myplugin-editor, το WordPress γνωρίζει πλέον να ψάξει στον φάκελο languages/ για ένα αρχείο JSON που ταιριάζει με αυτό το σενάριο και την τοπική ρύθμιση του τρέχοντος χρήστη. Αν το βρει, εισάγει τις μεταφράσεις πριν εκτελεστεί το σενάριό σας, και οι κλήσεις JS __() επιλύονται σωστά. Το handle που περνάτε πρέπει να ταιριάζει ακριβώς με ένα καταχωρημένο σενάριο – ένα handle που δεν ταιριάζει ή λείπει είναι ο δεύτερος πιο κοινός λόγος που οι μεταφράσεις αποτυγχάνουν σιωπηλά.

Το Όνομα Αρχείου με MD5 Hash που Κανείς δεν Περιμένει

Εδώ είναι η λεπτομέρεια που αποπροσανατολίζει σχεδόν τους πάντες. Το αρχείο JSON που αναζητά το WordPress δεν έχει ένα τακτοποιημένο όνομα όπως myplugin-fr_FR.json. Ονομάζεται με ένα MD5 hash της διαδρομής πηγής του σεναρίου:

Αποκωδικοποίηση του Μοτίβου Ονόματος Αρχείου

myplugin-fr_FR-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.json

Το μοτίβο είναι {textdomain}-{locale}-{md5}.json, όπου το hash είναι το MD5 της σχετικής διαδρομής προς το αρχείο σεναρίου (για παράδειγμα build/index.js) όπως έχει καταχωρηθεί. Το WordPress υπολογίζει αυτό το hash κατά την εκτέλεση για να βρει το σωστό JSON για το σωστό σενάριο. Αν ονομάσετε το αρχείο χειροκίνητα, το WordPress δεν θα το βρει, και θα ορκίζεστε ότι το σύστημα είναι χαλασμένο ενώ απλώς ψάχνει για διαφορετικό όνομα αρχείου.

Δεν υπολογίζετε το hash μόνοι σας. Η εντολή WP-CLI i18n το κάνει για εσάς, γι' αυτό ακριβώς πρέπει να χρησιμοποιήσετε τα εργαλεία αντί να δημιουργείτε αυτά τα αρχεία χειροκίνητα. Η κατανόηση ότι το hash υπάρχει, ωστόσο, είναι αυτό που σας σώζει ώρες όταν ένα αρχείο JSON υπάρχει στο languages/ αλλά εξακολουθεί να αγνοείται – είναι σχεδόν πάντα μια αναντιστοιχία hash ονόματος αρχείου επειδή η διαδρομή του σεναρίου άλλαξε.

Η Πλήρης Ροή Εργασίας: από make-pot σε make-json

Τα καλά νέα είναι ότι διατηρείτε τις μεταφράσεις σας στα ίδια αρχεία .po που ήδη χρησιμοποιείτε. Το JSON είναι ένα παράγωγο τεχνούργημα που δημιουργείται στο τέλος. Η απάντηση στην ερώτηση "πρέπει να διατηρώ τις συμβολοσειρές JS ξεχωριστά" είναι όχι – ζουν στο ίδιο .pot/.po με τις συμβολοσειρές PHP σας, και μια επιπλέον εντολή διαχωρίζει τις JS σε JSON.

Η Ροή Τεσσάρων Εντολών

Εδώ είναι η πλήρης ροή εργασίας:

# 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 του Βήματος 1 είναι αρκετά έξυπνο ώστε να σαρώνει τόσο τα αρχεία σας .php όσο και τον κώδικα προέλευσης .js/.jsx, έτσι ένα ενιαίο αρχείο .po ανά τοπική ρύθμιση περιέχει τα πάντα. Το make-json του Βήματος 4 διαβάζει κάθε μεταφρασμένο .po, βρίσκει τις καταχωρήσεις που προήλθαν από αρχεία JavaScript, και γράφει ένα σωστά κατακερματισμένο JSON ανά σενάριο. Η σημαία --no-purge διατηρεί επίσης τις συμβολοσειρές JS στο αρχείο .po σας, ώστε ένα μεταγενέστερο make-mo να μην τις χάσει – χωρίς αυτήν, το make-json αφαιρεί τις καταχωρήσεις JS από το .po, κάτι που εκπλήσσει τους χρήστες που εκτελούν τις εντολές με λάθος σειρά.

Ένα παραγόμενο αρχείο JSON μοιάζει με ένα σύνολο μεταφράσεων μορφής 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 διαβάζει τα locale_data και τα τροφοδοτεί στο @wordpress/i18n πριν εκτελεστεί το σενάριό σας. Τώρα το __( 'Add Item', 'myplugin' ) στο πρόγραμμα περιήγησης επιστρέφει Ajouter un élément, και ο επεξεργαστής μπλοκ σας είναι επιτέλους μεταφρασμένος.

Πώς Διαφέρει Αυτό από το i18next JSON

Και τα δύο συστήματα χρησιμοποιούν JSON, και τα δύο στοχεύουν τη JavaScript, και αυτή η επιφανειακή ομοιότητα προκαλεί πραγματική σύγχυση. Δεν είναι εναλλάξιμα. Το JSON του block-editor του WordPress είναι ένα payload που προέρχεται από το Gettext, με MD5 hash, ανά σενάριο, και καταναλώνεται από το @wordpress/i18n. Το i18next JSON είναι ένα επίπεδο ή ένθετο αρχείο κλειδιού-τιμής που καταναλώνεται από το react-i18next ή το next-intl, με τη δική του σύνταξη {{interpolation}} και συμβάσεις για πληθυντικό.

Αν εργάζεστε σε απλό React ή Next.js εκτός του WordPress, θέλετε την προσέγγιση i18next, την οποία καλύπτουμε στη μετάφραση i18next JSON σε React και Next.js. Μέσα στο WordPress, θέλετε τη ροή εργασίας make-json που περιγράφεται παραπάνω. Το να τα μπερδέψετε – για παράδειγμα, να γράψετε χειροκίνητα JSON σε στυλ i18next και να περιμένετε να το φορτώσει το wp_set_script_translations() – απλώς δεν θα λειτουργήσει, επειδή το WordPress αναζητά τη μορφή Jed με hash, όχι αυθαίρετα ζεύγη κλειδιού-τιμής.

Μία Πηγή, Κάθε Μορφή που Χρειάζεστε

Η αδυναμία σε όλα αυτά είναι το βήμα της μετάφρασης στη μέση. Το αρχείο σας .po τροφοδοτεί τόσο το .mo (PHP) όσο και το JSON (JavaScript), έτσι μια μόνο κακοφτιαγμένη μετάφραση – ένα παραμορφωμένο %s, μια χαλασμένη ετικέτα <strong>, μια μετονομασμένη πληθυντική μορφή – δηλητηριάζει και τις δύο εξόδους ταυτόχρονα. Και επειδή οι συμβολοσειρές JS φορτώνονται ασύγχρονα στο πρόγραμμα περιήγησης, ένα δομικό σφάλμα εκεί συχνά εμφανίζεται ως κενή ετικέτα ή πλήρης κρασάρισμα αντί για μια ομαλή επαναφορά.

Μία Μεταφόρτωση, Καλύπτονται PHP και JavaScript

Εδώ είναι που μια διαδικασία μετάφρασης που κατανοεί τη δομή του Gettext κερδίζει τη θέση της. Το SimplePoTranslate παίρνει ένα αρχείο πηγής .po ή .pot και παράγει καθαρή, μεταφρασμένη έξοδο σε πολλαπλές μορφές από μία μόνο μεταφόρτωση – .po, .mo, .json, .php, και .xliff – ώστε να μην χρειάζεται να συνδυάζετε ξεχωριστά εργαλεία για τα επίπεδα PHP και JavaScript. Η λειτουργία Syntax Locking διατηρεί τις θέσεις των %s, %1$s, {count} και του inline HTML, κάτι που είναι διπλά σημαντικό για τις συμβολοσειρές του block editor, όπου ένα χαλασμένο placeholder μπορεί να καταστρέψει ολόκληρο τον πίνακα του επεξεργαστή. Αναλύουμε περισσότερο το μοντέλο μίας πηγής, πολλών εξόδων στο ένα αρχείο μέσα, πέντε μορφές έξω.

Εξακολουθείτε να εκτελείτε το make-json για να παράγετε τα αρχεία με hash που περιμένει το WordPress – αυτό το βήμα είναι ειδικό για το WordPress και παραμένει στην κατασκευή σας. Αλλά η ίδια η μετάφραση, το μέρος που είναι πιο πιθανό να χαλάσει τις συμβολοσειρές JS σας, αντιμετωπίζεται από μια μηχανή που λαμβάνει υπόψη το περιεχόμενο, αντί για ένα σενάριο αναζήτησης και αντικατάστασης.

Συμπέρασμα

Ο λόγος που ο επεξεργαστής μπλοκ σας παραμένει στα Αγγλικά είναι δομικός, όχι κάποιο σφάλμα: η μετάφραση JSON στο WordPress είναι ένα ξεχωριστό σύστημα παράδοσης από το αρχείο .mo, σχεδιασμένο ειδικά επειδή τα προγράμματα περιήγησης δεν μπορούν να διαβάσουν δεδομένα Gettext από την πλευρά του διακομιστή. Μόλις καταλάβετε ότι οι συμβολοσειρές JavaScript χρειάζονται JSON με MD5 hash ανά σενάριο, που δημιουργείται από το wp i18n make-json και συνδέεται με το wp_set_script_translations(), η διόρθωση είναι μηχανική. Διατηρήστε τις συμβολοσειρές σας σε ένα .po, μεταγλωττίστε το .mo για την PHP, και εκτελέστε το make-json για τη JS.

Κάντε σωστά το βήμα της μετάφρασης και και οι δύο έξοδοι θα λειτουργήσουν. Κάντε το λάθος και θα διορθώνετε κενούς πίνακες επεξεργασίας για ένα απόγευμα.

Είστε έτοιμοι να μεταφράσετε τις συμβολοσειρές JSON και PHP του WordPress από μία καθαρή πηγή; Δοκιμάστε το SimplePoTranslate δωρεάν — δεν απαιτείται πιστωτική κάρτα. Το δωρεάν πακέτο μεταφράζει πραγματικά αρχεία .po και .pot με ασφαλές Syntax Locking για τους placeholders, ώστε οι συμβολοσειρές του block editor σας να είναι σωστές.