.po vs .mo vs .pot: WordPressin käännöstiedostot selitettynä

Kun avaat WordPress-teeman languages-kansion, löydät kolme lähes identtiseltä näyttävää tiedostoa: twentytwentyfour.pot, twentytwentyfour-de_DE.po ja twentytwentyfour-de_DE.mo. Sama teema, sama kieli, kolme eri tiedostopäätettä. Mitä niistä muokkaat? Mitä niistä WordPress todella lataa? Ja miksi väärän tiedoston muokkaaminen saa käännöksesi katoamaan äänettömästi?

Jos olet joskus miettinyt, millä tiedostolla on merkitystä .po vs .mo -tiedosto-keskustelussa, et ole yksin. Nämä kolme tiedostopäätettä ovat jokaisen käännetyn WordPress-sivuston selkäranka, silti niiden ero hämmentää niin aloittelijoita kuin kokeneitakin kehittäjiä. Muokkaa väärää tiedostoa, ja saksalaiset vierailijasi näkevät edelleen englantia. Muokkaa oikeaa, mutta ohita yksi vaihe, eikä mitään silti muutu.

Tässä oppaassa selitetään tarkalleen, mitä .pot-, .po- ja .mo-tiedostot ovat, miten ne liittyvät toisiinsa GNU Gettext -työnkulussa, missä ne sijaitsevat WordPressissä, ja miksi sinun ei tulisi koskaan avata .mo-tiedostoa tekstieditorissa. Tämän luettuasi tiedät, mihin tiedostoon koskea ja mitä jättää rauhaan.

Mitä .pot-, .po- ja .mo-tiedostot ovat?

Lyhyesti sanottuna: .pot-tiedosto on tyhjä mallipohja, .po-tiedosto on muokattava käännöksesi, ja .mo-tiedosto on käännetty binääritiedosto, jonka WordPress lukee ajon aikana. Ne muodostavat ketjun, ja jokaisella lenkillä on täsmälleen yksi tehtävä.

Nämä kolme formaattia ovat kaikki peräisin GNU Gettextistä, lokalisaatiojärjestelmästä, johon WordPress, Drupal ja tuhannet PHP- ja C-projektit luottavat. Gettext erottaa kehittäjän kirjoittamat lähdemerkkijonot kääntäjän tarjoamista käännöksistä, jotta sama koodipohja voi puhua kymmeniä kieliä koskematta yhteenkään PHP-riviin.

Ajattele sitä kuin reseptikorttia. .pot on tyhjä kortti, jossa on ainesosien paikat, mutta ei määriä. .po on kortti, joka on täytetty yhdelle tietylle ruokalajille. .mo on laminoitu, koneellisesti luettava kopio, jota keittiö käyttää palvelun aikana. Kirjoitat paperikortille; et koskaan raapusta laminoituun.

.pot-tiedosto: Päämallipohja

.pot-tiedosto (Portable Object Template) sisältää jokaisen käännettävän merkkijonon teemassa tai lisäosassa siten, että käännökset on jätetty tyhjiksi. Se on päälista, jonka kehittäjät toimittavat, jotta kääntäjät tietävät tarkalleen, mitä on käännettävä. msgstr-rivit ovat tyhjiä, koska kieltä ei ole vielä valittu.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr ""

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr ""

Huomaa tyhjä msgstr "". .pot on mallipohja, ei käännös. Kopioit sen kerran per kieli ja täytät tyhjät kohdat. Harvoin muokkaat .pot-tiedostoa käsin; se luodaan uudelleen lähdekoodista aina, kun merkkijonot muuttuvat.

.po-tiedosto: Ihmisen muokattava käännöksesi

.po-tiedosto (Portable Object) on kopio .pot-tiedostosta, jossa msgstr-rivit on täytetty yhdelle kielelle. Tämä on tiedosto, jota kääntäjät ja kehittäjät todella muokkaavat. Se on raakatekstiä, ihmisluettava ja versionhallintaystävällinen.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr "In den Warenkorb"

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr "Ihre Bestellung wurde an %s versandt"

msgid on alkuperäinen englanninkielinen lähdemerkkijono, eikä sitä saa koskaan muuttaa. msgstr on käännöksesi. %s on paikkamerkki, jonka on säilyttävä koskemattomana käännöksessä — sen pudottaminen tai uudelleenjärjestely on yleisin syy rikkinäisiin asetteluihin, mitä käsittelemme perusteellisesti artikkelissa kuinka kääntää PO-tiedostoja rikkomatta koodimuuttujia.

