Kuinka kääntää WordPress-lisäosa (askel askeleelta)

Löysit täydellisen WordPress-lisäosan projektiisi. Se tekee juuri sen, mitä tarvitset, arvostelut ovat loistavia, ja sitten aktivoit sen ja huomaat, että jokainen painike, otsikko ja virheilmoitus on englanniksi. Saksalaiset, ranskalaiset tai japanilaiset vierailijasi ovat törmäämässä tekstiseinään, jota he eivät osaa lukea.

Hyvä uutinen on, että useimmat hyvin rakennetut lisäosat ovat käännösvalmiita, mikä tarkoittaa, että kehittäjä on kääriytynyt merkkijononsa Gettext-funktioihin nimenomaan siksi, että kaltaisesi ihmiset voivat kääntää ne. Haasteena on tietää, missä tiedostot sijaitsevat, miksi käännöksesi tulisi nimetä ja minne se tulisi sijoittaa, jotta seuraava lisäosan päivitys ei pyyhi työtäsi.

Tämä opas näyttää, kuinka kääntää WordPress-lisäosa alusta loppuun: tekstidomainin ja kielikansion löytäminen, .pot-mallin hankkiminen tai luominen, oikein nimettyjen .po- ja .mo-tiedostojen rakentaminen ja niiden sijoittaminen paikkaan, josta WordPress lataa ne luotettavasti. Käsittelemme myös sen yhden lisäosatyypin, jota tämä lähestymistapa ei voi täysin kääntää, jotta et tuhlaa tunteja taisteluun mahdottoman tapauksen kanssa.

Kuinka löydät lisäosan käännöstiedostot?

Ennen mitään kääntämistä tarvitset kaksi tietoa lisäosasta: sen tekstidomainin ja sen kielikansion. Tekstidomain on ainutlaatuinen merkkijono, jota lisäosa käyttää omien käännöstensä tunnistamiseen, ja kielikansio on paikka, jossa lähdemalli sijaitsee.

Kielikansion ja tekstidomainin paikantaminen

Avaa lisäosan hakemisto kohdasta wp-content/plugins/your-plugin/ ja etsi /languages-alikansiota. Sisältä löydät yleensä .pot-tiedoston, tyhjän mallin, joka sisältää kaikki käännettävissä olevat merkkijonot.

Tekstidomainin vahvistamiseksi avaa lisäosan pää-PHP-tiedosto ja tarkista sen otsikkolohko:

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

Tässä tekstidomain on awesome-plugin. Tämä arvo on kriittinen, koska käännöstiedostojesi on sisällettävä se nimissään tai WordPress ei koskaan vastaa niitä lisäosaan. Näet sen myös jokaisessa merkkijonokutsussa koodissa:

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

Toinen argumentti, awesome-plugin, on jälleen tekstidomain. Jokainen merkkijono, joka käyttää sitä, voidaan kääntää luettelollasi. Jos lisäosan käyttöliittymän merkkijonosta puuttuu tämä kääre, esimerkiksi kehittäjä, joka oli kovakoodannut echo 'Save' ilman __(), niin kyseinen merkkijono ei ole lainkaan käännettävissä, eikä .po-tiedosto voi saavuttaa sitä. Useimmat maineikkaat lisäosat käärivät kaiken oikein, mutta jos huomaat yhden tai kaksi itsepäistä merkkijonoa, jotka kieltäytyvät kääntymästä, puuttuva Gettext-kääre lähdekoodissa on todennäköinen syyllinen.

Nopea tapa arvioida, onko lisäosa todella käännösvalmis, on tarkistaa sen listaus WordPress.org-hakemistosta, joka näyttää käännösprosenttin ja linkit /languages-malliin. Lisäosa, jolla on aktiivinen käännösprojekti, on paljon todennäköisemmin puhtaita, täysin kääriytyneitä merkkijonoja kuin hylätty.

Mitä jos lisäosassa ei ole POT-tiedostoa?

Jotkin lisäosat toimitetaan ilman .pot-mallia. Jos /languages-kansio on tyhjä tai puuttuu, sinun on luotava malli itse skannaamalla lähdekoodi käännettävien merkkijonojen varalta.

Tähän tarkoitukseen standardityökalu on WP-CLI, joka purkaa kaikki Gettext-kutsut uuteen .pot-tiedostoon.

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

