Hogyan hozzunk létre egy .pot fájlt egy téma vagy bővítmény számára
Épp most fejezett be egy WordPress bővítményt, amit meg szeretne osztani a világgal. A kód működik, a funkciók stabilak, és valaki Németországból e-mailben megkérdezi, hogyan fordíthatná le németre. Rámutat a languages mappára, és rájön, hogy semmi sincs ott. Nincs sablon, nincsenek stringek, a fordító még azt sem tudja, mit kell fordítani. A bővítménye technikailag csak nevében „fordításra kész”.
Minden fordítható WordPress projekt egy fájllal kezdődik: a .pot sablonnal. Mielőtt bárki német, francia vagy japán verziót készítene, létre kell hoznia egy POT fájlt, amely felsorolja a kódjában lévő összes felhasználói felületen megjelenő stringet. Hagyja ki ezt a lépést, és a fordítók sorról sorra fogják olvasni a forráskódot, találgatva, mely stringeknek kellene láthatónak lenniük.
Ez az útmutató a munka két felén vezeti végig: a forráskód előkészítésén, hogy a stringek megtalálhatóak legyenek, majd magának a .pot fájlnak a generálásán három különböző eszközzel. Használni fogjuk a WP-CLI-t, a Poedit-et és a régebbi makepot/grunt megközelítést, valós, másolható parancsokkal. A végére egy tiszta sablonja lesz, amelyet bármely fordítónak átadhat.
Első lépés: Jelölje meg a stringjeit fordíthatóként
Mielőtt létrehozhatna egy POT fájlt, minden olyan stringet, amelyet egy felhasználó láthat, be kell csomagolni egy Gettext függvénybe. Egy szkenner csak azokat a stringeket tudja kinyerni, amelyeket felismer, és ezeket a függvényhívások alapján ismeri fel — az egyszerű string literálok láthatatlanok számára.
A WordPress a lokalizációs függvények egy családját biztosítja, mindegyik kissé eltérő kontextushoz:
// 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' );
Minden hívás második argumentuma — 'my-plugin' — a text domain. Ez egyetlen névtér alá csoportosítja egy bővítmény vagy téma összes stringjét, így a WordPress tudja, melyik .mo fájlt töltse be számukra. A projektjében szereplő minden fordítható stringnek pontosan ugyanazt a text domaint kell használnia, különben néhány string soha nem fog lefordításra kerülni.
Használja az _x() függvényt, amikor egy szó kétértelmű. Az angol „Post” lehet főnév vagy ige, és sok nyelv különbözőképpen fordítja őket. A kontextus stringek segítik a fordítókat a megkülönböztetésben. És nyúljon az esc_html__() és esc_attr__() változatokhoz, amikor a lefordított string HTML-be kerül kiírásra, így egyszerre marad biztonságos és lokalizált.
Néhány szokás segíti a stringek kinyerhetőségét. Mindig egyszerű string literált adjon át első argumentumként — soha ne változót vagy összefűzést, mint például __( 'Hello ' . $name, 'my-plugin' ), mert a szkenner statikusan olvassa a forrásszöveget, és nem tudja feloldani a futásidejű értékeket. Számot tartalmazó mondatokhoz használja az _n() függvényt, hogy a többes számú alakok helyesen legyenek rögzítve, és dinamikus értékű mondatokhoz használja a sprintf() függvényt egy placeholder, például %s köré, ahelyett, hogy a stringeket összeragasztaná. Az itt lévő következetesség az, ami a következő lépést — a sablon generálását — teljessé és használhatóvá teszi.
Második lépés: Deklarálja a Text Domaint a fejlécben
A WordPressnek két fejlécmezőre van szüksége ahhoz, hogy tudja, hol találhatók a fordítások: a Text Domain-re és a Domain Path-re. Állítsa be őket a bővítmény fő fájljában vagy a téma style.css fájljában, és a WordPress futásidőben automatikusan betölti a megfelelő .mo fájlt.
<?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
*/
A Text Domain-nek meg kell egyeznie azzal a stringgel, amit minden __() és _e() hívásnak átadott — itt my-plugin. A Domain Path megmondja a WordPressnek, melyik almappa tartalmazza a fordítási fájlokat, a bővítmény vagy téma gyökérkönyvtárához képest. A konvenció /languages, és pontosan itt kell lennie a generált .pot fájljának.
Miután a stringek be vannak csomagolva, és a fejléc deklarálva van, a kódja készen áll a szkennelésre. A projekt fordításra való előkészítésének tágabb képe — beleértve azokat a témákat is, amelyek nem az Ön tulajdonában vannak — ebben a cikkben található: hogyan lokalizálhat bármilyen WordPress témát, még akkor is, ha nem fejlesztő.
Hogyan generálható a .pot fájl? Három módszer
A .pot fájlt úgy generálja, hogy futtat egy szkennert a forráskódján, amely megtalálja az összes Gettext hívást, és beírja a stringeket egy sablonba. Íme három megbízható módszer erre, a modern alapértelmezettől a régebbi megközelítésig.
1. módszer: WP-CLI (Ajánlott)
A POT fájl létrehozásának hivatalos, modern módja a WP-CLI az i18n paranccsal. A WordPress alapvető eszközkészletének része, érti a PHP és JavaScript stringeket, és egy sorban szabványos sablont készít.
# 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
Az első argumentum a forráskönyvtár (. az aktuális mappához), a második pedig a kimeneti útvonal. A WP-CLI végigmegy a fájljain, kinyeri az összes becsomagolt stringet, megjegyzi a forrásfájlt és a sor számát megjegyzésként, és megírja a .pot fájlt. Gyors, szkriptelhető, és a megfelelő választás bármilyen komoly projekthez.
A generált sablon hasznos metaadatokat tartalmaz, amelyeket extra jelzőkkel finomhangolhat. Adja át a --headers kapcsolót a projekt nevének, verziójának és a fordítók elérhetőségének beállításához, hogy a .pot fejlécblokkja helyesen legyen kitöltve, ne pedig placeholderként maradjon. A WP-CLI automatikusan kinyeri a JavaScript stringeket a wp_set_script_translations() hívásokból is, ami fontos a modern blokk-témák és Gutenberg bővítmények esetében, ahol a felhasználói felületen megjelenő szöveg fele JavaScriptben, nem pedig PHP-ben található. Egyetlen parancs lefedi mindkét világot.
2. módszer: Poedit (Grafikus)
Ha az asztali alkalmazásokat kedveli, a Poedit képes átvizsgálni a forráskódot és sablont generálni az interfészén keresztül. Nyissa meg a Poeditet, válassza az új fordítás létrehozását POT-ból vagy a források közvetlen szkennelését, mutasson rá a projektmappájára, és konfigurálja a forráskulcsszavakat (__, _e, _x, esc_html__) a katalógus tulajdonságai alatt.
A Poedit forráskód-szkennelő és .pot generáló funkciói a Pro kiadásában találhatók, de a munkafolyamat barátságos azoknak a fejlesztőknek, akik inkább kattintanak, mint parancsokat írnak be. Ez egy megbízható szerkesztő a következő fordítási fázishoz is. A Poeditet és számos más asztali lehetőséget összehasonlítunk a Top 5 ingyenes eszköz PO fájlok szerkesztéséhez és fordításához Mac és Windows rendszeren cikkben.
3. módszer: makepot / grunt (Örökség)
A WP-CLI előtt a standard eszköz a makepot.php szkript volt a WordPress i18n-tools repozitóriumából, gyakran Grunt build feladatba integrálva a grunt-wp-i18n segítségével. Régebbi bővítményekben és témákban még találkozhat vele.
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
Működik, de a WP-CLI-hez képest karbantartatlan és lassabb a beállítása. Csak akkor használja, ha egy olyan régebbi projektet tart karban, amely már függ tőle; minden új projekthez inkább a wp i18n make-pot parancsot részesítse előnyben.
Tartsa naprakészen a sablont, ahogy a kódja változik
A .pot a stringjeinek egy pillanatfelvétele. Minden alkalommal, amikor hozzáad egy funkciót, megváltoztat egy címkét, vagy kijavít egy elírást egy látható stringben, a sablon elavul, és a fordítók kihagyják az új megfogalmazást.
Tegye a regenerálást a kiadási rutinja részévé. Futtassa újra a wp i18n make-pot parancsot minden verziófrissítés előtt, majd egyesítse a frissített sablont a meglévő fordításokkal a wp i18n update-po vagy msgmerge segítségével, hogy a fordítók megőrizzék elkészült munkájukat, és csak az új hiányosságokat lássák. Tekintse a .pot fájlt egy generált build műterméknek, ne pedig egy kézzel szerkesztett fájlnak.
Az elavult sablon finom, frusztráló hibát okoz: új stringek jelennek meg angolul még egy „teljesen lefordított” oldalon is, mert soha nem szerepeltek a .pot fájlban, amellyel a fordító dolgozott. Ennek elkerülése olyan egyszerű, mint a regenerálás beillesztése a build folyamatába, így a sablon soha nem maradhat le a kódtól. Néhány csapat hozzáad egy CI ellenőrzést, amely meghiúsítja a buildet, ha a .pot újragenerálása eltérést mutat, ezzel garantálva, hogy a véglegesített sablon mindig megegyezzen az aktuális forráskóddal.
Miután a fordítók visszaküldik a kész .po fájlokat, azokat még le kell fordítani a bináris .mo fájllá, amelyet a WordPress ténylegesen betölt — és ha inkább kihagyná az egész letöltés-fordítás-újrakompilálás hurkot, egy felhőalapú eszköz képes kezelni ezt a folyamatot elejétől a végéig. A SimplePoTranslate közvetlenül fogadja az Ön .pot fájlját, lefordítja kontextusfüggő mesterséges intelligencia segítségével, amely megérti, mit jelent az egyes stringek az interfészében, és egyetlen ZIP fájlt ad vissza a már elkészült és elnevezett .po, .mo és más fájlokkal. A Syntax Locking funkciója rögzíti az olyan placeholder-eket, mint a %s és %1$s, így a változói soha nem törnek el a fordítás során.
Összefoglalás
A POT fájl megfelelő létrehozásához először tegye felfedezhetővé a kódját — csomagoljon be minden látható stringet a __(), _e(), _x() vagy egy escape változaton belül, mindezt egyetlen text domainnel, és deklarálja ezt a domaint, valamint a Domain Path értéket a fejlécében. Ezután generálja a sablont WP-CLI-vel új projektekhez, Poedittel, ha a GUI-t preferálja, vagy makepottal csak örökölt kód karbantartásakor.
Generáljon korán, regeneráljon gyakran, és soha ne hagyja, hogy a sablonja lemaradjon a kódja mögött. Az aktuális .pot jelenti a különbséget egy valóban világra kész bővítmény és egy csak annak mondott között.
Készen áll arra, hogy
.potsablonját kész fordításokká alakítsa a kézi fordítási tánc nélkül? Próbálja ki ingyen a SimplePoTranslate-et — nincs szükség hitelkártyára. Töltse fel sablonját az ingyenes szinten, és töltse le a szállításra kész fordítási fájlokat percek alatt.