Πώς να δημιουργήσετε ένα αρχείο .pot για ένα θέμα ή ένα plugin
Μόλις ολοκληρώσατε ένα plugin του WordPress που θέλετε να μοιραστείτε με τον κόσμο. Ο κώδικας λειτουργεί, οι δυνατότητες είναι σταθερές, και κάποιος από τη Γερμανία στέλνει ένα email ρωτώντας πώς να το μεταφράσει στα Γερμανικά. Τους παραπέμπετε στον φάκελο languages και συνειδητοποιείτε ότι δεν υπάρχει τίποτα εκεί. Κανένα πρότυπο, καμία συμβολοσειρά, κανένας τρόπος για έναν μεταφραστή να γνωρίζει τι χρειάζεται μετάφραση. Το plugin σας είναι τεχνικά "translation-ready" μόνο κατ' όνομα.
Κάθε μεταφράσιμο έργο του WordPress ξεκινά με ένα αρχείο: το πρότυπο .pot. Πριν κάποιος μπορέσει να δημιουργήσει μια Γερμανική, Γαλλική ή Ιαπωνική έκδοση, πρέπει να δημιουργήσετε ένα αρχείο POT που να περιλαμβάνει κάθε συμβολοσειρά που βλέπει ο χρήστης στον κώδικά σας. Παραλείψτε αυτό το βήμα και οι μεταφραστές θα κολλήσουν διαβάζοντας τον πηγαίο κώδικά σας γραμμή προς γραμμή, μαντεύοντας ποιες συμβολοσειρές προορίζονται να είναι ορατές.
Αυτός ο οδηγός περιγράφει τα δύο μισά της δουλειάς: την προετοιμασία του πηγαίου κώδικά σας ώστε οι συμβολοσειρές να είναι ανιχνεύσιμες, και στη συνέχεια τη δημιουργία του ίδιου του .pot με τρία διαφορετικά εργαλεία. Θα χρησιμοποιήσουμε WP-CLI, Poedit, και την παλαιότερη προσέγγιση makepot/grunt, με πραγματικές εντολές που μπορείτε να αντιγράψετε. Στο τέλος θα έχετε ένα καθαρό πρότυπο έτοιμο να το παραδώσετε σε οποιονδήποτε μεταφραστή.
Βήμα Πρώτο: Σημειώστε τις συμβολοσειρές σας ως μεταφράσιμες
Πριν μπορέσετε να δημιουργήσετε ένα αρχείο POT, κάθε συμβολοσειρά που μπορεί να δει ένας χρήστης πρέπει να είναι περιτυλιγμένη σε μια συνάρτηση Gettext. Ένας σαρωτής μπορεί να εξάγει μόνο συμβολοσειρές που αναγνωρίζει, και τις αναγνωρίζει από αυτές τις κλήσεις συναρτήσεων — οι απλές συμβολοσειρές είναι αόρατες σε αυτόν.
Το WordPress παρέχει μια οικογένεια συναρτήσεων τοπικής προσαρμογής, η καθεμία για ένα ελαφρώς διαφορετικό πλαίσιο:
// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );
// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );
// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );
// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );
Το δεύτερο όρισμα σε κάθε κλήση — 'my-plugin' — είναι το text domain. Ομαδοποιεί όλες τις συμβολοσειρές ενός plugin ή θέματος κάτω από έναν ενιαίο χώρο ονομάτων, ώστε το WordPress να γνωρίζει ποιο αρχείο .mo να φορτώσει γι' αυτές. Κάθε μεταφράσιμη συμβολοσειρά στο έργο σας πρέπει να μοιράζεται ακριβώς το ίδιο text domain, διαφορετικά κάποιες συμβολοσειρές δεν θα μεταφραστούν ποτέ.
Χρησιμοποιήστε το _x() όποτε μια λέξη είναι αμφίσημη. Η Αγγλική λέξη "Post" μπορεί να είναι ουσιαστικό ή ρήμα, και πολλές γλώσσες τις μεταφράζουν διαφορετικά. Οι συμβολοσειρές πλαισίου επιτρέπουν στους μεταφραστές να τις ξεχωρίζουν. Και χρησιμοποιήστε τις παραλλαγές esc_html__() και esc_attr__() όποτε η μεταφρασμένη συμβολοσειρά εκτυπώνεται σε HTML, ώστε να παραμένετε ασφαλείς και τοπικοποιημένοι ταυτόχρονα.
Υπάρχουν μερικές συνήθειες που διατηρούν τις συμβολοσειρές σας εξάγουσες. Πάντα να περνάτε μια απλή συμβολοσειρά ως το πρώτο όρισμα — ποτέ μια μεταβλητή ή μια συνένωση όπως __( 'Hello ' . $name, 'my-plugin' ), επειδή ο σαρωτής διαβάζει το αρχικό κείμενο στατικά και δεν μπορεί να επιλύσει τιμές χρόνου εκτέλεσης. Για προτάσεις με αριθμό, χρησιμοποιήστε το _n() ώστε οι πληθυντικές μορφές να συλλαμβάνονται σωστά, και για προτάσεις με δυναμική τιμή, χρησιμοποιήστε το sprintf() γύρω από ένα placeholder όπως %s αντί να κολλάτε συμβολοσειρές. Η συνέπεια εδώ είναι αυτό που κάνει το επόμενο βήμα — τη δημιουργία του προτύπου — να παράγει ένα πλήρες, χρησιμοποιήσιμο αποτέλεσμα.
Βήμα Δεύτερο: Δηλώστε το Text Domain στην Κεφαλίδα σας
Το WordPress χρειάζεται δύο πεδία κεφαλίδας για να γνωρίζει πού βρίσκονται οι μεταφράσεις σας: το Text Domain και το Domain Path. Ορίστε τα στο κύριο αρχείο του plugin σας ή στο style.css του θέματός σας, και το WordPress θα φορτώσει αυτόματα το σωστό .mo κατά το χρόνο εκτέλεσης.
<?php
/**
* Plugin Name: My Plugin
* Description: A perfectly localized WordPress plugin.
* Version: 1.0.0
* Requires at least: 6.4
* Text Domain: my-plugin
* Domain Path: /languages
*/
Το Text Domain πρέπει να αντιστοιχεί στη συμβολοσειρά που περάσατε σε κάθε κλήση __() και _e() — my-plugin εδώ. Το Domain Path λέει στο WordPress ποιον υποφάκελο περιέχουν τα αρχεία μετάφρασης, σε σχέση με τη ρίζα του plugin ή του θέματος. Η σύμβαση είναι /languages, και ακριβώς εκεί πρέπει να βρίσκεται το παραγόμενο αρχείο .pot.
Με τις συμβολοσειρές περιτυλιγμένες και την κεφαλίδα δηλωμένη, ο κώδικάς σας είναι έτοιμος για σάρωση. Η ευρύτερη εικόνα της προετοιμασίας ενός έργου για μετάφραση — συμπεριλαμβανομένων θεμάτων που δεν είναι δικά σας — καλύπτεται στο πώς να τοπικοποιήσετε οποιοδήποτε θέμα WordPress ακόμα κι αν δεν είστε προγραμματιστής.
Πώς Δημιουργείτε το αρχείο .pot; Τρεις Μέθοδοι
Δημιουργείτε ένα αρχείο .pot εκτελώντας έναν σαρωτή στον πηγαίο κώδικά σας που βρίσκει κάθε κλήση Gettext και γράφει τις συμβολοσειρές σε ένα πρότυπο. Εδώ είναι τρεις αξιόπιστοι τρόποι να το κάνετε, από την σύγχρονη προεπιλογή έως την παλαιότερη προσέγγιση.
Μέθοδος 1: WP-CLI (Συνιστάται)
Ο επίσημος, σύγχρονος τρόπος για να δημιουργήσετε ένα αρχείο POT είναι το WP-CLI με την εντολή i18n. Αποστέλλεται ως μέρος των εργαλείων του πυρήνα του WordPress, κατανοεί συμβολοσειρές PHP και JavaScript και παράγει ένα πρότυπο συμβατό με τα πρότυπα σε μία γραμμή.
# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot
# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules
Το πρώτο όρισμα είναι ο κατάλογος προέλευσης (. για τον τρέχοντα φάκελο), και το δεύτερο είναι η διαδρομή εξόδου. Το WP-CLI διατρέχει τα αρχεία σας, εξάγει κάθε περιτυλιγμένη συμβολοσειρά, καταγράφει το αρχείο προέλευσης και τον αριθμό γραμμής ως σχόλιο και γράφει το .pot. Είναι γρήγορο, scriptable και η σωστή επιλογή για κάθε σοβαρό έργο.
Το παραγόμενο πρότυπο περιλαμβάνει χρήσιμα μεταδεδομένα που μπορείτε να προσαρμόσετε με επιπλέον flags. Περάστε το --headers για να ορίσετε το όνομα του έργου, την έκδοση και τη διεύθυνση επικοινωνίας των μεταφραστών, ώστε το μπλοκ κεφαλίδας του .pot να συμπληρωθεί σωστά αντί να παραμείνει ως placeholders. Το WP-CLI εξάγει επίσης αυτόματα συμβολοσειρές JavaScript από κλήσεις wp_set_script_translations(), κάτι που είναι σημαντικό για σύγχρονα block themes και plugins του Gutenberg όπου το μισό κείμενο που βλέπει ο χρήστης βρίσκεται σε JavaScript αντί για PHP. Μια εντολή καλύπτει και τους δύο κόσμους.
Μέθοδος 2: Poedit (Γραφική)
Αν προτιμάτε μια εφαρμογή επιφάνειας εργασίας, το Poedit μπορεί να σαρώσει τον πηγαίο κώδικά σας και να δημιουργήσει το πρότυπο μέσω της διεπαφής του. Ανοίξτε το Poedit, επιλέξτε να δημιουργήσετε μια νέα μετάφραση από POT ή να σαρώσετε απευθείας τις πηγές, δείξτε του τον φάκελο του έργου σας και διαμορφώστε τις λέξεις-κλειδιά πηγής (__, _e, _x, esc_html__) κάτω από τις ιδιότητες του καταλόγου.
Οι δυνατότητες σάρωσης πηγαίου κώδικα και δημιουργίας αρχείων .pot του Poedit βρίσκονται στην έκδοση Pro, αλλά η ροή εργασίας είναι φιλική για τους προγραμματιστές που προτιμούν να κάνουν κλικ παρά να πληκτρολογούν εντολές. Είναι επίσης ένας αξιόπιστος επεξεργαστής για τη φάση μετάφρασης που ακολουθεί. Το Poedit και αρκετές άλλες επιλογές επιφάνειας εργασίας συγκρίνονται στο τα 5 κορυφαία δωρεάν εργαλεία για επεξεργασία και μετάφραση αρχείων PO σε Mac και Windows.
Μέθοδος 3: makepot / grunt (Παλαιότερη)
Πριν το WP-CLI, το τυπικό εργαλείο ήταν το script makepot.php από το αποθετήριο WordPress i18n-tools, συχνά συνδεδεμένο με μια εργασία κατασκευής Grunt με το grunt-wp-i18n. Θα το συναντήσετε ακόμα σε παλαιότερα plugins και θέματα.
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
Λειτουργεί, αλλά δεν συντηρείται σε σχέση με το WP-CLI και είναι πιο αργό στην εγκατάσταση. Χρησιμοποιήστε το μόνο όταν συντηρείτε ένα παλαιότερο έργο που ήδη εξαρτάται από αυτό. για οτιδήποτε νέο, προτιμήστε το wp i18n make-pot.
Διατηρήστε το Πρότυπο Ενημερωμένο Καθώς ο Κώδικάς σας Αλλάζει
Ένα .pot είναι ένα στιγμιότυπο των συμβολοσειρών σας σε μια συγκεκριμένη στιγμή. Κάθε φορά που προσθέτετε μια λειτουργία, αλλάζετε μια ετικέτα ή διορθώνετε ένα τυπογραφικό λάθος σε μια ορατή συμβολοσειρά, το πρότυπο παλιώνει και οι μεταφραστές χάνουν τη νέα διατύπωση.
Κάντε την αναδημιουργία μέρος της ρουτίνας κυκλοφορίας σας. Επαναλάβετε την εκτέλεση του wp i18n make-pot πριν από κάθε αύξηση έκδοσης, και στη συνέχεια συγχωνεύστε το ανανεωμένο πρότυπο σε υπάρχουσες μεταφράσεις με wp i18n update-po ή msgmerge ώστε οι μεταφραστές να διατηρούν την ολοκληρωμένη τους εργασία και να βλέπουν μόνο τα νέα κενά. Αντιμετωπίστε το .pot ως ένα artifact κατασκευής που αναδημιουργείτε, όχι ως ένα αρχείο που επεξεργάζεστε χειροκίνητα.
Ένα παλιό πρότυπο προκαλεί μια ανεπαίσθητη, απογοητευτική αποτυχία: νέες συμβολοσειρές εμφανίζονται στα Αγγλικά ακόμη και σε έναν "πλήρως μεταφρασμένο" ιστότοπο, επειδή δεν υπήρχαν ποτέ στο .pot από το οποίο εργάστηκε ο μεταφραστής. Η αντιμετώπιση αυτού είναι τόσο απλή όσο η προγραμματισμένη αναδημιουργία στην κατασκευή σας, ώστε το πρότυπο να μην μπορεί ποτέ να καθυστερήσει σε σχέση με τον κώδικα. Ορισμένες ομάδες προσθέτουν έναν έλεγχο CI που αποτυγχάνει την κατασκευή εάν η αναδημιουργία του .pot παράγει μια διαφορά, εγγυώμενο ότι το δεσμευμένο πρότυπο ταιριάζει πάντα με την τρέχουσα πηγή.
Μόλις οι μεταφραστές επιστρέψουν τα ολοκληρωμένα αρχεία .po, αυτά εξακολουθούν να χρειάζονται μεταγλώττιση στο δυαδικό .mo που πραγματικά φορτώνει το WordPress — και αν προτιμάτε να παραλείψετε ολόκληρο τον κύκλο λήψης-μετάφρασης-αναμεταγλώττισης, ένα εργαλείο cloud μπορεί να το χειριστεί από άκρο σε άκρο. Το SimplePoTranslate δέχεται απευθείας το αρχείο .pot σας, το μεταφράζει με Context-Aware AI που κατανοεί τι σημαίνει κάθε συμβολοσειρά στη διεπαφή σας, και επιστρέφει ένα ενιαίο ZIP με τα αρχεία .po, .mo, και άλλα ήδη δημιουργημένα και ονομασμένα. Η δυνατότητα Syntax Locking παγώνει placeholders όπως %s και %1$s ώστε οι μεταβλητές σας να μην αλλοιώνονται ποτέ κατά τη μετάφραση.
Συμπεράσματα
Για να δημιουργήσετε ένα αρχείο POT με τον σωστό τρόπο, πρώτα κάντε τον κώδικά σας ανιχνεύσιμο — περιτυλίξτε κάθε ορατή συμβολοσειρά σε __(), _e(), _x() ή μια παραλλαγή διαφυγής, όλα μοιραζόμενα ένα text domain, και δηλώστε αυτό το domain συν το Domain Path στην κεφαλίδα σας. Στη συνέχεια, δημιουργήστε το πρότυπο με WP-CLI για νέα έργα, Poedit αν προτιμάτε μια GUI, ή makepot μόνο κατά τη συντήρηση παλαιού κώδικα.
Δημιουργήστε νωρίς, αναδημιουργήστε συχνά και μην αφήσετε ποτέ το πρότυπό σας να μείνει πίσω από τον κώδικά σας. Ένα ενημερωμένο .pot είναι η διαφορά ανάμεσα σε ένα plugin που είναι πραγματικά έτοιμο για τον κόσμο και σε ένα που μόνο ισχυρίζεται ότι είναι.
Έτοιμοι να μετατρέψετε το πρότυπο
.potσε ολοκληρωμένες μεταφράσεις χωρίς τον χειροκίνητο χορό μεταγλώττισης; Δοκιμάστε το SimplePoTranslate δωρεάν — δεν απαιτείται πιστωτική κάρτα. Ανεβάστε το πρότυπό σας στη δωρεάν βαθμίδα και κατεβάστε έτοιμα προς αποστολή αρχεία μετάφρασης σε λίγα λεπτά.