Hogyan fordítsunk le egy WordPress bővítményt (lépésről lépésre)

Megtalálta a tökéletes WordPress bővítményt a projektjéhez. Pontosan azt teszi, amire szüksége van, a vélemények ragyogóak, majd aktiválja, és rájön, hogy minden gomb, címke és hibaüzenet angolul van. Német, francia vagy japán látogatói olvashatatlan szövegfalba ütköznek.

A jó hír az, hogy a legtöbb jól megépített bővítmény fordításra kész, ami azt jelenti, hogy a fejlesztő a stringjeit Gettext függvényekbe csomagolta kifejezetten azért, hogy az Ön-féle emberek lefordíthassák őket. A kihívás az, hogy tudjuk, hol vannak a fájlok, mi legyen a fordítás neve, és hová tegyük, hogy a következő bővítményfrissítés ne törölje a munkáját.

Ez az útmutató bemutatja, hogyan kell lefordítani egy WordPress bővítményt a kezdetektől a végéig: megtalálni a szövegdomaint és a nyelvi mappát, beszerezni vagy generálni a .pot sablont, létrehozni a helyesen elnevezett .po és .mo fájlokat, és elhelyezni őket oda, ahol a WordPress megbízhatóan betölti azokat. Kitérünk arra a bővítménytípusra is, amelyet ez a megközelítés nem tud teljesen lefordítani, így nem pazarolja óráit egy lehetetlen eset elleni küzdelemre.

Hogyan találja meg egy bővítmény fordítási fájljait?

Mielőtt bármit is lefordítana, két információra van szüksége a bővítményből: a szövegdomainjére és a nyelvi mappájára. A szövegdomain az a egyedi string, amelyet a bővítmény a saját fordításainak azonosítására használ, a nyelvi mappa pedig az, ahol a forrássablon található.

A nyelvi mappa és a szövegdomain megkeresése

Nyissa meg a bővítmény könyvtárát a wp-content/plugins/your-plugin/ útvonalon, és keresse meg a /languages alkönyvtárat. Belül általában talál egy .pot fájlt, az üres sablont, amely minden fordítható stringet tartalmaz.

A szövegdomain megerősítéséhez nyissa meg a bővítmény fő PHP fájlját, és nézze meg a fejléc blokkját:

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

Itt a szövegdomain az awesome-plugin. Ez az érték kritikus fontosságú, mert a fordítási fájljainak tartalmazniuk kell a nevükben, különben a WordPress soha nem fogja őket párosítani a bővítménnyel. A kódban minden stringhívásban látni fogja:

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

A második argumentum, az awesome-plugin, ismét a szövegdomain. Minden string, amely ezt használja, lefordítható a katalógusával. Ha egy string hiányzik a bővítmény felületéről, például egy fejlesztő, aki hardkódolta az echo 'Save' kifejezést a __() nélkül, akkor az a string egyáltalán nem fordítható, és egyetlen .po fájl sem éri el. A legtöbb jó hírű bővítmény mindent helyesen csomagol, de ha egy-két makacs stringet észlel, amelyek nem akarnak lefordítani, akkor valószínűleg egy hiányzó Gettext wrapper a forráskódban a ludas.

Egy gyors módja annak, hogy felmérje, egy bővítmény valóban fordításra kész-e, ha ellenőrzi a WordPress.org címtárban található listáját, amely mutatja a fordítási százalékot és linkeket tartalmaz egy /languages sablonhoz. Egy aktív fordítási projekttel rendelkező bővítmény sokkal nagyobb valószínűséggel rendelkezik tiszta, teljesen becsomagolt stringekkel, mint egy elhagyott.

Mi van, ha a bővítménynek nincs POT fájlja?

Néhány bővítmény .pot sablon nélkül érkezik. Ha a /languages mappa üres vagy hiányzik, akkor Önnek kell generálnia a sablont a forráskód átvizsgálásával a fordítható stringek után.

Ennek standard eszköze a WP-CLI, amely minden Gettext hívást kinyer egy friss .pot fájlba.

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

