Cum să creezi un fișier .pot pentru o temă sau un plugin
Tocmai ai terminat un plugin WordPress pe care vrei să-l împărtășești cu lumea. Codul funcționează, funcționalitățile sunt solide, iar cineva din Germania îți trimite un e-mail întrebând cum să-l traducă în germană. Îi îndrumi către folderul languages și realizezi că nu este nimic acolo. Niciun șablon, nicio coardă, niciun mod pentru un traducător să știe măcar ce trebuie tradus. Pluginul tău este tehnic „pregătit pentru traducere” doar cu numele.
Fiecare proiect WordPress traductibil începe cu un singur fișier: șablonul .pot. Înainte ca cineva să poată produce o versiune germană, franceză sau japoneză, trebuie să creezi un fișier POT care listează fiecare șir de caractere vizibil pentru utilizator din codul tău. Sari peste acest pas și traducătorii vor fi nevoiți să citească codul sursă rând cu rând, ghicind care șiruri de caractere sunt menite să fie vizibile.
Acest ghid parcurge cele două jumătăți ale sarcinii: pregătirea codului sursă astfel încât șirurile de caractere să fie detectabile și apoi generarea .pot-ului în sine cu trei instrumente diferite. Vom folosi WP-CLI, Poedit și abordarea veche makepot/grunt, cu comenzi reale pe care le poți copia. Până la final vei avea un șablon curat, gata de a fi înmânat oricărui traducător.
Pasul Unu: Marchează Șirurile de Caractere ca Traductibile
Înainte de a putea crea un fișier POT, fiecare șir de caractere pe care un utilizator l-ar putea vedea trebuie să fie învelit într-o funcție Gettext. Un scaner poate extrage doar șirurile de caractere pe care le recunoaște și le recunoaște prin aceste apeluri de funcții — șirurile de caractere literale simple îi sunt invizibile.
WordPress oferă o familie de funcții de localizare, fiecare pentru un context ușor diferit:
// 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' );
Al doilea argument în fiecare apel — 'my-plugin' — este domeniul textului. Acesta grupează toate șirurile de caractere ale unui plugin sau unei teme sub un singur spațiu de nume, astfel încât WordPress să știe ce fișier .mo să încarce pentru ele. Fiecare șir de caractere traductibil din proiectul tău trebuie să partajeze exact același domeniu de text, altfel unele șiruri de caractere nu vor fi niciodată traduse.
Folosește _x() ori de câte ori un cuvânt este ambiguu. În limba engleză, „Post” poate fi un substantiv sau un verb, iar multe limbi le traduc diferit. Șirurile de caractere de context le permit traducătorilor să le distingă. Și apelează la variantele esc_html__() și esc_attr__() ori de câte ori șirul de caractere tradus este tipărit în HTML, astfel încât să rămâi în siguranță și localizat în același timp.
Există câteva obiceiuri care îți mențin șirurile de caractere extractabile. Întotdeauna transmite un șir de caractere literal simplu ca prim argument — niciodată o variabilă sau o concatenare precum __( 'Hello ' . $name, 'my-plugin' ), deoarece scanerul citește textul sursă static și nu poate rezolva valorile la runtime. Pentru propozițiile cu un număr, folosește _n() astfel încât formele de plural să fie capturate corect, iar pentru propozițiile cu o valoare dinamică, folosește sprintf() în jurul unui placeholder precum %s în loc să lipești șirurile de caractere. Coerența aici este ceea ce face ca pasul următor — generarea șablonului — să producă un rezultat complet și utilizabil.
Pasul Doi: Declară Domeniul Textului în Antetul Tău
WordPress are nevoie de două câmpuri de antet pentru a ști unde se află traducerile tale: Text Domain (Domeniul Textului) și Domain Path (Calea Domeniului). Setează-le în fișierul principal al pluginului tău sau în style.css al temei tale, iar WordPress va încărca automat fișierul .mo potrivit la runtime.
<?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 trebuie să corespundă șirului de caractere pe care l-ai transmis fiecărui apel __() și _e() — my-plugin aici. Domain Path îi spune lui WordPress ce subfolder conține fișierele de traducere, relativ la rădăcina pluginului sau a temei. Convenția este /languages, și exact acolo ar trebui să se afle .pot-ul tău generat.
Cu șirurile de caractere învelite și antetul declarat, codul tău este gata de scanare. Imaginea mai largă a pregătirii unui proiect pentru traducere — incluzând temele care nu îți aparțin — este acoperită în cum să localizezi orice temă WordPress chiar dacă nu ești un dezvoltator.
Cum Generezi Fișierul .pot? Trei Metode
Generezi un .pot rulând un scaner peste codul sursă care găsește fiecare apel Gettext și scrie șirurile de caractere într-un șablon. Iată trei modalități fiabile de a face acest lucru, de la abordarea modernă implicită la cea veche.
Metoda 1: WP-CLI (Recomandat)
Modul oficial și modern de a crea un fișier POT este WP-CLI cu comanda i18n. Vine ca parte a instrumentelor de bază WordPress, înțelege șirurile de caractere PHP și JavaScript și produce un șablon conform standardelor într-o singură linie.
# 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
Primul argument este directorul sursă (. pentru folderul curent), iar al doilea este calea de ieșire. WP-CLI parcurge fișierele tale, extrage fiecare șir de caractere învelit, înregistrează fișierul sursă și numărul liniei ca un comentariu și scrie fișierul .pot. Este rapid, scriptabil și alegerea potrivită pentru orice proiect serios.
Șablonul generat include metadate utile pe care le poți ajusta cu flaguri suplimentare. Transmite --headers pentru a seta numele proiectului, versiunea și adresa de contact a traducătorilor, astfel încât blocul de antet .pot să fie completat corect, mai degrabă decât lăsat ca placeholder-uri. WP-CLI extrage, de asemenea, automat șirurile de caractere JavaScript din apelurile wp_set_script_translations(), ceea ce este important pentru temele moderne bazate pe blocuri și pluginurile Gutenberg, unde jumătate din textul vizibil pentru utilizator se află în JavaScript, mai degrabă decât în PHP. O singură comandă acoperă ambele lumi.
Metoda 2: Poedit (Grafică)
Dacă preferi o aplicație desktop, Poedit poate scana sursa ta și genera șablonul prin interfața sa. Deschide Poedit, alege să creezi o traducere nouă din POT sau să scanezi sursele direct, indică-i folderul proiectului tău și configurează cuvintele cheie sursă (__, _e, _x, esc_html__) sub proprietățile catalogului.
Funcționalitățile de scanare a surselor și de generare a fișierelor .pot din Poedit se găsesc în ediția sa Pro, dar fluxul de lucru este prietenos pentru dezvoltatorii care preferă să dea click în loc să tasteze comenzi. Este, de asemenea, un editor solid pentru faza de traducere care urmează. Poedit și alte câteva opțiuni desktop sunt comparate în top 5 instrumente gratuite pentru a edita și traduce fișiere PO pe Mac și Windows.
Metoda 3: makepot / grunt (Moștenire)
Înainte de WP-CLI, instrumentul standard era scriptul makepot.php din depozitul WordPress i18n-tools, adesea integrat într-o sarcină de construire Grunt cu grunt-wp-i18n. Îl vei întâlni în continuare în pluginuri și teme mai vechi.
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
Funcționează, dar este neîntreținut în comparație cu WP-CLI și mai lent de configurat. Folosește-l doar atunci când întreții un proiect vechi care depinde deja de el; pentru orice proiect nou, preferă wp i18n make-pot.
Menține Șablonul Actualizat pe Măsură ce Codul Tău se Modifică
Un fișier .pot este o imagine de moment a șirurilor tale de caractere. Ori de câte ori adaugi o funcționalitate, modifici o etichetă sau corectezi o greșeală de tipar într-un șir de caractere vizibil, șablonul devine învechit și traducătorii ratează noua formulare.
Fă din regenerare o parte a rutinei tale de lansare. Rulează din nou wp i18n make-pot înainte de fiecare actualizare de versiune, apoi îmbină șablonul actualizat în traducerile existente cu wp i18n update-po sau msgmerge, astfel încât traducătorii să-și păstreze munca finalizată și să vadă doar noile lacune. Tratează fișierul .pot ca pe un artefact de construire pe care îl regenerezi, nu ca pe un fișier pe care îl editezi manual.
Un șablon învechit cauzează o eroare subtilă, frustrantă: șiruri de caractere noi apar în engleză chiar și pe un site „complet tradus”, deoarece nu au fost niciodată în fișierul .pot din care a lucrat traducătorul. Remedirea acestui lucru este la fel de simplă ca scriptarea regenerării în procesul tău de construire, astfel încât șablonul să nu rămână niciodată în urmă codului. Unele echipe adaugă o verificare CI care eșuează construirea dacă regenerarea fișierului .pot produce o diferență, garantând că șablonul comitat se potrivește întotdeauna cu sursa curentă.
Odată ce traducătorii returnează fișiere .po finalizate, acestea trebuie încă compilate în fișierul binar .mo pe care WordPress îl încarcă efectiv — și dacă preferi să sari peste întregul ciclu de descărcare-traducere-recompilare, un instrument cloud o poate gestiona de la un capăt la altul. SimplePoTranslate acceptă direct fișierul tău .pot, îl traduce cu AI conștientă de context care înțelege ce înseamnă fiecare șir de caractere în interfața ta și returnează un singur ZIP cu fișierele .po, .mo și altele deja construite și denumite. Blocarea sa de sintaxă blochează placeholder-uri precum %s și %1$s astfel încât variabilele tale să nu se strice niciodată în traducere.
Concluzie
Pentru a crea un fișier POT în mod corect, mai întâi fă-ți codul detectabil — înfășoară fiecare șir de caractere vizibil în __(), _e(), _x(), sau o variantă de evadare, toate partajând un singur domeniu text, și declară acel domeniu plus Domain Path în antetul tău. Apoi generează șablonul cu WP-CLI pentru proiecte noi, Poedit dacă preferi o interfață grafică, sau makepot doar atunci când întreții cod vechi.
Generează devreme, regenerează des și nu lăsa niciodată șablonul tău să rămână în urmă codului. Un .pot actual este diferența dintre un plugin care este cu adevărat pregătit pentru lume și unul care doar pretinde că este.
Ești gata să transformi șablonul tău
.potîn traduceri finalizate fără procesul manual de compilare? Încearcă SimplePoTranslate gratuit — nu este necesar un card de credit. Încarcă șablonul tău pe nivelul gratuit și descarcă fișiere de traducere gata de expediere în câteva minute.