Jak przetłumaczyć wtyczkę WordPress (krok po kroku)

Znalazłeś idealną wtyczkę WordPress do swojego projektu. Robi dokładnie to, czego potrzebujesz, recenzje są świetne, a potem ją aktywujesz i zdajesz sobie sprawę, że każdy przycisk, etykieta i komunikat o błędzie są po angielsku. Twoi niemieccy, francuscy lub japońscy goście zaraz natrafią na ścianę tekstu, którego nie potrafią przeczytać.

Dobrą wiadomością jest to, że większość dobrze zbudowanych wtyczek jest gotowa do tłumaczenia (translation-ready), co oznacza, że deweloper umieścił swoje ciągi znaków w funkcjach Gettext specjalnie po to, aby osoby takie jak Ty mogły je tłumaczyć. Wyzwaniem jest wiedza, gdzie znajdują się pliki, jak nazwać tłumaczenie i gdzie je umieścić, aby kolejna aktualizacja wtyczki nie zniweczyła Twojej pracy.

Ten przewodnik pokaże Ci, jak przetłumaczyć wtyczkę WordPress od początku do końca: znajdziesz domenę tekstową i folder języków, uzyskasz lub wygenerujesz szablon .pot, zbudujesz prawidłowo nazwane pliki .po i .mo oraz umieścisz je tam, gdzie WordPress będzie je niezawodnie ładował. Omówimy również jeden rodzaj wtyczki, której to podejście nie jest w stanie w pełni przetłumaczyć, abyś nie tracił godzin na walkę z niemożliwym przypadkiem.

Jak znaleźć pliki tłumaczeń wtyczki?

Zanim cokolwiek przetłumaczysz, potrzebujesz dwóch informacji z wtyczki: jej domeny tekstowej i jej folderu języków. Domena tekstowa to unikalny ciąg znaków, którego wtyczka używa do identyfikacji własnych tłumaczeń, a folder języków to miejsce, w którym znajduje się szablon źródłowy.

Lokalizowanie folderu języków i domeny tekstowej

Otwórz katalog wtyczki w wp-content/plugins/your-plugin/ i poszukaj podfolderu /languages. Wewnątrz zazwyczaj znajdziesz plik .pot, pusty szablon zawierający każdy ciąg znaków do przetłumaczenia.

Aby potwierdzić domenę tekstową, otwórz główny plik PHP wtyczki i spójrz na jego blok nagłówka:

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Tutaj domeną tekstową jest awesome-plugin. Ta wartość jest krytyczna, ponieważ Twoje pliki tłumaczeń muszą ją zawierać w swoich nazwach, w przeciwnym razie WordPress nigdy nie dopasuje ich do wtyczki. Zobaczysz ją również w każdym wywołaniu ciągu znaków w całym kodzie:

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Ten drugi argument, awesome-plugin, to ponownie domena tekstowa. Każdy ciąg znaków, który go używa, może być przetłumaczony przez Twój katalog. Jeśli ciąg znaków w interfejsie wtyczki nie posiada tej „otoczki”, na przykład deweloper zakodował na stałe echo 'Save' bez __(), to ten ciąg znaków w ogóle nie jest możliwy do przetłumaczenia, a żaden plik .po nie może go dosięgnąć. Większość renomowanych wtyczek prawidłowo otacza wszystko, ale jeśli zauważysz jeden lub dwa uparte ciągi znaków, które odmawiają tłumaczenia, prawdopodobnym winowajcą jest brak „otoczki” Gettext w kodzie źródłowym.

Szybkim sposobem na ocenę, czy wtyczka jest naprawdę gotowa do tłumaczenia, jest sprawdzenie jej na liście katalogu WordPress.org, która pokazuje procent tłumaczenia i linki do szablonu /languages. Wtyczka z aktywnym projektem tłumaczeniowym ma znacznie większe szanse na posiadanie czystych, w pełni opakowanych ciągów znaków niż ta porzucona.

Co jeśli wtyczka nie ma pliku POT?

Niektóre wtyczki są dostarczane bez szablonu .pot. Jeśli folder /languages jest pusty lub go brakuje, musisz samodzielnie wygenerować szablon, skanując kod źródłowy w poszukiwaniu ciągów znaków do przetłumaczenia.

Standardowym narzędziem do tego jest WP-CLI, który wyodrębnia każde wywołanie Gettext do nowego pliku .pot.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