.mo-tiedosto: Käännetty binääritiedosto

.mo-tiedosto (Machine Object) on .po-tiedoston käännetty binääriversio. WordPress ei pysty lukemaan .po-tiedostoja tehokkaasti ajon aikana, joten se lataa esikäännetyn .mo-tiedoston sen sijaan. .mo-tiedoston avaaminen tekstieditorissa näyttää lukukelvottomia tavuja — se on tarkoitettu koneille, ei ihmisille.

Kun WordPress kutsuu load_textdomain()- tai load_theme_textdomain()-funktioita, se etsii .mo-tiedostoa, jäsentää sen binäärisen hajautustaulun ja vaihtaa jokaisen msgid:n vastaavaan msgstr:ään lennossa. Tämä binäärimuoto tekee hausta nopeaa jopa sivustoilla, joilla on tuhansia merkkijonoja.

Miten kolme tiedostoa liittyvät toisiinsa Gettext-työnkulussa?

Ne muodostavat yksisuuntaisen putkilinjan: lähdekoodista tulee .pot, .pot:sta tulee kielikohtainen .po, ja jokainen .po kääntyy .mo:ksi. Käännökset virtaavat aina alaspäin.

Tässä on koko elinkaari järjestyksessä:

1. Kehittäjä käärii käyttäjälle näkyvät merkkijonot Gettext-funktioihin, kuten __() ja _e(), PHP-lähdekoodissa.
2. Skannaustyökalu lukee lähteen ja generoi .pot-mallipohjan, joka sisältää jokaisen käärityn merkkijonon.
3. Kääntäjä kopioi .pot-tiedoston kielikohtaiseen .po-tiedostoon (esimerkiksi de_DE.po) ja täyttää jokaisen msgstr:n.
4. Valmis .po käännetään binääriseksi .mo-tiedostoksi.
5. WordPress lataa .mo-tiedoston ajon aikana ja näyttää käännetyn sivuston.

Kun kehittäjä lisää uusia merkkijonoja myöhemmin, .pot generoidaan uudelleen, uudet merkinnät yhdistetään jokaiseen olemassa olevaan .po-tiedostoon (säilyttäen vanhat käännökset), kääntäjä täyttää aukot, ja .po käännetään uudelleen .mo:ksi. Sykli toistuu projektin elinkaaren ajan.

Kriittinen opetus: muokkaat .po:ta ja sitten käännät sen .mo:ksi. Et koskaan muokkaa .mo:ta suoraan, etkä koskaan käännä .pot:n sisällä. Jos haluat syvemmän kokonaiskuvan, lopullinen opas WordPress-lokalisointiin käy läpi koko putkilinjan esimerkkien kanssa.

Nimeämiskäytännöt ja tiedostojen sijainti

WordPress on tiukka tiedostonimien suhteen. Jos nimeät väärin, täydellisesti käännetty .mo-tiedostosi yksinkertaisesti ohitetaan, koska WordPress etsii tarkan vastaavuuden tekstidomainin ja paikalliskielen perusteella.

Teemojen ja lisäosien käännösten nimeämismalli on:

# Pattern: textdomain-locale.po / .mo
twentytwentyfour-de_DE.po      # German (Germany) translation
twentytwentyfour-de_DE.mo      # compiled binary WordPress loads
twentytwentyfour-fr_FR.po      # French (France)
twentytwentyfour.pot           # template, no locale suffix

textdomain vastaa merkkijonoa, joka välitetään toisena argumenttina Gettext-funktioille, kuten __( 'Add to Cart', 'twentytwentyfour' ). locale on WordPressin paikalliskoodi, kuten de_DE, fr_FR tai pt_BR. .pot-mallipohjassa ei ole paikalliskieliliitettä, koska se on kielineutraali.

Sijainnilla on yhtä paljon merkitystä kuin nimeämisellä. WordPress etsii muutamasta ennustettavasta polusta:

• Teemojen käännökset toimitetaan teeman omassa wp-content/themes/your-theme/languages/-kansiossa.
• Lisäosien käännökset toimitetaan wp-content/plugins/your-plugin/languages/-kansiossa.
• Käännökset osoitteesta translate.wordpress.org ja käyttäjän ohitukset päätyvät globaaleihin wp-content/languages/themes/- ja wp-content/languages/plugins/-hakemistoihin, jotka ovat etusijalla ja säilyvät päivitysten yli.