Ez a parancs végigpásztázza a bővítmény PHP és JavaScript fájljait, megkeresi az összes __(), _e(), _n() és kapcsolódó hívást, majd elkészít egy teljes sablont. Ha a grafikus utat preferálja, a Poedit Pro ugyanígy képes átvizsgálni a forráskódot. Akárhogy is, az eredmény egy .pot fájl, amely az összes forrás stringet tartalmazza üres fordításokkal, készen arra, hogy igazi nyelvi fájllá alakuljon.

Saját sablon generálásának van egy rejtett előnye: rögzíti azokat a stringeket, amelyeket az eredeti fejlesztő esetleg elfelejtett bevenni egy kiadott .pot fájlba. A bővítmények gyorsan fejlődnek, és a 2.1-es verzióval érkezett sablonból hiányozhatnak a 2.4-ben hozzáadott stringek. A jelenlegi forrásból való újragenerálás garantálja, hogy a katalógusa azt tükrözi, amit a bővítmény valójában ma megjelenít, nem pedig azt, amit két kiadással ezelőtt. Ha egy bővítmény fordításait hosszabb ideig karbantartja, akkor minden nagyobb frissítés után a make-pot újra futtatása megbízható szokás.

A PO és MO fájlok létrehozása a helyes névvel

Egy bővítmény fordításakor a leggyakoribb hiba a fájlnév. A WordPress nagyon specifikus mintázat alapján keresi a bővítményfordításokat, és egyetlen rossz karakter azt jelenti, hogy a fordítását teljesen figyelmen kívül hagyja.

A fájlnév képlete

A bővítményfordítások esetében a minta a text-domain-locale. Tehát az awesome-plugin szövegdomain német fordításához a fájloknak a következő nevet kell kapniuk:

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

A locale kód a WordPress webhely nyelvi kódja: de_DE némethez, fr_FR franciához, es_ES spanyolhoz, pt_BR brazil portugálhoz. Ha rosszul adja meg a locale-t, a WordPress némán átugorja a fájlját. Ezeket a .pot sablonból hozhatja létre egy olyan szerkesztőben, mint a Poedit, amely mentéskor automatikusan lefordítja a bináris .mo fájlt. Ha még új a szerkesztőben, a teljes Poedit útmutató lépésről lépésre végigvezeti egy fordítás sablonból történő létrehozásán.

Hová helyezze a fájlokat, hogy a frissítések ne töröljék őket

Két lehetséges hely van, és a helyes kiválasztása számít.

# 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

Mindig használja a wp-content/languages/plugins/ útvonalat. A WordPress először ezt a felülíró könyvtárat ellenőrzi, és mivel a bővítmény mappáján kívül található, a bővítmény frissítése soha nem érinti a fordításait. A bővítmény saját mappájába helyezett fájlokat felülírják, amint egy új verzió települ.

Ez a felülírási viselkedés az egyik leghasznosabb és legkevésbé ismert funkciója a WordPress lokalizációnak. Ez azt jelenti, hogy bármely harmadik féltől származó bővítményhez szállíthat egyedi vagy javított fordításokat anélkül, hogy valaha is elágaztatná azt, és a módosításai teljesen frissítésbiztosak. Ha több ügyféloldalt kezel, amelyek ugyanazt a bővítményt futtatják, akár egyetlen felülírható .mo fájlgyűjteményt is tarthat, és telepítheti azokat mindegyiken, tudva, hogy minden webhely automatikusan felveszi őket, amíg a locale egyezik.

Hogyan tölti be a WordPress a fordítását

A fordításra kész bővítmény arra utasítja a WordPress-t, hogy inicializáláskor töltse be a katalógusát a load_plugin_textdomain() hívásával:

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

A legtöbb modern bővítmény esetében, a WordPress 4.6 és újabb verzióin, ezt nem kell megérintenie. A WordPress automatikusan betölti a fordításokat a wp-content/languages/plugins/ mappából, amíg a fájlnév és a webhely locale megegyezik. Ha a kész fordítás továbbra sem jelenik meg, az ok szinte mindig fájlnév-eltérés, elavult .mo fájl, vagy helytelen locale-ra beállított webhelynyelv. A fordítások megjelenésének hiányát tárgyaló hibaelhárítási útmutatónk végigvezet ezen hibahelyeken.

