I den här delen kommer vi att fokusera på hur man översätter texterna och värderingarna i vårt anpassade Gutenberg-block. Vi använder WP-CLI för att generera nödvändiga filer så att Gutenberg kan ladda våra översättningar när du byter WordPress-språk.
Innan du går vidare med detta måste du ha WP CLI (kommandoradsgränssnitt för WordPress) installerat. Om du inte har det, följ bara guiden på WordPress Handbook for CLI.
För att kortfattat förklara hur man översätter för Javascript (Gutenberg)-skript: WordPress kräver .mofiler för översättning av PHP-filer, men för Javascript kräver WordPress en .jsonfil. Varje Javascript-fil behöver en JSON-fil för översättning. JSON bör ha ett specifikt format (WP CLI genererar det åt oss) med våra översatta strängar. Vi behöver en JSON-fil per språk vi vill översätta till.
Så vad vi behöver göra är att först lägga till gettext-funktionerna (__(), _e()etc.) i våra Javascript-filer och generera en PO-fil som vanligt för vårt tema eller plugin. Eftersom vi har packat in texterna i våra skriptfiler med t.ex. __()bör PO-filen kunna inkludera dem. Sedan gör vi översättningen som vanligt i vår PO-fil. Och så använder vi slutligen WP CLI för att extrahera de nödvändiga strängarna från PO-filen och generera JSON-filer för alla våra Javascript-filer.
Tänk på att dina tema- eller plugin- .po/ .mo-filer aldrig kommer att ha en effekt på dina Javascript-filer – även om de innehåller översatta strängar från våra Javascript-filer.
Implementera översättning i Javascript
Det första steget är att lägga alla texter i vår Javascript-fil i översättningsfunktioner. Om du har hanterat översättning för WordPress i PHP är du förmodligen mycket bekant med funktionerna __(), _e(), esc_html__()och så vidare. WordPress har ett paket wp.i18nsom innehåller dessa funktioner, som fungerar precis som i PHP.
Som med PHP måste du tillhandahålla en textdomändomän (namn/handtag). Det kan vara vad du vill, men håll det kort eftersom du förmodligen kommer att behöva skriva ut det väldigt ofta. För mitt tema har jag ställt in min textdomän med domänen awhitepixel. Så inom PHP kommer jag att göra __('My string', 'awhitepixel')för att översätta strängar, och det kommer att vara exakt samma sak i Javascript-filer.
Låt oss börja redigera vår Javascript-fil. Först måste vi destrukturera __och _efungera från wp.i18npaketet. På grund av Reacts natur kommer du troligen mest eller kanske bara att använda __funktionen.
const { __, _e } = wp.i18n;Och sedan gäller det att hitta alla våra hårdkodade texter i Javascript-filen och uppdatera dem. Tänk på att funktionerna __och _ekräver Javascript-kontext. Det betyder att när vi skriver strängar som till exempel objektegenskapsvärden använder vi __()direkt, men som värden för t.ex. rekvisita måste vi linda in allt { }för att indikera att detta är Javascript-kod.
Till exempel kommer vårt registerBlockTypemed stöd för översättning att se ut så här:
registerBlockType('awp/firstblock', {
title: __('My first block', 'awhitepixel'),
category: 'common',
icon: 'smiley',
description: __('Learning in progress', 'awhitepixel'),
keywords: [__('example', 'awhitepixel'), __('test', 'awhitepixel')],
attributes: {
...Och vad gäller rekvisita, dvs i InspectorControls:
Slå in alla texter du vill stödja översättning för i __()och _e(). Om du har följt den här handledningen steg för steg, borde du inte ha några fall där du behöver använda _e(). När du är klar, kompilera om Javascript, så går vi bort från Javascript.
Ställa in po- och/eller pot-filer
Det här steget varierar lite beroende på vad du redan har gjort och ställt in för ditt tema eller plugin. Du kanske skriver dina Gutenberg-skript i ett nytt och tomt plugin som inte har ställts in för PHP-översättning, eller i ett tema som redan har en textdomän registrerad. Du kanske har PO (och MO)-filer redo, eller så har du bara en POT-fil. Jag ska göra mitt bästa för att täcka alla baser.
Mitt tema eller plugin har redan en po(t)-fil
Om du redan har en PO- eller POT-fil i ditt projekt, har du med största sannolikhet även PHP-funktionen load_theme_textdomain(), load_child_theme_textdomain()eller load_plugin_textdomain()någonstans i din kod. Se till att den registrerade domänen är densamma som du har använt i dina Javascript-filer.
Allt du behöver göra är att ladda PO-filen för språket du vill översätta (eller generera en från POT-filen) i till exempel PoEdit. Klicka på "Uppdatera från kod" (eller liknande i andra program) så att programmet kan skanna alla projektfiler (inklusive våra nyligen uppdaterade Javascript-filer) och uppdatera poolen av strängar för översättning. Strängarna i vår Javascript-fil bör visas. du behöver bara översätta dem som vanligt och spara.
PS: Om du inte kan klicka på "Uppdatera från kod" eller skanna om filerna, har PO-filen förmodligen inte ställts in korrekt. Leta efter tips i nästa avsnitt.
Jag har inga översättningsfiler
Om ditt tema eller projekt inte har ställts in med översättning måste du antingen generera en POT-fil med WP-CLI eller skapa en PO-fil manuellt.
Jag har en grundlig guide i hur man skapar en PO-fil i min Temahandledning för nybörjare – del 8. Inlägget beskriver hur du kan skapa filen och ställa in den korrekt för att söka i dina temafiler, och nyckelorden att söka efter (__, _e, etc.).
Om du hellre vill skapa en POT-fil kan du använda kommandot wp i18n make-pot i WP-CLI, och sedan skapa en PO-fil av den med t.ex. PoEdit. Tänk på att du måste återskapa POT-filen (och sedan PO-filen) varje gång du uppdaterar några strängar i din kod.
Slutresultat
Vad du i slutändan behöver är en PO-fil som har hittat dina Javascript-strängar där dessa har översatts. Jag rekommenderar att du placerar dina översättningsfiler i en separat mapp i ditt tema eller plugin. När vi börjar generera JSON-filer kommer vi att få en hel del filer för översättning och det kommer att vara trevligt att ha dem alla samlade i sin egen mapp.
Som en referenspunkt placerar jag alla översättningsfiler i min theme/assets/lang/. Jag har lagt till en norsk översättning för mitt tema, som heter nb_NO.po, som innehåller de översatta strängarna från vår anpassade block Javascript-fil.
Genererar JSON-filer från po-filen
Nästa steg är att använda WP-CLI för att generera JSON-filer från vår po-fil. För att göra detta använder vi kommandot wp i18n make-json.
Var medveten om att som standard kommer detta kommando att ta ut de översatta strängarna från din PO-fil för användning vid generering av JSON-fil. Detta kan vara besvärligt när du är mitt i utvecklingen av ditt tema eller plugin. För när du lägger till nya eller justerar strängar måste du skanna filerna igen och översätta alla strängar igen (och igen, och igen). Lyckligtvis finns det en flagga till kommandot för att undvika detta.
Låt oss börja! I din terminal navigerar du till din språkkatalog för ditt projekt. Kör följande kommando och hänvisa till din po-fil (som nämnt har jag en nb_NO.pofil redo).
wp i18n make-json nb_NO.po --no-purgeOm du inte har några problem med att ta bort de översatta strängarna från din PO-fil (till exempel om du gör din slutliga build), kan du hoppa över --no-purgeflaggan.
Terminalen bör fråga "Success" och ange hur många JSON-filer som skapades. Om du ser att den genererade två JSON-filer beror det på att den har läst både vår källkods Javascript-fil och byggfilen och genererat en för varje. Om du har fler Javascript-filer i ditt projekt kommer du att få ännu fler JSON-filer.
När detta skrivs (WordPress v 5.3.2 och WP-CLI version 2.4.0) genereras JSON-filerna med språkkoden och en hash – en kryptisk sträng som filnamn. Vi måste hitta rätt och byta namn på den.
Byter namn på JSON-filen och laddar den i PHP
Din språkmapp ser förmodligen ut ungefär så här:
Kom ihåg att kommandot har genererat en JSON-fil per Javascript-fil – och eftersom vi faktiskt har två filer för vårt anpassade block (källan och byggnaden) genererade det två filer. Om din Javascript-kod är uppdelad i flera filer, skulle var och en få två av sina egna JSON-filer.
Om du bara sitter med två JSON-filer (eftersom inga andra Javascript-filer hittades) kan du ta bort en av dem nu. Om du har fler än två måste du öppna JSON-filerna och se vilken fil de är till för. JSON-filerna innehåller en egenskap " source" som talar om vilken Javascript-fil den här JSON-filen är till för. Använd det för att ta reda på vilken JSON-fil du ska behålla. Jag rekommenderar att du hittar den slutliga byggfilen (i motsats till dev-filerna) eftersom denna bör innehålla alla strängar från alla filer.
När du har hittat rätt måste vi byta namn på den. Vi måste byta namn på den för att följa detta mönster:
[textdomain]-[language code]-[script handle].json
Använd textdomänen du har använt överallt (t.ex. __('My string', 'awhitepixel')), lägg till ett bindestreck och språkkoden. Ange sedan ett streck och skripthandtaget du använde för att registrera din Gutenberg Javascript-fil (wp_register_script()). Som referens är min textdomän awhitepixel, min språkkod är nb_NO, och mitt skripthandtag för Gutenberg-skriptet är awp-myfirstblock-js. Så jag byter namn på JSON-filen till:
awhitepixel-nb_NO-awp-myfirstblock-js.json
Be WordPress att ladda vår JSON
Allt som återstår nu är det sista steget – att säga åt WordPress att ladda vår JSON-fil. Vi måste använda funktionen [wp_set_script_translations](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)(). Det här är en ganska ny WordPress-funktion så jag rekommenderar att du lindar in den i en function_exists(). Den accepterar tre parametrar; skripthandtaget för vårt block, textdomänen och sökvägen till vår översättningsmapp (obs: sökvägen, inte webbadressen).
Inuti vår funktion kopplad till init, där vi registrerade vårt blockskript och anrop register_block_typekan vi också anropa denna nya funktion för att ladda vår JSON-översättningsfil. PS: Tänk på att kroken enqueue_block_assetsinte fungerar för att registrera översättningar.
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');
}
});Och det är allt! Ditt block bör nu översättas. Byt WordPress-språket till det språk du översatt till och kontrollera det själv. När jag byter WordPress-språk till norska och lägger till mitt block översätts namnet och allt i det:
