Cum să traduci un plugin WordPress (Pas cu pas)

Ai găsit pluginul WordPress perfect pentru proiectul tău. Face exact ce ai nevoie, recenziile sunt excelente, iar apoi îl activezi și îți dai seama că fiecare buton, etichetă și mesaj de eroare este în engleză. Vizitatorii tăi germani, francezi sau japonezi sunt pe cale să întâlnească un zid de text pe care nu-l pot citi.

Vestea bună este că majoritatea pluginurilor bine construite sunt pregătite pentru traducere (translation-ready), ceea ce înseamnă că dezvoltatorul și-a inclus șirurile de caractere în funcții Gettext special pentru ca oameni ca tine să le poată traduce. Provocarea este să știi unde se află fișierele, cum să-ți denumești traducerea și unde să o plasezi, astfel încât următoarea actualizare a pluginului să nu-ți șteargă munca.

Acest ghid îți arată cum să traduci un plugin WordPress de la început până la sfârșit: găsirea domeniului de text și a folderului pentru limbi, obținerea sau generarea șablonului .pot, construirea fișierelor .po și .mo denumite corect și plasarea lor acolo unde WordPress le va încărca în mod fiabil. Vom aborda, de asemenea, singurul tip de plugin pe care această abordare nu-l poate traduce integral, pentru a nu pierde ore luptându-te cu un caz imposibil.

Cum găsești fișierele de traducere ale unui plugin?

Înainte de a traduce orice, ai nevoie de două informații de la plugin: domeniul său de text și folderul său de limbi. Domeniul de text este șirul unic pe care pluginul îl folosește pentru a-și identifica propriile traduceri, iar folderul de limbi este locul unde se află șablonul sursă.

Localizarea folderului de limbi și a domeniului de text

Deschide directorul pluginului la wp-content/plugins/your-plugin/ și caută un subfolder /languages. În interior, vei găsi de obicei un fișier .pot, șablonul gol care conține fiecare șir de caractere traductibil.

Pentru a confirma domeniul de text, deschide fișierul PHP principal al pluginului și privește blocul său de antet:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Aici, domeniul de text este awesome-plugin. Această valoare este crucială, deoarece fișierele tale de traducere trebuie să o includă în numele lor, altfel WordPress nu le va potrivi niciodată cu pluginul. O vei vedea, de asemenea, în fiecare apel de șir de-a lungul codului:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Cel de-al doilea argument, awesome-plugin, este din nou domeniul de text. Fiecare șir care îl utilizează poate fi tradus de catalogul tău. Dacă un șir din interfața pluginului îi lipsește această încadrare, de exemplu un dezvoltator care a codat echo 'Save' fără __(), atunci acel șir nu este traductibil deloc și niciun fișier .po nu îl poate atinge. Majoritatea pluginurilor reputabile încadrează totul corect, dar dacă observi unul sau două șiruri încăpățânate care refuză să se traducă, o încadrare Gettext lipsă în sursă este un posibil vinovat.

O modalitate rapidă de a evalua dacă un plugin este cu adevărat pregătit pentru traducere este să verifici listarea sa în directorul WordPress.org, care afișează un procent de traducere și linkuri către un șablon /languages. Un plugin cu un proiect de traducere activ este mult mai probabil să aibă șiruri curate, complet încadrate, decât unul abandonat.

Ce se întâmplă dacă pluginul nu are un fișier POT?

Unele pluginuri sunt livrate fără un șablon .pot. Dacă folderul /languages este gol sau lipsește, trebuie să generezi tu șablonul prin scanarea codului sursă pentru șirurile de caractere traductibile.

Instrumentul standard pentru aceasta este WP-CLI, care extrage fiecare apel Gettext într-un .pot nou.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

Această comandă parcurge fișierele PHP și JavaScript ale pluginului, găsește fiecare __(), _e(), _n() și apelurile conexe și scrie un șablon complet. Dacă preferi o rută grafică, Poedit Pro poate scana codul sursă în același mod. Oricum ar fi, rezultatul este un .pot care conține toate șirurile sursă cu traduceri goale, gata să fie transformat într-un fișier lingvistic real.

Generarea propriului șablon are un beneficiu ascuns: captează șiruri pe care dezvoltatorul original ar fi putut uita să le includă într-un .pot livrat. Pluginurile evoluează rapid, iar un șablon care a venit cu versiunea 2.1 ar putea să nu conțină șiruri adăugate în 2.4. Regenerarea din sursa curentă garantează că catalogul tău reflectă ceea ce pluginul afișează de fapt astăzi, nu ceea ce afișa acum două lansări. Dacă menții traduceri pentru un plugin de-a lungul timpului, reexecutarea make-pot după fiecare actualizare majoră este un obicei fiabil.

Crearea fișierelor PO și MO cu numele corect

Cea mai comună greșeală la traducerea unui plugin este numele fișierului. WordPress găsește traducerile pluginurilor potrivind un model foarte specific, iar un caracter greșit înseamnă că traducerea ta este ignorată în totalitate.

Formula numelui fișierului

Pentru traducerile de pluginuri, modelul este text-domain-locale. Deci, pentru domeniul de text awesome-plugin tradus în germană, fișierele trebuie să fie denumite:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

Codul local este codul de limbă al site-ului WordPress: de_DE pentru germană, fr_FR pentru franceză, es_ES pentru spaniolă, pt_BR pentru portugheza braziliană. Dacă greșești localul, WordPress îți va sări peste fișier în tăcere. Le creezi din șablonul .pot într-un editor precum Poedit, care compilează fișierul binar .mo automat la salvare. Dacă ești nou în acel editor, ghidul complet Poedit parcurge pas cu pas crearea unei traduceri dintr-un șablon.

Unde să plasezi fișierele, astfel încât actualizările să nu le șteargă

Există două locații posibile, iar alegerea celei corecte contează.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Folosește întotdeauna wp-content/languages/plugins/. WordPress verifică mai întâi acest director de suprascriere și, deoarece se află în afara folderului pluginului, actualizarea pluginului nu îți va afecta niciodată traducerile. Fișierele plasate în folderul propriu al pluginului sunt suprascrise în momentul în care se instalează o nouă versiune.

Acest comportament de suprascriere este una dintre cele mai utile și mai puțin cunoscute caracteristici ale localizării WordPress. Înseamnă că poți livra traduceri personalizate sau corectate pentru orice plugin terț fără a-l „furca” vreodată, iar modificările tale sunt complet sigure în fața actualizărilor. Dacă administrezi mai multe site-uri client care rulează același plugin, poți chiar să păstrezi un singur set de fișiere .mo de suprascriere și să le implementezi pe toate, știind că fiecare site le va prelua automat atâta timp cât se potrivește localul.

Cum încarcă WordPress traducerea ta

Un plugin pregătit pentru traducere îi spune lui WordPress să-și încarce catalogul apelând load_plugin_textdomain() în timpul inițializării:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

Pentru majoritatea pluginurilor moderne pe WordPress 4.6 și versiunile ulterioare, nu este nevoie să atingi acest lucru. WordPress încarcă automat traducerile din wp-content/languages/plugins/ atâta timp cât numele fișierului și localul site-ului se potrivesc. Dacă traducerea finalizată nu apare totuși, cauza este aproape întotdeauna o nepotrivire a numelui fișierului, un .mo vechi sau o limbă a site-ului setată la un local greșit. Ghidul nostru de depanare pentru traduceri care nu apar parcurge fiecare dintre aceste puncte de eșec.

Pluginuri care stochează șiruri de caractere în baza de date

Aici este limitarea importantă. Abordarea Gettext traduce doar șirurile de caractere care se află în codul pluginului. Unele pluginuri, în special constructoarele de formulare, constructoarele de pagini și extensiile de comerț electronic, îți permit să creezi conținut (etichete de formulare, atribute de produs, mesaje personalizate) care este salvat în baza de date WordPress. Acele șiruri de caractere sunt date generate de utilizator, nu fac parte din .pot, astfel încât un fișier .po nu le poate accesa. Pentru conținutul bazei de date ai nevoie de un plugin multilingv precum WPML sau Polylang, sau de propria funcție de traducere a șirurilor de caractere a pluginului. Testează întotdeauna dacă un anumit șir de caractere se află în cod sau în baza de date înainte de a presupune că un fișier .po îl poate rezolva.

Un test simplu îți spune cu ce tip de șir ai de-a face. Dacă textul este ceva ce ai tastat într-un câmp de setări, o etichetă de formular pe care ai creat-o, un mesaj personalizat de mulțumire, un nume de produs, este conținut de bază de date și un .po nu-l poate atinge. Dacă textul face parte din interfața încorporată a pluginului, etichete de butoane, erori de validare, notificări de administrare livrate cu pluginul în sine, acesta se află în cod și un fișier .po este instrumentul potrivit. Trasarea acestei linii devreme economisește ore de frustrare, deoarece nicio cantitate de editare perfectă .po nu va traduce vreodată un șir pe care pluginul îl extrage din baza de date la rulare.

Traducerea la scară fără efort manual

Traducerea unui singur plugin într-o singură limbă, manual, este gestionabilă. Traducerea lui în zece limbi, sau traducerea unui întreg set de pluginuri pentru un site client, se transformă în zile de muncă repetitivă, iar fiecare editare manuală riscă să încurce un placeholder precum %s sau %1$s și să strice rezultatul.

Aici un flux de lucru în cloud schimbă ecuația. Încarcă fișierul .po sau .pot al pluginului pe SimplePoTranslate, alege limbile țintă, iar AI-ul conștient de context traduce întregul catalog, în timp ce Syntax Locking blochează fiecare placeholder, etichetă HTML și token de cod, astfel încât nimic să nu se poată strica. Smart Batching gestionează cataloage mari într-o singură trecere, și descarci un ZIP care conține .po, .mo, .json, .php și .xliff împreună, formatate corect și gata de a fi plasate în wp-content/languages/plugins/. Rulează în întregime în cloud, deci nu există instalare pe desktop și nici supraîncărcare pe site-ul tău.

Reține că traducerea unui plugin diferă de traducerea unei teme, care utilizează o convenție de foldere și o funcție de încărcare ușor diferite. Dacă o temă este ținta ta, urmează în schimb ghidul nostru dedicat despre localizarea oricărei teme WordPress chiar dacă nu ești dezvoltator.

Folosește calea manuală atunci când ai un singur plugin și o singură limbă. Folosește cloud-ul atunci când ai nevoie de multe limbi, rapid, fără a compromite siguranța placeholder-urilor.

Ești gata să-ți traduci pluginul WordPress în fiecare limbă pe care o vorbește publicul tău fără a strica o singură variabilă? Încearcă SimplePoTranslate gratuit — nu este necesar un card de credit. Nivelul gratuit îți permite să traduci primul tău fișier .po al pluginului în câteva minute, cu Syntax Locking activat pentru fiecare șir de caractere.