Bővítmények, amelyek az adatbázisban tárolják a stringeket

Itt van a fontos korlátozás. A Gettext megközelítés csak azokat a stringeket fordítja le, amelyek a bővítmény kódjában élnek. Néhány bővítmény, különösen az űrlapépítők, oldalépítők és e-kereskedelmi kiegészítők, lehetővé teszik olyan tartalom létrehozását (űrlapcímkék, termékattribútumok, egyéni üzenetek), amelyek a WordPress adatbázisában tárolódnak. Ezek a stringek felhasználó által generált adatok, nem részei a .pot fájlnak, így egy .po fájl nem éri el őket. Az adatbázis-tartalomhoz többnyelvű bővítményre, például a WPML-re vagy a Polylangra, vagy a bővítmény saját stringfordítási funkciójára van szüksége. Mindig ellenőrizze, hogy egy adott string a kódban vagy az adatbázisban található-e, mielőtt feltételezné, hogy egy .po fájl meg tudja oldani.

Egy egyszerű teszt megmondja, milyen típusú stringgel van dolga. Ha a szöveg valami olyasmi, amit beírt egy beállítási mezőbe, egy létrehozott űrlapcímke, egy egyéni köszönőüzenet, egy terméknév, az adatbázis-tartalom, és egy .po nem érintheti. Ha a szöveg a bővítmény beépített felületének része, gombcímkék, érvényesítési hibák, adminisztrációs értesítések, amelyek magával a bővítménnyel együtt érkeznek, az a kódban él, és egy .po fájl pontosan a megfelelő eszköz. Ennek a vonalnak a korai meghúzása órányi frusztrációt takarít meg, mert a tökéletes .po szerkesztés semmilyen mértékben nem fogja lefordítani azt a stringet, amelyet a bővítmény futásidőben az adatbázisból húz elő.

Fordítás nagy volumenben kézi munka nélkül

Egy bővítmény egy nyelvre történő kézi fordítása kezelhető. Tíz nyelvre történő fordítása, vagy egy teljes bővítménycsomag fordítása egy ügyféloldal számára napokig tartó ismétlődő munkává válik, és minden kézi szerkesztés magában hordozza a %s vagy %1$s típusú placeholder elrontásának és a kimenet megszakításának kockázatát.

Itt változtatja meg a számokat egy felhőalapú munkafolyamat. Töltse fel a bővítmény .po vagy .pot fájlját a SimplePoTranslate-re, válassza ki a célnyelveket, és a kontextusfüggő AI lefordítja a teljes katalógust, míg a Syntax Locking befagyaszt minden placeholdert, HTML taget és kódtokent, így semmi sem romolhat el. A Smart Batching egyetlen lépésben kezeli a nagy katalógusokat, és Ön letölt egy ZIP fájlt, amely tartalmazza a .po, .mo, .json, .php és .xliff fájlokat együtt, helyesen formázva és készen arra, hogy a wp-content/languages/plugins/ mappába kerüljön. Teljesen a felhőben fut, így nincs asztali telepítés és nincs felesleges tartalom a webhelyén.

Ne feledje, hogy egy bővítmény fordítása eltér egy téma fordításától, amely kissé eltérő mappakonvenciót és betöltési funkciót használ. Ha egy téma a célja, kövesse a bármely WordPress téma lokalizálása, még ha nem is fejlesztő című külön útmutatónkat.

Használja a kézi utat, ha egy bővítménye és egy nyelve van. Használja a felhőt, ha sok nyelvre van szüksége, gyorsan, anélkül, hogy feláldozná a placeholder biztonságot.

Készen áll arra, hogy lefordítsa WordPress bővítményét közönsége minden nyelvére anélkül, hogy egyetlen változót is elrontana? Próbálja ki ingyen a SimplePoTranslate-et – nincs szükség bankkártyára. Az ingyenes szinttel percek alatt lefordíthatja az első bővítmény .po fájlját, minden stringen bekapcsolt Syntax Locking funkcióval.