Tämä komento käy läpi lisäosan PHP- ja JavaScript-tiedostot, löytää kaikki __(), _e(), _n() ja niihin liittyvät kutsut ja kirjoittaa täydellisen mallin. Jos suosit graafista reittiä, Poedit Pro voi skannata lähdekoodin samalla tavalla. Joka tapauksessa, tulos on .pot, joka sisältää kaikki lähdemerkkijonot tyhjillä käännöksillä, valmiina muunnettavaksi todelliseksi kielitiedostoksi.

Oman mallin luomisessa on piilotettu etu: se tallentaa merkkijonot, jotka alkuperäinen kehittäjä on saattanut unohtaa sisällyttää toimitettuun .pot-tiedostoon. Lisäosat kehittyvät nopeasti, ja version 2.1 mukana tullut malli saattaa puuttua merkkijonoja, jotka on lisätty versiossa 2.4. Uudelleenluominen nykyisestä lähteestä takaa, että luettelosi heijastaa sitä, mitä lisäosa todella näyttää tänään, ei sitä, mitä se näytti kaksi julkaisua sitten. Jos ylläpidät käännöksiä lisäosalle ajan myötä, make-pot-komennon uudelleenkäyttö jokaisen suuren päivityksen jälkeen on luotettava tapa.

PO- ja MO-tiedostojen luominen oikealla nimellä

Yleisin virhe lisäosan kääntämisessä on tiedostonimi. WordPress löytää lisäosan käännökset vastaamalla hyvin tiettyä mallia, ja yksi väärä merkki tarkoittaa, että käännöksesi jätetään kokonaan huomiotta.

Tiedostonimen kaava

Lisäosakäännöksille malli on text-domain-locale. Joten awesome-plugin-tekstidomainille, joka on käännetty saksaksi, tiedostot on nimettävä:

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

Lokaalikoodi on WordPress-sivuston kielikoodi: de_DE saksalle, fr_FR ranskalle, es_ES espanjalle, pt_BR Brasilian portugalille. Jos lokaali on väärin, WordPress ohittaa tiedostosi äänettömästi. Luot nämä .pot-mallista Poeditin kaltaisessa editorissa, joka kääntää binaarisen .mo-tiedoston automaattisesti tallennettaessa. Jos olet uusi käyttäjä kyseisessä editorissa, täydellinen Poedit-opas käy läpi käännöksen luomisen mallista askel askeleelta.

Minne tiedostot sijoitetaan, jotta päivitykset eivät poista niitä

Mahdollisia sijainteja on kaksi, ja oikean valitseminen on tärkeää.

# 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

Käytä aina wp-content/languages/plugins/. WordPress tarkistaa tämän ohitushakemiston ensin, ja koska se sijaitsee lisäosakansion ulkopuolella, lisäosan päivittäminen ei koskaan kosketa käännöksiäsi. Lisäosan oman kansion sisälle sijoitetut tiedostot kirjoitetaan yli heti, kun uusi versio asennetaan.

Tämä ohituskäyttäytyminen on yksi WordPressin lokalisoinnin hyödyllisimmistä ja vähiten tunnetuista ominaisuuksista. Se tarkoittaa, että voit toimittaa mukautettuja tai korjattuja käännöksiä mille tahansa kolmannen osapuolen lisäosalle haarauttamatta sitä koskaan, ja muutoksesi ovat täysin päivitysturvallisia. Jos hallinnoit useita asiakassivustoja, jotka käyttävät samaa lisäosaa, voit jopa säilyttää yhden sarjan .mo-ohitustiedostoja ja ottaa ne käyttöön kaikilla niillä, tietäen, että jokainen sivusto poimii ne automaattisesti, kunhan lokaali täsmää.

Kuinka WordPress lataa käännöksesi

Käännösvalmis lisäosa kehottaa WordPressiä lataamaan luettelonsa kutsumalla load_plugin_textdomain() alustuksen aikana:

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

Useimpien modernien lisäosien kohdalla WordPress 4.6:ssa ja uudemmissa, sinun ei tarvitse koskea tähän. WordPress lataa käännökset automaattisesti wp-content/languages/plugins/-kansiosta, kunhan tiedostonimi ja sivuston lokaali täsmäävät. Jos valmis käännöksesi ei edelleenkään näy, syynä on lähes aina tiedostonimen epäsuhta, vanhentunut .mo-tiedosto tai väärään lokaaliin asetettu sivuston kieli. Vianmääritysoppaamme käännösten näkymättömyydelle WordPressissä käy läpi kaikki nämä epäonnistumispisteet.

Lisäosat, jotka tallentavat merkkijonot tietokantaan

Tässä on tärkeä rajoitus. Gettext-lähestymistapa kääntää vain merkkijonot, jotka sijaitsevat lisäosan koodissa. Jotkin lisäosat, erityisesti lomakerakentajat, sivurakentajat ja verkkokauppalaajennukset, antavat sinun luoda sisältöä (lomakkeiden otsikot, tuoteattribuutit, mukautetut viestit), joka tallennetaan WordPressin tietokantaan. Nämä merkkijonot ovat käyttäjän luomaa dataa, eivätkä ne ole osa .pot-tiedostoa, joten .po-tiedosto ei voi tavoittaa niitä. Tietokantasisällölle tarvitset monikielisen lisäosan, kuten WPML:n tai Polylangin, tai lisäosan oman merkkijonokäännösominaisuuden. Testaa aina, sijaitseeko tietty merkkijono koodissa vai tietokannassa ennen kuin oletat, että .po-tiedosto voi korjata sen.

Yksinkertainen testi kertoo, minkälaisesta merkkijonosta on kyse. Jos teksti on jotain, jonka kirjoitit asetuskenttään, luomasi lomakekentän otsikko, mukautettu kiitosviesti tai tuotteen nimi, se on tietokannan sisältöä, eikä .po-tiedosto voi koskettaa sitä. Jos teksti on osa lisäosan sisäänrakennettua käyttöliittymää, kuten painikkeiden otsikoita, validointivirheitä tai hallintapaneelin ilmoituksia, jotka toimitetaan itse lisäosan mukana, se sijaitsee koodissa, ja .po-tiedosto on juuri oikea työkalu. Tämän rajan vetäminen aikaisin säästää tuntikausia turhautumista, koska täydellinenkään .po-muokkaus ei koskaan käännä merkkijonoa, jonka lisäosa hakee tietokannasta suorituksen aikana.

Kääntäminen suuressa mittakaavassa ilman manuaalista hiontaa

Yhden lisäosan kääntäminen yhdelle kielelle käsin on hallittavissa. Sen kääntäminen kymmenelle kielelle tai kokonaisen lisäosapinon kääntäminen asiakkaan sivustolle muuttuu päivien toistuvaksi työksi, ja jokainen manuaalinen muokkaus voi vahingossa rikkoa paikkamerkin, kuten %s tai %1$s, ja viedä tulosteen sekaisin.

Tässä pilvityönkulku muuttaa tilannetta. Lataa lisäosan .po- tai .pot-tiedosto SimplePoTranslateen, valitse kohdekielet, ja kontekstitietoinen tekoäly kääntää koko luettelon samalla kun Syntax Locking jäädyttää kaikki paikkamerkit, HTML-tagit ja koodimerkit, jotta mikään ei voi rikkoutua. Smart Batching käsittelee suuret luettelot yhdellä kertaa, ja voit ladata ZIP-tiedoston, joka sisältää .po, .mo, .json, .php ja .xliff yhdessä, oikein muotoiltuna ja valmiina pudotettavaksi wp-content/languages/plugins/-kansioon. Se toimii kokonaan pilvessä, joten työpöytäasennusta tai sivustosi kuormitusta ei tarvita.

Huomaa, että lisäosan kääntäminen eroaa teeman kääntämisestä, joka käyttää hieman erilaista kansiokäytäntöä ja lataustoimintoa. Jos teema on kohteesi, noudata sen sijaan erillistä opastamme WordPress-teeman lokalisoinnista, vaikka et olisikaan kehittäjä.

Käytä manuaalista polkua, kun sinulla on yksi lisäosa ja yksi kieli. Käytä pilveä, kun tarvitset monia kieliä nopeasti, tinkimättä paikkamerkin turvallisuudesta.

Oletko valmis kääntämään WordPress-lisäosasi kaikille kielille, joita yleisösi puhuu rikkomatta yhtäkään muuttujaa? Kokeile SimplePoTranslatea ilmaiseksi – luottokorttia ei vaadita. Ilmaisella tasolla voit kääntää ensimmäisen lisäosasi .po-tiedoston minuuteissa, Syntax Locking päällä jokaisessa merkkijonossa.