Luo mukautettu Gutenberg-lohko – Osa 8: Käännöstuki

Tässä osassa keskitymme tekstien ja arvojen kääntämiseen mukautetussa Gutenberg-lohkossamme. Luomme WP-CLI:n avulla tarvittavat tiedostot, jotta Gutenberg pystyy lataamaan käännöksemme WordPress-kieltä vaihtaessaan.

Ennen kuin jatkat tätä, sinulla on oltava WP CLI (WordPressin komentoriviliittymä) asennettuna. Jos sinulla ei ole sitä, seuraa vain WordPress Handbook for CLI -opasta.

Selvittääksesi lyhyesti, kuinka Javascript (Gutenberg) -skriptejä käännetään: WordPress vaatii .motiedostoja PHP-tiedostojen kääntämiseen, mutta Javascriptiin WordPress vaatii .jsontiedoston. Jokainen Javascript-tiedosto tarvitsee yhden JSON-tiedoston kääntämistä varten. JSONin tulee olla tietyssä muodossa (WP CLI luo sen meille) käännetyillä merkkijonoillamme. Tarvitsemme yhden JSON-tiedoston kutakin kieltä, jolle haluamme kääntää.

Joten meidän täytyy ensin lisätä gettext-funktiot (__()jne _e().) Javascript-tiedostoihimme ja luoda PO-tiedosto tavalliseen tapaan teemallemme tai laajennuksellemme. Koska olemme käärineet skriptitiedostojemme tekstit esim. -merkillä __(), PO-tiedoston pitäisi pystyä sisällyttämään ne. Sitten teemme käännöksen tavalliseen tapaan PO-tiedostossamme. Ja lopuksi käytämme WP CLI:tä tarvittavien merkkijonojen purkamiseen PO-tiedostosta ja JSON-tiedostojen luomiseen kaikille Javascript-tiedostoillemme.

Muista, että teemasi tai laajennuksesi .po/ .mo-tiedostot eivät koskaan vaikuta Javascript-tiedostoihisi – vaikka ne sisältävätkin Javascript-tiedostoistamme käännettyjä merkkijonoja.

Käännöksen käyttöönotto Javascriptissä

Ensimmäinen askel on kääriä kaikki tekstit Javascript-tiedostoomme käännöstoimintojen sisällä. Jos olet käsitellyt WordPressin käännöksiä PHP:llä, tunnet todennäköisesti hyvin funktiot __(), _e()ja esc_html__()niin edelleen. WordPressillä on paketti wp.i18n, joka sisältää nämä toiminnot, jotka toimivat täsmälleen kuten PHP:ssä.

Kuten PHP:n kohdalla, sinun on annettava tekstiverkkotunnus (nimi/kahva). Se voi olla mitä haluat, mutta pidä se lyhyt, koska sinun on todennäköisesti kirjoitettava se hyvin usein. Teemaani varten olen määrittänyt tekstiverkkotunnukseni verkkotunnuksella awhitepixel. Joten PHP:ssä teen __('My string', 'awhitepixel')merkkijonojen kääntämisen, ja se on täsmälleen sama Javascript-tiedostoissa.

Aloitetaan Javascript-tiedoston muokkaaminen. Ensin meidän täytyy tuhota __ja _efunktio wp.i18npaketista. Reactin luonteesta johtuen käytät todennäköisesti enimmäkseen tai ehkä vain __toimintoa.

const { __, _e } = wp.i18n;

Ja sitten on etsittävä kaikki kovakoodatut tekstimme Javascript-tiedostosta ja päivitettävä ne. Muista, että __ja – _efunktiot vaativat Javascript-kontekstin. Tämä tarkoittaa, että kun kirjoitamme merkkijonoja esimerkiksi objektin ominaisuusarvoiksi, käytämme niitä __()heti, mutta esimerkiksi rekvisiittauksen arvoina meidän täytyy kääriä kaikki sisälle { }osoittamaan, että tämä on Javascript-koodi.

Esimerkiksi registerBlockTypekäännöstukemme näyttää tältä:

