Jak stworzyć plik .pot dla motywu lub wtyczki
Właśnie skończyłeś wtyczkę WordPress, którą chcesz udostępnić światu. Kod działa, funkcje są solidne, a ktoś z Niemiec pisze e-maila z pytaniem, jak przetłumaczyć ją na niemiecki. Wskazujesz im folder languages i zdajesz sobie sprawę, że nic tam nie ma. Żadnego szablonu, żadnych ciągów znaków, żadnego sposobu, aby tłumacz mógł w ogóle wiedzieć, co wymaga tłumaczenia. Twoja wtyczka jest technicznie „gotowa do tłumaczenia” tylko z nazwy.
Każdy projekt WordPress, który nadaje się do tłumaczenia, zaczyna się od jednego pliku: szablonu .pot. Zanim ktokolwiek będzie mógł stworzyć wersję niemiecką, francuską czy japońską, musisz stworzyć plik POT, który zawiera listę wszystkich ciągów znaków widocznych dla użytkownika w Twoim kodzie. Pomiń ten krok, a tłumacze będą musieli czytać Twój kod źródłowy linia po linii, zgadując, które ciągi znaków w ogóle mają być widoczne.
Ten przewodnik przedstawia dwie części zadania: przygotowanie kodu źródłowego tak, aby ciągi znaków były wykrywalne, a następnie wygenerowanie samego .pot za pomocą trzech różnych narzędzi. Użyjemy WP-CLI, Poedit oraz starszego podejścia makepot/grunt, wraz z rzeczywistymi poleceniami, które możesz skopiować. Na koniec będziesz mieć czysty szablon gotowy do przekazania każdemu tłumaczowi.
Krok pierwszy: Oznacz ciągi znaków jako możliwe do przetłumaczenia
Zanim będziesz mógł stworzyć plik POT, każdy ciąg znaków, który użytkownik może zobaczyć, musi być opakowany w funkcję Gettext. Skaner może wyodrębnić tylko te ciągi, które rozpoznaje, a rozpoznaje je po wywołaniach tych funkcji — zwykłe literały ciągów znaków są dla niego niewidoczne.
WordPress udostępnia rodzinę funkcji lokalizacyjnych, każdą dla nieco innego kontekstu:
// 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' );
Drugi argument w każdym wywołaniu — 'my-plugin' — to domena tekstowa. Grupuje ona wszystkie ciągi znaków wtyczki lub motywu pod jedną przestrzenią nazw, dzięki czemu WordPress wie, który plik .mo ma dla nich załadować. Każdy ciąg znaków możliwy do przetłumaczenia w Twoim projekcie musi mieć dokładnie tę samą domenę tekstową, w przeciwnym razie niektóre ciągi nigdy nie zostaną przetłumaczone.
Używaj _x() zawsze, gdy słowo jest niejednoznaczne. Angielskie „Post” może być rzeczownikiem lub czasownikiem, a wiele języków tłumaczy je inaczej. Ciągi kontekstowe pozwalają tłumaczom je rozróżnić. Sięgnij po warianty esc_html__() i esc_attr__() zawsze, gdy przetłumaczony ciąg jest drukowany do HTML, abyś był bezpieczny i zlokalizowany jednocześnie.
Istnieje kilka nawyków, które sprawiają, że Twoje ciągi znaków są możliwe do wyodrębnienia. Zawsze przekazuj prosty literał ciągu znaków jako pierwszy argument — nigdy zmienną ani konkatenację, taką jak __( 'Hello ' . $name, 'my-plugin' ), ponieważ skaner czyta tekst źródłowy statycznie i nie może rozwiązywać wartości w czasie wykonania. Dla zdań z liczbą użyj _n(), aby formy liczby mnogiej były poprawnie przechwytywane, a dla zdań z wartością dynamiczną użyj sprintf() wokół symbolu zastępczego, takiego jak %s, zamiast łączenia ciągów znaków. Spójność w tym miejscu sprawia, że następny krok — generowanie szablonu — daje kompletny, użyteczny wynik.
Krok drugi: Zadeklaruj domenę tekstową w nagłówku
WordPress potrzebuje dwóch pól nagłówka, aby wiedzieć, gdzie znajdują się Twoje tłumaczenia: Domena tekstowa (Text Domain) i Ścieżka domeny (Domain Path). Ustaw je w głównym pliku wtyczki lub w style.css Twojego motywu, a WordPress automatycznie załaduje właściwy plik .mo w czasie wykonania.
<?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
*/
Domena tekstowa musi odpowiadać ciągowi znaków, który przekazałeś do każdego wywołania __() i _e() — tutaj my-plugin. Ścieżka domeny informuje WordPress, który podfolder zawiera pliki tłumaczeń, względem katalogu głównego wtyczki lub motywu. Konwencją jest /languages, i to właśnie tam powinien znajdować się wygenerowany plik .pot.
Gdy ciągi znaków są opakowane, a nagłówek zadeklarowany, Twój kod jest gotowy do skanowania. Szerszy obraz przygotowania projektu do tłumaczenia — w tym motywów, które nie są Twoje — jest opisany w jak zlokalizować dowolny motyw WordPress, nawet jeśli nie jesteś programistą.
Jak wygenerować plik .pot? Trzy metody
Generujesz plik .pot, uruchamiając skaner w kodzie źródłowym, który znajduje każde wywołanie Gettext i zapisuje ciągi znaków do szablonu. Oto trzy niezawodne sposoby, aby to zrobić, od nowoczesnego domyślnego do starszego podejścia.
Metoda 1: WP-CLI (zalecana)
Oficjalnym, nowoczesnym sposobem tworzenia pliku POT jest WP-CLI za pomocą polecenia i18n. Jest on dostarczany jako część podstawowych narzędzi WordPress, rozumie ciągi znaków PHP i JavaScript, i tworzy zgodny ze standardami szablon w jednej linii.
# 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
Pierwszym argumentem jest katalog źródłowy (. dla bieżącego folderu), a drugim ścieżka wyjściowa. WP-CLI przechodzi przez Twoje pliki, wyodrębnia każdy opakowany ciąg znaków, zapisuje plik źródłowy i numer linii jako komentarz, i zapisuje plik .pot. Jest szybki, skryptowalny i właściwym wyborem dla każdego poważnego projektu.
Wygenerowany szablon zawiera pomocne metadane, które można dostosować za pomocą dodatkowych flag. Przekaż --headers, aby ustawić nazwę projektu, wersję i adres kontaktowy tłumaczy, dzięki czemu blok nagłówka .pot zostanie poprawnie wypełniony, a nie pozostawiony jako symbole zastępcze. WP-CLI automatycznie wyodrębnia również ciągi znaków JavaScript z wywołań wp_set_script_translations(), co ma znaczenie dla nowoczesnych motywów blokowych i wtyczek Gutenberg, gdzie połowa tekstu widocznego dla użytkownika znajduje się w JavaScript, a nie w PHP. Jedno polecenie obejmuje oba światy.
Metoda 2: Poedit (graficzna)
Jeśli wolisz aplikację desktopową, Poedit może skanować Twój kod źródłowy i generować szablon za pośrednictwem swojego interfejsu. Otwórz Poedit, wybierz tworzenie nowego tłumaczenia z POT lub bezpośrednie skanowanie źródeł, wskaż folder projektu i skonfiguruj słowa kluczowe źródła (__, _e, _x, esc_html__) w właściwościach katalogu.
Funkcje skanowania kodu źródłowego i generowania .pot w Poedit są dostępne w edycji Pro, ale przepływ pracy jest przyjazny dla programistów, którzy wolą klikać niż wpisywać polecenia. Jest to również solidny edytor do następującej fazy tłumaczenia. Poedit i kilka innych opcji desktopowych są porównywane w top 5 darmowych narzędzi do edycji i tłumaczenia plików PO na Mac i Windows.
Metoda 3: makepot / grunt (starsza)
Przed WP-CLI standardowym narzędziem był skrypt makepot.php z repozytorium WordPress i18n-tools, często podłączony do zadania kompilacji Grunt za pomocą grunt-wp-i18n. Nadal spotkasz go w starszych wtyczkach i motywach.
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
Działa, ale jest nieutrzymywany w porównaniu do WP-CLI i wolniejszy w konfiguracji. Używaj go tylko wtedy, gdy utrzymujesz starszy projekt, który już od niego zależy; dla czegoś nowego preferuj wp i18n make-pot.
Utrzymuj szablon aktualny wraz ze zmianami w kodzie
Plik .pot to migawka Twoich ciągów znaków w danym momencie. Za każdym razem, gdy dodasz funkcję, zmienisz etykietę lub poprawisz literówkę w widocznym ciągu znaków, szablon staje się nieaktualny, a tłumacze pomijają nowe sformułowanie.
Włącz regenerację do swojej rutyny wydawniczej. Ponownie uruchom wp i18n make-pot przed każdym zwiększeniem wersji, a następnie połącz odświeżony szablon z istniejącymi tłumaczeniami za pomocą wp i18n update-po lub msgmerge, aby tłumacze zachowali swoją ukończoną pracę i widzieli tylko nowe luki. Traktuj .pot jako artefakt kompilacji, który regenerujesz, a nie plik, który edytujesz ręcznie.
Nieaktualny szablon powoduje subtelną, frustrującą awarię: nowe ciągi znaków pojawiają się w języku angielskim nawet na „w pełni przetłumaczonej” stronie, ponieważ nigdy nie było ich w pliku .pot, z którego korzystał tłumacz. Wykrycie tego jest tak proste, jak zaprogramowanie regeneracji w procesie kompilacji, dzięki czemu szablon nigdy nie może odbiegać od kodu. Niektóre zespoły dodają kontrolę CI, która powoduje błąd kompilacji, jeśli regeneracja .pot generuje różnicę, gwarantując, że zatwierdzony szablon zawsze odpowiada bieżącemu kodowi źródłowemu.
Gdy tłumacze zwrócą ukończone pliki .po, nadal trzeba je skompilować do binarnego pliku .mo, który WordPress faktycznie ładuje — a jeśli wolisz pominąć całą pętlę pobierania, tłumaczenia i rekompilacji, narzędzie chmurowe może obsłużyć to kompleksowo. SimplePoTranslate akceptuje Twój plik .pot bezpośrednio, tłumaczy go za pomocą sztucznej inteligencji świadomej kontekstu (Context-Aware AI), która rozumie, co oznacza każdy ciąg znaków w Twoim interfejsie, i zwraca pojedynczy plik ZIP z już zbudowanymi i nazwanymi plikami .po, .mo i innymi. Jego blokada składni (Syntax Locking) zamraża symbole zastępcze, takie jak %s i %1$s, dzięki czemu Twoje zmienne nigdy nie zostaną uszkodzone podczas tłumaczenia.
Podsumowanie
Aby stworzyć plik POT we właściwy sposób, najpierw spraw, aby Twój kod był wykrywalny — opakuj każdy widoczny ciąg znaków w __(), _e(), _x() lub wariant ucieczki, wszystkie dzielące jedną domenę tekstową, i zadeklaruj tę domenę wraz ze Ścieżką domeny w nagłówku. Następnie wygeneruj szablon za pomocą WP-CLI dla nowych projektów, Poedit, jeśli wolisz GUI, lub makepot tylko podczas utrzymywania starszego kodu.
Generuj wcześnie, regeneruj często i nigdy nie pozwól, aby Twój szablon pozostawał w tyle za kodem. Aktualny plik .pot to różnica między wtyczką, która jest naprawdę gotowa na świat, a taką, która tylko twierdzi, że jest.
Gotowy, aby przekształcić swój szablon
.potw gotowe tłumaczenia bez ręcznego procesu kompilacji? Wypróbuj SimplePoTranslate za darmo — karta kredytowa nie jest wymagana. Prześlij swój szablon na darmowym poziomie i pobierz gotowe do wysyłki pliki tłumaczeń w ciągu kilku minut.