To polecenie przechodzi przez pliki PHP i JavaScript wtyczki, znajduje każde wywołanie __(), _e(), _n() i podobne, a następnie zapisuje kompletny szablon. Jeśli wolisz ścieżkę graficzną, Poedit Pro może skanować kod źródłowy w ten sam sposób. W każdym razie, wynikiem jest plik .pot zawierający wszystkie ciągi źródłowe z pustymi tłumaczeniami, gotowy do przekształcenia w prawdziwy plik językowy.

Generowanie własnego szablonu ma ukrytą zaletę: przechwytuje ciągi znaków, o których pierwotny deweloper mógł zapomnieć w dostarczonym pliku .pot. Wtyczki szybko ewoluują, a szablon, który został dostarczony z wersją 2.1, może nie zawierać ciągów znaków dodanych w wersji 2.4. Regeneracja z aktualnego źródła gwarantuje, że Twój katalog odzwierciedla to, co wtyczka faktycznie wyświetla dzisiaj, a nie to, co wyświetlała dwie wersje temu. Jeśli utrzymujesz tłumaczenia dla wtyczki przez pewien czas, ponowne uruchomienie make-pot po każdej większej aktualizacji jest niezawodnym nawykiem.

Tworzenie plików PO i MO z poprawną nazwą

Najczęstszym błędem podczas tłumaczenia wtyczki jest nazwa pliku. WordPress znajduje tłumaczenia wtyczek, dopasowując bardzo specyficzny wzorzec, a jeden błędny znak oznacza, że Twoje tłumaczenie zostanie całkowicie zignorowane.

Formuła nazewnictwa plików

W przypadku tłumaczeń wtyczek wzorzec to text-domain-locale. Zatem dla domeny tekstowej awesome-plugin przetłumaczonej na język niemiecki, pliki muszą być nazwane:

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

Kod języka lokalnego to kod języka witryny WordPress: de_DE dla niemieckiego, fr_FR dla francuskiego, es_ES dla hiszpańskiego, pt_BR dla brazylijskiego portugalskiego. Jeśli kod języka lokalnego będzie błędny, WordPress cicho pominie Twój plik. Tworzysz je z szablonu .pot w edytorze takim jak Poedit, który automatycznie kompiluje binarny .mo po zapisaniu. Jeśli jesteś nowy w tym edytorze, kompletny przewodnik po Poedit przeprowadzi Cię przez proces tworzenia tłumaczenia z szablonu krok po kroku.

Gdzie umieścić pliki, aby aktualizacje ich nie usunęły

Dostępne są dwie możliwe lokalizacje, a wybór właściwej ma znaczenie.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Zawsze używaj wp-content/languages/plugins/. WordPress sprawdza najpierw ten katalog nadrzędny, a ponieważ znajduje się on poza folderem wtyczki, aktualizacja wtyczki nigdy nie dotknie Twoich tłumaczeń. Pliki umieszczone w folderze samej wtyczki zostaną nadpisane w momencie instalacji nowej wersji.

To zachowanie nadpisywania jest jedną z najbardziej użytecznych i najmniej znanych funkcji lokalizacji WordPress. Oznacza to, że możesz dostarczać niestandardowe lub poprawione tłumaczenia dla dowolnej wtyczki zewnętrznej bez jej forkowania, a Twoje zmiany są całkowicie bezpieczne w przypadku aktualizacji. Jeśli zarządzasz kilkoma witrynami klientów, na których działa ta sama wtyczka, możesz nawet przechowywać jeden zestaw nadpisujących plików .mo i wdrażać je na wszystkich, wiedząc, że każda witryna automatycznie je pobierze, o ile kod języka lokalnego będzie się zgadzał.

Jak WordPress ładuje Twoje tłumaczenie

Wtyczka gotowa do tłumaczenia informuje WordPressa, aby załadował swój katalog, wywołując load_plugin_textdomain() podczas inicjalizacji:

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

W przypadku większości nowoczesnych wtyczek na WordPressie w wersji 4.6 i nowszych, nie musisz tego dotykać. WordPress automatycznie ładuje tłumaczenia z wp-content/languages/plugins/, o ile nazwa pliku i język witryny są zgodne. Jeśli Twoje ukończone tłumaczenie nadal się nie pojawia, przyczyną jest prawie zawsze niezgodność nazwy pliku, nieaktualny plik .mo lub język witryny ustawiony na niewłaściwy język lokalny. Nasz przewodnik rozwiązywania problemów, gdy tłumaczenia nie wyświetlają się w WordPressie omawia każdy z tych punktów awarii.