Aseta oikein nimetty de_DE.mo oikeaan kansioon, ja saksalaiset vierailijat näkevät saksan kieltä. Aseta se yhden kansion liian syvälle, tai kirjoita tekstidomain väärin, ja WordPress palaa hiljaisesti englantiin ilman virheilmoitusta. Jos käännöksesi eivät näy, nimeämis- tai polkuvirhe on yleinen syyllinen, ja ohje puuttuvien käännösten vianmääritykseen käsittelee kaikki yleisimmät syyt.

Miksi .mo-tiedostoa ei tulisi koskaan muokata suoraan

Koska .mo on käännetty binääritiedosto, sitä ei voi turvallisesti muokata käsin — ja kaikki pakottamasi muutokset ylikirjoitetaan seuraavan kerran, kun .po käännetään uudelleen. .po on totuuden lähde; .mo on kertakäyttöinen rakennusjäänne.

Tämä yksittäinen sääntö selittää suuren osan tukipyynnöistä, kuten ”käännökseni muuttui, mutta sivusto ei päivittynyt”. Joku muokkaa merkkijonoa, tallentaa .po:n ja unohtaa kääntää .mo:n uudelleen. WordPress jatkaa vanhan binääritiedoston lataamista, joten uusi sanamuoto ei koskaan näy. Korjaus on aina: muokkaa .po:ta, käännä uudelleen .mo:ksi, lataa uudelleen.

Säännöllä on toinenkin syy, miksi se on tärkeä: .mo-tiedostot eivät ole diff-ystävällisiä versionhallinnassa. Koska ne ovat binäärisiä, pienikin sanamuodon muutos tuottaa läpinäkymättömän kokonaisuuden Git-historiaasi, jota kukaan tarkastelija ei voi lukea. Pitämällä .po:n seurattavana totuuden lähteenä ja käsittelemällä .mo:ta generoituja artefaktina pidät repositorysi tarkistettavana ja käännöksesi auditoitavina.

Tämän tekeminen manuaalisesti kymmenillä kielillä on työlästä ja virhealtista. Tässä kohtaa pilvipohjainen työnkulku säästää todella aikaa. Työkalut kuten SimplePoTranslate kääntävät .po-merkkijonosi ja palauttavat yhden ZIP-tiedoston, joka sisältää vastaavat .po- ja .mo-tiedostot yhdessä — jo käännettynä, oikein nimettynä, valmiina pudotettavaksi wp-content/languages/-kansioon. Ei ole mitään manuaalisesti käännettävää, eikä riskiä vanhentuneesta .mo:sta.

Se soveltaa myös Syntax Locking -ominaisuutta, joka jäädyttää jokaisen paikkamerkin, kuten %s, %1$s ja {name}, sekä HTML-tagit, ennen kääntämistä. Muuttujasi säilyvät ennallaan, joten et koskaan toimita .mo-tiedostoa, joka rikkoisi asettelun. Ja koska se toimii kokonaan pilvessä, sivustoasi ei rasita ylimääräinen lisäosa — lataat tiedoston ja lataat valmiit, käännetyt käännökset.

Kootaan kaikki yhteen

Kun .po vs .mo -tiedosto-ero selkenee, koko WordPressin käännösjärjestelmä lakkaa tuntumasta mystiseltä. .pot on kehittäjän mallipohja, .po on kääntäjän muokattavissa oleva työkopio, ja .mo on käännetty binääritiedosto, jonka WordPress itse asiassa tarjoaa vierailijoille. Käännökset virtaavat yhteen suuntaan — mallipohjasta .po:ksi ja sitten .mo:ksi — ja muokkaat aina vain keskimmäistä käsin.

Muista kolme sääntöä, jotka estävät yhdeksänkymmentä prosenttia käännöspäänsäryistä: älä koskaan käännä .pot-tiedoston sisällä, käännä .mo aina uudelleen .po:n muokkaamisen jälkeen, ja vastaa textdomain-locale-nimeämistä tarkasti. Noudata näitä, niin käännetyt merkkijonosi näkyvät joka kerta.

Valmis lopettamaan kamppailun käännöstiedostojen käsin kääntämisen ja nimeämisen kanssa? Kokeile SimplePoTranslatea ilmaiseksi — luottokorttia ei tarvita. Lataa .po- tai .pot-tiedostosi ja saat valmiin .po + .mo -paketin takaisin ilmaiskerroksella minuuteissa.