Miten luodaan .pot-tiedosto teemaa tai lisäosaa varten

Olet juuri saanut valmiiksi WordPress-lisäosan, jonka haluat jakaa maailman kanssa. Koodi toimii, ominaisuudet ovat vankat, ja joku Saksasta lähettää sähköpostia kysyen, miten se käännetään saksaksi. Osoitat heidät languages-kansioon ja huomaat, ettei siellä ole mitään. Ei mallia, ei merkkijonoja, ei edes tapaa, jolla kääntäjä voisi tietää, mitä pitää kääntää. Lisäosasi on teknisesti ottaen vain nimellisesti "käännettävissä".

Jokainen käännettävissä oleva WordPress-projekti alkaa yhdellä tiedostolla: .pot-mallilla. Ennen kuin kukaan voi tuottaa saksan-, ranskan- tai japaninkielisen version, sinun on luotava POT-tiedosto, joka luettelee kaikki koodissasi olevat käyttäjälle näkyvät merkkijonot. Ohita tämä vaihe, ja kääntäjät joutuvat lukemaan lähdekoodiasi rivi riviltä ja arvailemaan, mitkä merkkijonot ylipäätään on tarkoitettu näkyviksi.

Tämä opas käy läpi työn kaksi puoliskoa: lähdekoodin valmistelun niin, että merkkijonot ovat löydettävissä, ja sitten itse .pot-tiedoston luomisen kolmella eri työkalulla. Käytämme WP-CLI:tä, Poeditia ja perinteistä makepot/grunt-lähestymistapaa, ja mukana on todellisia komentoja, jotka voit kopioida. Lopuksi sinulla on siisti malli valmiina annettavaksi mille tahansa kääntäjälle.

Ensimmäinen vaihe: Merkitse merkkijonot käännettäviksi

Ennen kuin voit luoda POT-tiedoston, jokainen merkkijono, jonka käyttäjä saattaa nähdä, on kiedottava Gettext-funktioon. Skanneri voi poimia vain tunnistamansa merkkijonot, ja se tunnistaa ne näiden funktioiden kutsuista – tavalliset merkkijonoliteraalit ovat sille näkymättömiä.

WordPress tarjoaa joukon lokalisointifunktioita, joista jokainen on tarkoitettu hieman erilaiseen kontekstiin:

// 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' );

Jokaisen kutsun toinen argumentti – 'my-plugin' – on tekstiverkkotunnus (text domain). Se ryhmittelee kaikki lisäosan tai teeman merkkijonot yhden nimiavaruuden alle, jotta WordPress tietää, mikä .mo-tiedosto niille ladataan. Jokaisen käännettävissä olevan merkkijonon projektissasi on jaettava täsmälleen sama tekstiverkkotunnus, tai joitakin merkkijonoja ei koskaan käännetä.

Käytä _x()-funktiota aina, kun sana on moniselitteinen. Englanninkielinen "Post" voi olla substantiivi tai verbi, ja monet kielet kääntävät ne eri tavoin. Kontekstimerkkijonot auttavat kääntäjiä erottamaan ne. Ja käytä esc_html__()- ja esc_attr__()-muunnelmia aina, kun käännetty merkkijono tulostetaan HTML:ään, jotta pysyt turvallisena ja lokalisoituna samanaikaisesti.

Muutama tapa pitää merkkijonosi poimittavina. Syötä aina tavallinen merkkijonoliteraali ensimmäisenä argumenttina – ei koskaan muuttujaa tai ketjutusta kuten __( 'Hello ' . $name, 'my-plugin' ), koska skanneri lukee lähdetekstin staattisesti eikä voi ratkaista ajonaikaisia arvoja. Lauseissa, joissa on luku, käytä _n()-funktiota, jotta monikkomuodot tallennetaan oikein, ja lauseissa, joissa on dynaaminen arvo, käytä sprintf()-funktiota paikkamerkin, kuten %s, ympärillä sen sijaan, että liittäisit merkkijonoja yhteen. Johdonmukaisuus tässä on se, mikä saa seuraavan vaiheen – mallin luomisen – tuottamaan täydellisen ja käyttökelpoisen tuloksen.