Wtyczki, które przechowują ciągi znaków w bazie danych

Oto ważne ograniczenie. Podejście Gettext tłumaczy tylko ciągi znaków, które znajdują się w kodzie wtyczki. Niektóre wtyczki, zwłaszcza te do tworzenia formularzy, konstruktorzy stron i rozszerzenia e-commerce, umożliwiają tworzenie treści (etykiet formularzy, atrybutów produktów, niestandardowych wiadomości), które są zapisywane w bazie danych WordPress. Te ciągi znaków to dane generowane przez użytkownika, nie są częścią pliku .pot, więc plik .po nie może ich dosięgnąć. W przypadku treści z bazy danych potrzebujesz wtyczki wielojęzycznej, takiej jak WPML lub Polylang, lub własnej funkcji tłumaczenia ciągów znaków wtyczki. Zawsze sprawdzaj, czy dany ciąg znaków znajduje się w kodzie, czy w bazie danych, zanim założysz, że plik .po może to naprawić.

Prosty test powie Ci, z jakim rodzajem ciągu znaków masz do czynienia. Jeśli tekst jest czymś, co wpisałeś w polu ustawień, etykietą formularza, którą utworzyłeś, niestandardową wiadomością z podziękowaniem, nazwą produktu, jest to treść z bazy danych i plik .po nie może jej dotknąć. Jeśli tekst jest częścią wbudowanego interfejsu wtyczki, etykietami przycisków, błędami walidacji, powiadomieniami administratora dostarczanymi z samą wtyczką, znajduje się on w kodzie, a plik .po jest dokładnie właściwym narzędziem. Wczesne wyznaczenie tej granicy oszczędza godziny frustracji, ponieważ żadna ilość perfekcyjnej edycji .po nigdy nie przetłumaczy ciągu znaków, który wtyczka pobiera z bazy danych w czasie rzeczywistym.

Tłumaczenie na dużą skalę bez ręcznej pracy

Ręczne tłumaczenie jednej wtyczki na jeden język jest wykonalne. Tłumaczenie jej na dziesięć języków lub tłumaczenie całego stosu wtyczek dla witryny klienta zamienia się w dni powtarzalnej pracy, a każda ręczna edycja grozi pomyleniem symbolu zastępczego, takiego jak %s lub %1$s, i uszkodzeniem danych wyjściowych.

Właśnie tutaj przepływ pracy w chmurze zmienia rachunek. Prześlij plik .po lub .pot wtyczki do SimplePoTranslate, wybierz języki docelowe, a sztuczna inteligencja świadoma kontekstu przetłumaczy cały katalog, podczas gdy Syntax Locking zamrozi każdy symbol zastępczy, tag HTML i token kodu, aby nic nie mogło się zepsuć. Smart Batching obsługuje duże katalogi w jednym przebiegu, a Ty pobierasz plik ZIP zawierający pliki .po, .mo, .json, .php i .xliff razem, prawidłowo sformatowane i gotowe do umieszczenia w wp-content/languages/plugins/. Działa w całości w chmurze, więc nie ma instalacji na komputerze stacjonarnym i nie ma „nadmuchania” Twojej witryny.

Należy pamiętać, że tłumaczenie wtyczki różni się od tłumaczenia motywu, które wykorzystuje nieco inną konwencję folderów i funkcję ładowania. Jeśli motyw jest Twoim celem, skorzystaj z naszego dedykowanego przewodnika na temat lokalizowania dowolnego motywu WordPress, nawet jeśli nie jesteś deweloperem.

Użyj ścieżki ręcznej, gdy masz jedną wtyczkę i jeden język. Użyj chmury, gdy potrzebujesz wielu języków, szybko, bez rezygnacji z bezpieczeństwa symboli zastępczych.

Gotowy, aby przetłumaczyć swoją wtyczkę WordPress na każdy język, którym posługuje się Twoja publiczność, nie naruszając ani jednej zmiennej? Wypróbuj SimplePoTranslate za darmo — karta kredytowa nie jest wymagana. Darmowy plan pozwala przetłumaczyć Twój pierwszy plik .po wtyczki w kilka minut, z włączoną funkcją Syntax Locking dla każdego ciągu znaków.