Så här skapar du en .pot-fil för ett tema eller tillägg

Du har precis slutfört ett WordPress-tillägg som du vill dela med världen. Koden fungerar, funktionerna är stabila, och någon i Tyskland mejlar och frågar hur man översätter det till tyska. Du hänvisar dem till mappen languages och inser att det inte finns något där. Ingen mall, inga strängar, inget sätt för en översättare att ens veta vad som behöver översättas. Ditt tillägg är tekniskt sett bara "översättningsklart" till namnet.

Varje översättningsbart WordPress-projekt börjar med en fil: .pot-mallen. Innan någon kan skapa en tysk, fransk eller japansk version måste du skapa en POT-fil som listar varje användarriktad sträng i din kod. Hoppa över detta steg och översättare blir tvungna att läsa din källkod rad för rad och gissa vilka strängar som ens är avsedda att vara synliga.

Denna guide går igenom de två delarna av jobbet: att förbereda din källkod så att strängar är upptäckbara, och sedan att generera själva .pot-filen med tre olika verktyg. Vi kommer att använda WP-CLI, Poedit och den äldre makepot/grunt-metoden, med verkliga kommandon som du kan kopiera. I slutet kommer du att ha en ren mall redo att lämna till vilken översättare som helst.

Steg ett: Markera dina strängar som översättningsbara

Innan du kan skapa en POT-fil måste varje sträng en användare kan se omslutas av en Gettext-funktion. En skanner kan bara extrahera strängar den känner igen, och den känner igen dem genom dessa funktionsanrop – rena strängkonstanter är osynliga för den.

WordPress tillhandahåller en familj av lokaliseringsfunktioner, var och en för ett något annorlunda sammanhang:

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

Det andra argumentet i varje anrop – 'my-plugin' – är textdomänen. Den grupperar alla strängar från ett tillägg eller tema under ett namnutrymme så att WordPress vet vilken .mo-fil som ska laddas för dem. Varje översättningsbar sträng i ditt projekt måste dela exakt samma textdomän, annars kommer vissa strängar aldrig att översättas.

Använd _x() när ett ord är tvetydigt. Det engelska "Post" kan vara ett substantiv eller ett verb, och många språk översätter dem olika. Kontextsträngar låter översättare skilja dem åt. Och använd varianterna esc_html__() och esc_attr__() när den översatta strängen skrivs ut i HTML, så att du förblir säker och lokaliserad samtidigt.

Det finns några vanor som håller dina strängar extraherbara. Skicka alltid en ren strängkonstant som första argument – aldrig en variabel eller en sammanfogning som __( 'Hello ' . $name, 'my-plugin' ), eftersom skannern läser källtext statiskt och inte kan lösa värden vid körning. För meningar med ett tal, använd _n() så att pluralformer fångas upp korrekt, och för meningar med ett dynamiskt värde, använd sprintf() runt en platshållare som %s istället för att sammanfoga strängar. Konsekvens här är det som gör att nästa steg – att generera mallen – producerar ett komplett, användbart resultat.

Steg två: Deklarera textdomänen i din sidhuvud

WordPress behöver två sidhuvudsfält för att veta var dina översättningar finns: Text Domain och Domain Path. Ställ in dem i ditt tilläggs huvudfil eller ditt temas style.css, så laddar WordPress automatiskt rätt .mo-fil vid körning.

<?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 Domain måste matcha strängen du skickade till varje anrop av __() och _e() – my-plugin här. Domain Path berättar för WordPress vilken undermapp som innehåller översättningsfilerna, relativt till tilläggets eller temats rot. Konventionen är /languages, och det är precis där din genererade .pot-fil ska finnas.

Med omslutna strängar och deklarerat sidhuvud är din kod redo att skannas. Den bredare bilden av att förbereda ett projekt för översättning – inklusive teman som inte är dina egna – behandlas i så här lokaliserar du ett WordPress-tema även om du inte är utvecklare.

Hur genererar man .pot-filen? Tre metoder

Du genererar en .pot-fil genom att köra en skanner över din källkod som hittar varje Gettext-anrop och skriver strängarna till en mall. Här är tre pålitliga sätt att göra det, från den moderna standarden till den äldre metoden.

Metod 1: WP-CLI (rekommenderas)

Det officiella, moderna sättet att skapa en POT-fil är WP-CLI med kommandot i18n. Det ingår som en del av WordPress kärnverktyg, förstår PHP- och JavaScript-strängar, och producerar en standardkompatibel mall på en enda rad.

# 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

Det första argumentet är källkatalogen (. för den aktuella mappen), och det andra är utdata-sökvägen. WP-CLI går igenom dina filer, extraherar varje omsluten sträng, registrerar källfilen och radnumret som en kommentar, och skriver .pot-filen. Det är snabbt, skriptbart och det rätta valet för alla seriösa projekt.