registerBlockType('awp/firstblock', {
    title: __('My first block', 'awhitepixel'), 
    category: 'common',
    icon: 'smiley',
    description: __('Learning in progress', 'awhitepixel'),
    keywords: [__('example', 'awhitepixel'), __('test', 'awhitepixel')],
    attributes: {
        ...

Ja mitä tulee rekvisiittiin, eli sisään InspectorControls:

Kääri kaikki tekstit, joiden käännöstä haluat tukea, __()ja _e(). Jos olet noudattanut tätä opetusohjelmaa vaihe vaiheelta, sinulla ei pitäisi olla tapauksia, joissa sinun on käytettävä _e(). Kun olet valmis, käännä Javascript uudelleen, niin siirrymme pois Javascriptistä.

Po- ja/tai pottitiedostojen asettaminen

Tämä vaihe vaihtelee hieman sen mukaan, mitä olet jo tehnyt ja määrittänyt teemallesi tai laajennukselle. Saatat kirjoittaa Gutenberg-skriptejäsi uudessa ja tyhjässä laajennuksessa, jota ei ole määritetty PHP-kääntämiseen, tai teemaan, jolla on jo rekisteröity tekstiverkkotunnus. Sinulla saattaa olla PO- (ja MO)-tiedostoja valmiina tai sinulla voi olla vain POT-tiedosto. Yritän parhaani mukaan peittää kaikki pohjat.

Teemallani tai laajennuksellani on jo po(t)-tiedosto

Jos sinulla on jo projektissasi PO- tai POT-tiedosto, sinulla on todennäköisesti myös PHP-toiminto load_theme_textdomain(), load_child_theme_textdomain()tai load_plugin_textdomain()jossain koodissasi. Varmista, että rekisteröity verkkotunnus on sama, jota olet käyttänyt Javascript-tiedostoissasi.

Sinun tarvitsee vain ladata sen kielen PO-tiedosto, jonka haluat kääntää (tai luoda sellainen POT-tiedostosta), esimerkiksi PoEdit. Napsauta "Päivitä koodista" (tai vastaavaa muissa ohjelmissa), jotta ohjelma voi skannata kaikki projektitiedostot (mukaan lukien äskettäin päivitetyt Javascript-tiedostomme) ja päivittää merkkijonovalikoiman käännöstä varten. Javascript-tiedostomme merkkijonojen pitäisi ilmestyä. Sitten sinun tarvitsee vain kääntää ne normaalisti ja tallentaa.

PS: Jos et voi napsauttaa "Päivitä koodista" tai skannata tiedostoja uudelleen, PO-tiedostoa ei todennäköisesti ole asetettu oikein. Etsi vinkkejä seuraavasta osiosta.

Minulla ei ole käännöstiedostoja

Jos teemaasi tai projektiasi ei ole määritetty kääntämällä, sinun on joko luotava POT-tiedosto WP-CLI:n avulla tai luotava PO-tiedosto manuaalisesti.

Minulla on perusteellinen opas PO-tiedoston luomiseen aloittelijoille suunnatussa Theme Tutorial -oppaassani – osassa 8. Viestissä kuvataan, kuinka voit luoda tiedoston ja määrittää sen oikein etsimään teematiedostoja sekä hakusanat (__, _e, jne.).

Jos haluat mieluummin luoda POT-tiedoston, voit käyttää WP-CLI:ssä komentoa wp i18n make-pot ja sitten luoda siitä PO-tiedosto esim. PoEditillä. Muista, että sinun on luotava uudelleen POT-tiedosto (ja sitten PO-tiedosto) aina, kun päivität koodisi merkkijonoja.

Lopputulos

Viime kädessä tarvitset PO-tiedoston, joka on löytänyt Javascript-merkkijonosi, josta ne on käännetty. Suosittelen sijoittamaan käännöstiedostot erilliseen kansioon teemassasi tai laajennuksessasi. Kun aloitamme JSON-tiedostojen luomisen, saamme käännettäväksi melkoisen määrän tiedostoja, ja on mukavaa säilyttää ne kaikki yhdessä omassa kansiossa.

Viitekohtana sijoitan kaikki käännöstiedostot omaan theme/assets/lang/. Olen lisännyt teemalleni norjankielisen käännöksen nb_NO.po, joka sisältää käännetyt merkkijonot mukautetusta Javascript-lohkotiedostostamme.

Luodaan JSON-tiedostoja po-tiedostosta

Seuraava askel on käyttää WP-CLI:tä JSON-tiedostojen luomiseen po-tiedostostamme. Tätä varten käytämme komentoa wp i18n make-json.

Huomaa, että oletusarvoisesti tämä komento poistaa käännetyt merkkijonot PO-tiedostostasi käytettäväksi JSON-tiedoston luomisessa. Tämä voi olla hankalaa, kun kehität teemaa tai laajennusta. Koska kun lisäät uusia tai säädät merkkijonoja, sinun on skannattava tiedostot uudelleen ja käännettävä kaikki merkkijonot uudelleen (ja uudelleen ja uudelleen). Onneksi komennossa on lippu tämän välttämiseksi.

Aloitetaan! Siirry päätteessäsi projektisi kielihakemistoon. Suorita seuraava komento ja katso po-tiedostoasi (kuten mainittiin, minulla on nb_NO.potiedosto valmiina).

wp i18n make-json nb_NO.po --no-purge

Jos sinulla ei ole ongelmia käännettyjen merkkijonojen poistamisessa PO-tiedostostasi (esimerkiksi jos olet tekemässä lopullista versiota), voit ohittaa --no-purgelipun.

Päätteen tulee kysyä "Onnistuminen" ja ilmoittaa, kuinka monta JSON-tiedostoa luotiin. Jos näet, että se loi kaksi JSON-tiedostoa, tämä johtuu siitä, että se on lukenut sekä lähdekoodimme Javascript-tiedoston että koontitiedoston ja luonut yhden kullekin. Jos projektissasi on enemmän Javascript-tiedostoja, saat vielä enemmän JSON-tiedostoja.

Tätä kirjoittaessa (WordPress v 5.3.2 ja WP-CLI versio 2.4.0) JSON-tiedostot on luotu kielikoodilla ja hashilla – salaperäisellä merkkijonolla tiedostoniminä. Meidän on löydettävä oikea ja nimettävä se uudelleen.

Nimeä JSON-tiedosto uudelleen ja lataa se PHP:ssä

Kielikansiosi näyttää todennäköisesti tältä:

Muista, että komento on luonut yhden JSON-tiedoston Javascript-tiedostoa kohden – ja koska meillä on itse asiassa kaksi tiedostoa mukautetulle lohkollemme (lähde ja rakenne), se loi kaksi tiedostoa. Jos Javascript-koodisi on jaettu useisiin tiedostoihin, jokainen saa kaksi omaa JSON-tiedostoaan.

Jos istut vain kahden JSON-tiedoston kanssa (koska muita Javascript-tiedostoja ei löytynyt), voit poistaa yhden niistä nyt. Jos sinulla on enemmän kuin kaksi, sinun on avattava JSON-tiedostot ja katsottava, mitä tiedostoa varten ne ovat. JSON-tiedostot sisältävät ominaisuuden " source", joka kertoo, mille Javascript-tiedostolle tämä JSON-tiedosto on tarkoitettu. Käytä sitä selvittääksesi, mikä JSON-tiedosto säilytetään. Suosittelen löytämään lopullisen koontitiedoston (toisin kuin dev-tiedostoja), koska sen pitäisi sisältää kaikki merkkijonot kaikista tiedostoista.

Kun olet löytänyt oikean, meidän on nimettävä se uudelleen. Meidän on nimettävä se uudelleen noudattamaan tätä mallia:

[textdomain]-[language code]-[script handle].json

Käytä kaikkialla käyttämääsi tekstiverkkotunnusta (esim __('My string', 'awhitepixel'). ), lisää viiva ja kielikoodi. Anna sitten viiva ja komentosarjan kahva, jolla rekisteröit Gutenberg Javascript -tiedoston (wp_register_script()). Viittauksena tekstiverkkotunnukseni on awhitepixel, kielikoodini on nb_NO, ja Gutenberg-skriptin käsikirjoituskahvani on awp-myfirstblock-js. Joten nimeän JSON-tiedoston uudelleen muotoon:

awhitepixel-nb_NO-awp-myfirstblock-js.json

Pyydä WordPressiä lataamaan JSON

Nyt on jäljellä vain viimeinen vaihe – käskeä WordPressiä lataamaan JSON-tiedostomme. Meidän on käytettävä toimintoa [wp_set_script_translations](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)(). Tämä on melko uusi WordPress-toiminto, joten suosittelen sen käärimistä function_exists(). Se hyväksyy kolme parametria; lohkomme komentosarjakahva, tekstiverkkotunnus ja polku käännöskansioomme (huomaa: polku, ei URL-osoite).

Toiminnossamme, joka on koukussa toimintoon init, johon rekisteröimme lohkoskriptimme ja kutsumme register_block_type, voimme myös kutsua tätä uutta toimintoa ladataksemme JSON-käännöstiedostomme. PS: Muista, että koukku enqueue_block_assetsei toimi käännösten rekisteröinnissä.

add_action('init', function() {
    wp_register_script('awp-myfirstblock-js', ....);
    register_block_type('awp/firstblock', ....
 
    if (function_exists('wp_set_script_translations')) {
        wp_set_script_translations('awp-myfirstblock-js', 'awhitepixel', get_template_directory(). '/assets/lang');
    }
});

Ja siinä kaikki! Lohkosi pitäisi nyt kääntää. Vaihda WordPress-kieli kielelle, jolle käänsit, ja tarkista se itse. Kun vaihdan WordPress-kieleni norjaksi ja lisään lohkoni, nimi ja kaikki siinä oleva käännetään: