Sådan opretter du en .pot-fil til et tema eller plugin

Du har netop færdiggjort et WordPress-plugin, du ønsker at dele med verden. Koden fungerer, funktionerne er solide, og en person i Tyskland sender en e-mail og spørger, hvordan man oversætter det til tysk. Du peger dem mod mappen languages og indser, at der intet er. Ingen skabelon, ingen strenge, ingen måde for en oversætter overhovedet at vide, hvad der skal oversættes. Dit plugin er teknisk set kun "oversættelsesparat" af navn.

Ethvert oversætteligt WordPress-projekt starter med én fil: .pot skabelonen. Før nogen kan producere en tysk, fransk eller japansk version, skal du oprette en POT-fil, der lister alle brugerrettede strenge i din kode. Spring dette trin over, og oversættere vil sidde fast med at læse din kildekode linje for linje og gætte, hvilke strenge der overhovedet er beregnet til at være synlige.

Denne guide gennemgår de to halvdele af opgaven: at forberede din kildekode, så strenge kan findes, og derefter at generere selve .pot-filen med tre forskellige værktøjer. Vi vil bruge WP-CLI, Poedit og den ældre makepot/grunt-tilgang, med rigtige kommandoer du kan kopiere. Til sidst vil du have en ren skabelon klar til at give til enhver oversætter.

Trin Én: Markér dine strenge som oversættelige

Før du kan oprette en POT-fil, skal hver streng, en bruger potentielt vil se, være omkranset af en Gettext-funktion. En scanner kan kun udtrække strenge, den genkender, og den genkender dem ved disse funktionskald – almindelige strengliteraler er usynlige for den.

WordPress giver en familie af lokaliseringsfunktioner, hver til en lidt forskellig kontekst:

// 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 andet argument i hvert kald – 'my-plugin' – er tekstdomænet. Det grupperer alle et plugins eller temas strenge under ét navneområde, så WordPress ved, hvilken .mo-fil der skal indlæses for dem. Hver oversættelig streng i dit projekt skal dele præcis det samme tekstdomæne, ellers vil nogle strenge aldrig blive oversat.

Brug _x(), når et ord er tvetydigt. Det engelske "Post" kan være et substantiv eller et verbum, og mange sprog oversætter dem forskelligt. Kontekststrenge lader oversættere skelne dem. Og brug esc_html__() og esc_attr__()-varianterne, når den oversatte streng udskrives i HTML, så du forbliver sikker og lokaliseret på samme tid.

Der er et par vaner, der holder dine strenge udtrækkelige. Send altid en almindelig strengliteral som det første argument – never a variable or a concatenation like __( 'Hello ' . $name, 'my-plugin' ), because the scanner reads source text statically and cannot resolve runtime values. For sætninger med et tal, brug _n(), så flertalsformer fanges korrekt, og for sætninger med en dynamisk værdi, brug sprintf() omkring en pladsholder som %s i stedet for at lime strenge sammen. Konsistens her er, hvad der får det næste trin – at generere skabelonen – til at producere et komplet, brugbart resultat.

Trin To: Erklær tekstdomænet i din header

WordPress har brug for to header-felter for at vide, hvor dine oversættelser bor: Tekstdomænet og Domænesti. Indstil dem i dit plugins hovedfil eller dit temas style.css, og WordPress vil automatisk indlæse den rigtige .mo-fil under kørsel.

<?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
 */

Tekstdomænet skal matche strengen, du sendte til hvert __() og _e() kald – my-plugin her. Domænesti fortæller WordPress, hvilken undermappe der indeholder oversættelsesfilerne, relativt til pluginets eller temaets rod. Konventionen er /languages, og det er præcis der, din genererede .pot-fil skal ligge.

Med strenge omkranset og headeren erklæret, er din kode klar til at scanne. Det bredere billede af at forberede et projekt til oversættelse – herunder temaer, der ikke er dine egne – er dækket i hvordan man lokaliserer et WordPress-tema, selvom man ikke er udvikler.

Hvordan genererer du .pot-filen? Tre metoder

Du genererer en .pot-fil ved at køre en scanner over din kildekode, der finder hvert Gettext-kald og skriver strengene ind i en skabelon. Her er tre pålidelige måder at gøre det på, fra den moderne standard til den ældre tilgang.

Metode 1: WP-CLI (Anbefalet)

Den officielle, moderne måde at oprette en POT-fil på er WP-CLI med i18n-kommandoen. Den leveres som en del af WordPress' kernewærktøjer, forstår PHP- og JavaScript-strenge og producerer en standardkompatibel skabelon på én linje.

# 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ørste argument er kildemappen (. for den aktuelle mappe), og det andet er outputstien. WP-CLI gennemgår dine filer, udtrækker hver omviklet streng, registrerer kilde fil og linjenummer som en kommentar og skriver .pot-filen. Det er hurtigt, scriptbart og det rigtige valg for ethvert seriøst projekt.

Den genererede skabelon inkluderer nyttig metadata, du kan justere med ekstra flag. Send --headers for at indstille projektnavn, version og oversætternes kontaktadresse, så .pot-headerblokken udfyldes korrekt i stedet for at være pladsholdere. WP-CLI udtrækker også JavaScript-strenge fra wp_set_script_translations()-kald automatisk, hvilket er vigtigt for moderne bloktemaer og Gutenberg-plugins, hvor halvdelen af den brugerrettede tekst ligger i JavaScript snarere end PHP. Én kommando dækker begge verdener.

Metode 2: Poedit (Grafisk)

Hvis du foretrækker en desktop-app, kan Poedit scanne din kildekode og generere skabelonen via sin grænseflade. Åbn Poedit, vælg at oprette en ny oversættelse fra POT eller scan kilder direkte, peg den mod din projektmappe, og konfigurer kildeordene (__, _e, _x, esc_html__) under katalogegenskaberne.

Poedit's funktioner til kildescanning og .pot-generering findes i dens Pro-udgave, men arbejdsgangen er venlig for udviklere, der hellere vil klikke end at skrive kommandoer. Det er også en solid editor til den oversættelsesfase, der følger. Poedit og flere andre desktop-muligheder sammenlignes i top 5 gratis værktøjer til at redigere og oversætte PO-filer på Mac og Windows.

Metode 3: makepot / grunt (Ældre)

Før WP-CLI var standardværktøjet makepot.php-scriptet fra WordPress i18n-tools-lageret, ofte forbundet til en Grunt-buildopgave med grunt-wp-i18n. Du vil stadig støde på det i ældre plugins og temaer.

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

Det virker, men det er ikke vedligeholdt i forhold til WP-CLI og er langsommere at sætte op. Brug det kun, når du vedligeholder et ældre projekt, der allerede afhænger af det; for alt nyt, foretræk wp i18n make-pot.

Hold skabelonen opdateret, når din kode ændres

En .pot-fil er et øjebliksbillede af dine strenge. Hver gang du tilføjer en funktion, ændrer en etiket eller retter en tastefejl i en synlig streng, bliver skabelonen forældet, og oversættere går glip af den nye ordlyd.

Gør regenerering til en del af din udgivelsesrutine. Kør wp i18n make-pot igen før hver versionopdatering, og flet derefter den opdaterede skabelon ind i eksisterende oversættelser med wp i18n update-po eller msgmerge, så oversættere beholder deres færdige arbejde og kun ser de nye huller. Behandl .pot-filen som en bygge-artefakt, du regenererer, not a file you hand-edit.

En forældet skabelon forårsager en subtil, frustrerende fejl: nye strenge vises på engelsk, selv på et "fuldt oversat" websted, fordi de aldrig var i den .pot-fil, oversætteren arbejdede ud fra. At fange dette er så simpelt som at scripte regenereringen ind i dit build, så skabelonen aldrig kan sakke bagud i forhold til din kode. Nogle teams tilføjer et CI-check, der får buildet til at fejle, hvis regenerering af .pot-filen producerer en diff, hvilket garanterer, at den committende skabelon altid matcher den aktuelle kildekode.

Når oversættere returnerer færdige .po-filer, skal disse stadig kompileres til den binære .mo-fil, som WordPress faktisk indlæser – og hvis du hellere vil springe hele download-oversæt-genkompilerings-løkken over, kan et cloud-værktøj håndtere det ende til ende. SimplePoTranslate accepterer din .pot-fil direkte, oversætter den med Context-Aware AI, der forstår, hvad hver streng betyder i din grænseflade, og returnerer en enkelt ZIP med .po, .mo og mere allerede bygget og navngivet. Dens Syntax Locking fryser pladsholdere som %s og %1$s, så dine variabler never break in translation.

Afrunding

For at oprette en POT-fil på den rigtige måde skal du først gøre din kode opdagelig – omkranse hver synlig streng i __(), _e(), _x() eller en escaping-variant, som alle deler ét tekstdomæne, og erklære det domæne plus Domain Path i din header. Generer derefter skabelonen med WP-CLI til nye projekter, Poedit, hvis du foretræker en GUI, eller makepot kun, når du vedligeholder ældre kode.

Generer tidligt, regenerer ofte, og lad aldrig din skabelon sakke bagud i forhold til din kode. En aktuel .pot-fil er forskellen mellem et plugin, der er ægte klar til verden, og et, der kun hævder at være det.

Klar til at omdanne din .pot-skabelon til færdige oversættelser uden den manuelle kompileringsdans? Prøv SimplePoTranslate gratis – intet kreditkort påkrævet. Upload din skabelon på den gratis plan og download klar-til-afsendelse oversættelsesfiler på få minutter.