Den genererade mallen innehåller användbar metadata som du kan justera med extra flaggor. Skicka --headers för att ställa in projektnamn, version och översättarnas kontaktadress, så att .pot-sidhuvudsblocket fylls i korrekt istället för att lämnas som platshållare. WP-CLI extraherar även JavaScript-strängar från wp_set_script_translations()-anrop automatiskt, vilket är viktigt för moderna blockteman och Gutenberg-tillägg där hälften av den användarriktade texten finns i JavaScript snarare än PHP. Ett kommando täcker båda världarna.

Metod 2: Poedit (grafiskt)

Om du föredrar en skrivbordsapp kan Poedit skanna din källkod och generera mallen via sitt gränssnitt. Öppna Poedit, välj att skapa en ny översättning från POT eller skanna källor direkt, peka den mot din projektmapp och konfigurera källnyckelorden (__, _e, _x, esc_html__) under katalogegenskaperna.

Poedit's funktioner för källkodsskanning och .pot-generering finns i dess Pro-utgåva, men arbetsflödet är vänligt för utvecklare som hellre klickar än skriver kommandon. Det är också en stabil redigerare för den översättningsfas som följer. Poedit och flera andra skrivbordsalternativ jämförs i topp 5 gratis verktyg för att redigera och översätta PO-filer på Mac och Windows.

Metod 3: makepot / grunt (äldre)

Före WP-CLI var standardverktyget makepot.php-skriptet från WordPress i18n-tools-förrådet, ofta kopplat till en Grunt-bygguppgift med grunt-wp-i18n. Du kommer fortfarande att stöta på det i äldre tillägg och teman.

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

Det fungerar, men det underhålls inte i samma utsträckning som WP-CLI och är långsammare att sätta upp. Använd det bara när du underhåller ett äldre projekt som redan är beroende av det; för allt nytt, föredra wp i18n make-pot.

Håll mallen uppdaterad när din kod ändras

En .pot-fil är en ögonblicksbild av dina strängar vid ett tillfälle. Varje gång du lägger till en funktion, ändrar en etikett eller fixar ett stavfel i en synlig sträng, blir mallen inaktuell och översättare missar den nya formuleringen.

Gör omgenerering till en del av din lanseringsrutin. Kör wp i18n make-pot igen före varje versionsuppdatering, slå sedan samman den uppdaterade mallen med befintliga översättningar med wp i18n update-po eller msgmerge så att översättare behåller sitt färdiga arbete och bara ser de nya luckorna. Behandla .pot-filen som en byggartefakt som du omgenererar, inte en fil du redigerar manuellt.

En inaktuell mall orsakar ett subtilt, frustrerande fel: nya strängar visas på engelska även på en "fullständigt översatt" webbplats, eftersom de aldrig fanns i den .pot-fil som översättaren arbetade med. Att upptäcka detta är lika enkelt som att skripta in omgenereringen i din byggprocess, så att mallen aldrig kan släpa efter koden. Vissa team lägger till en CI-kontroll som misslyckas med bygget om omgenerering av .pot-filen producerar en diff, vilket garanterar att den committade mallen alltid matchar den aktuella källan.

När översättare returnerar färdiga .po-filer behöver dessa fortfarande kompileras till den binära .mo-fil som WordPress faktiskt laddar – och om du hellre vill hoppa över hela nedladdnings-, översättnings- och omkompileringsloopen kan ett molnverktyg hantera det från början till slut. SimplePoTranslate accepterar din .pot-fil direkt, översätter den med kontextmedveten AI som förstår vad varje sträng betyder i ditt gränssnitt, och returnerar en enda ZIP-fil med .po, .mo, och mer redan byggda och namngivna. Dess Syntax Locking fryser platshållare som %s och %1$s så att dina variabler aldrig går sönder i översättningen.

Sammanfattning

För att skapa en POT-fil på rätt sätt, gör först din kod upptäckbar – omslut varje synlig sträng med __(), _e(), _x(), eller en flyktvariant, alla delar samma textdomän, och deklarera den domänen plus Domain Path i din sidhuvud. Generera sedan mallen med WP-CLI för nya projekt, Poedit om du föredrar ett GUI, eller makepot endast när du underhåller äldre kod.

Generera tidigt, omgenerera ofta, och låt aldrig din mall hamna efter din kod. En aktuell .pot-fil är skillnaden mellan ett tillägg som verkligen är redo för världen och ett som bara påstår sig vara det.

Redo att förvandla din .pot-mall till färdiga översättningar utan den manuella kompileringsprocessen? Prova SimplePoTranslate gratis – inget kreditkort krävs. Ladda upp din mall på gratistjänsten och ladda ner färdiga översättningsfiler på några minuter.