Toinen vaihe: Määrittele tekstiverkkotunnus otsikkoosi

WordPress tarvitsee kaksi otsikkokenttää tietääkseen, missä käännöksesi sijaitsevat: Text Domain ja Domain Path. Määrittele ne lisäosan päätiedostoon tai teeman style.css-tiedostoon, ja WordPress lataa automaattisesti oikean .mo-tiedoston ajon aikana.

<?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 Domainin on vastattava merkkijonoa, jonka annoit jokaiselle __()- ja _e()-kutsulle – tässä my-plugin. Domain Path kertoo WordPressille, missä alikansiossa käännöstiedostot sijaitsevat, suhteessa lisäosan tai teeman juureen. Yleinen käytäntö on /languages, ja juuri sinne luodun .pot-tiedoston tulisi sijoittua.

Kun merkkijonot on kiedottu ja otsikko määritelty, koodisi on valmis skannattavaksi. Laajemmin projektin valmistelusta käännöstä varten – mukaan lukien teemat, jotka eivät ole omia – kerrotaan artikkelissa how to localize any WordPress theme even if you are not a developer.

Miten .pot-tiedosto luodaan? Kolme tapaa

Luot .pot-tiedoston ajamalla skannerin lähdekoodisi yli, joka löytää kaikki Gettext-kutsut ja kirjoittaa merkkijonot malliin. Tässä on kolme luotettavaa tapaa tehdä se, modernista oletuksesta perinteiseen lähestymistapaan.

Tapa 1: WP-CLI (suositus)

Virallinen, moderni tapa luoda POT-tiedosto on WP-CLI i18n-komennolla. Se toimitetaan osana WordPressin ydintyökaluja, ymmärtää PHP- ja JavaScript-merkkijonoja ja tuottaa standardien mukaisen mallin yhdellä rivillä.

# 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

Ensimmäinen argumentti on lähdehakemisto (. tarkoittaa nykyistä kansiota), ja toinen on tulostuspolku. WP-CLI käy läpi tiedostosi, poimii jokaisen kiedotun merkkijonon, tallentaa lähdetiedoston ja rivinumeron kommenttina ja kirjoittaa .pot-tiedoston. Se on nopea, skriptattava ja oikea valinta mihin tahansa vakavaan projektiin.

Luotu malli sisältää hyödyllistä metatietoa, jota voit säätää lisälippuilla. Anna --headers-lippu asettaaksesi projektin nimen, version ja kääntäjien yhteystiedot, jotta .pot-otsikkolohko täytetään oikein eikä jätetä paikkamerkeiksi. WP-CLI poimii myös JavaScript-merkkijonot wp_set_script_translations()-kutsuista automaattisesti, mikä on tärkeää moderneille lohkoteemoille ja Gutenberg-lisäosille, joissa puolet käyttäjälle näkyvästä tekstistä on JavaScriptissä PHP:n sijaan. Yksi komento kattaa molemmat maailmat.

Tapa 2: Poedit (graafinen)

Jos pidät työpöytäsovelluksista, Poedit voi skannata lähdekoodisi ja luoda mallin käyttöliittymänsä kautta. Avaa Poedit, valitse luoda uusi käännös POT-tiedostosta tai skannata lähteet suoraan, osoita se projektikansioosi ja määritä lähdeavainsanat (__, _e, _x, esc_html__) luettelon ominaisuuksissa.

Poeditin lähdekoodin skannaus- ja .pot-tiedoston luomisominaisuudet ovat sen Pro-versiossa, mutta työnkulku on ystävällinen kehittäjille, jotka mieluummin napsauttavat kuin kirjoittavat komentoja. Se on myös vankka editori seuraavassa käännösvaiheessa. Poeditia ja useita muita työpöytäsovelluksia verrataan artikkelissa top 5 free tools to edit and translate PO files on Mac and Windows.

Tapa 3: makepot / grunt (perinteinen)

Ennen WP-CLI:tä standardityökalu oli makepot.php-skripti WordPressin i18n-tools-arkistosta, usein kytkettynä Grunt-rakennustehtävään grunt-wp-i18n-komennolla. Tulet edelleen törmäämään siihen vanhemmissa lisäosissa ja teemoissa.

# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot

Se toimii, mutta sitä ei ylläpidetä verrattuna WP-CLI:hin ja se on hitaampi asentaa. Käytä sitä vain, kun ylläpidät vanhaa projektia, joka jo riippuu siitä; uusiin projekteihin mieluummin wp i18n make-pot.

Pidä malli ajan tasalla koodin muuttuessa

.pot-tiedosto on tilannekuva merkkijonoistasi tietyllä hetkellä. Joka kerta kun lisäät ominaisuuden, muutat tunnustekstiä tai korjaat kirjoitusvirheen näkyvässä merkkijonossa, malli vanhenee ja kääntäjät jäävät paitsi uudesta sanamuodosta.

Tee uudelleenluomisesta osa julkaisurutiiniasi. Suorita wp i18n make-pot uudelleen ennen jokaista versiopäivitystä ja yhdistä sitten päivitetty malli olemassa oleviin käännöksiin wp i18n update-po- tai msgmerge-komennolla, jotta kääntäjät säilyttävät valmiin työnsä ja näkevät vain uudet puutteet. Käsittele .pot-tiedostoa luontivaiheen artefaktina, jonka luot uudelleen, älä tiedostona, jota muokkaat käsin.

Vanhentunut malli aiheuttaa hienovaraisen, turhauttavan virheen: uudet merkkijonot näkyvät englanniksi jopa "täysin käännetyllä" sivustolla, koska niitä ei koskaan ollut siinä .pot-tiedostossa, josta kääntäjä työskenteli. Tämän havaitseminen on yhtä yksinkertaista kuin uudelleenluomisen sisällyttäminen rakennusprosessiin, jotta malli ei koskaan jää jälkeen koodista. Jotkut tiimit lisäävät CI-tarkistuksen, joka keskeyttää rakennuksen, jos .pot-tiedoston uudelleenluominen tuottaa eroja, mikä takaa, että lähetetty malli vastaa aina nykyistä lähdekoodia.

Kun kääntäjät palauttavat valmiit .po-tiedostot, ne on vielä käännettävä binaarimuotoiseksi .mo-tiedostoksi, jonka WordPress itse lataa – ja jos haluat mieluummin ohittaa koko lataus-käännös-uudelleenkäännös-kierron, pilvityökalu voi hoitaa sen kokonaan. SimplePoTranslate hyväksyy .pot-tiedostosi suoraan, kääntää sen Context-Aware AI:n avulla, joka ymmärtää, mitä kukin merkkijono tarkoittaa käyttöliittymässäsi, ja palauttaa yhden ZIP-tiedoston, jossa on jo luotu ja nimetty .po, .mo ja paljon muuta. Sen Syntax Locking jäädyttää paikkamerkit kuten %s ja %1$s, joten muuttujasi eivät koskaan rikkoudu käännöksessä.

Yhteenveto

Jotta voit luoda POT-tiedoston oikealla tavalla, tee ensin koodistasi löydettävää – kiedo jokainen näkyvä merkkijono __()-, _e()-, _x()- tai pakomuunnelmaan, kaikki jakamalla yhden tekstiverkkotunnuksen, ja määrittele tämä verkkotunnus sekä Domain Path otsikkoosi. Luo sitten malli WP-CLI:llä uusiin projekteihin, Poeditilla jos pidät graafisesta käyttöliittymästä, tai makepotilla vain vanhaa koodia ylläpitäessäsi.

Luo aikaisin, luo uudelleen usein, äläkä koskaan anna mallisi jäädä koodisi jälkeen. Ajantasainen .pot-tiedosto on ero lisäosan, joka on aidosti valmis maailmalle, ja sellaisen välillä, joka vain väittää olevansa.

Valmiina muuttamaan .pot-mallisi valmiiksi käännöksiksi ilman manuaalista kääntötyötä? Kokeile SimplePoTranslatea ilmaiseksi — luottokorttia ei tarvita. Lataa mallisi ilmaiseen tasoon ja lataa toimitusvalmiit käännöstiedostot minuuteissa.