Dlaczego Twoje tłumaczenia nie pojawiają się w WordPress (Przewodnik rozwiązywania problemów)

W rozwoju WordPressa nie ma nic bardziej frustrującego niż „Cicha Awaria”.

Zrobiłeś wszystko dobrze. Przetłumaczyłeś plik .po. Skompilowałeś go do pliku .mo. Przesłałeś go na swój serwer przez FTP. Wyczyściłeś pamięć podręczną.

Odświeżasz stronę, spodziewając się zobaczyć hiszpański, francuski lub niemiecki. Zamiast tego widzisz... angielski.

Brak komunikatu o błędzie, brak białego ekranu — tylko uparty, nieprzetłumaczony tekst. Zanim wyrwiesz sobie włosy z głowy, przeczytaj ten przewodnik. Oto 5 najczęstszych powodów, dla których tłumaczenia nie ładują się w WordPress, i jak je naprawić.

1. Źle nazywasz plik

WordPress jest niezwykle surowy, jeśli chodzi o nazewnictwo plików. Jeśli pominiesz znak, nie załaduje pliku.

Standardowy format to: {domena-tekstowa}-{locale}.mo

• Domena Tekstowa (Text Domain): Jest to unikalny identyfikator motywu lub wtyczki (np. woocommerce, twentytwentyfour, my-custom-plugin).
• Ustawienia Lokalne (Locale): Kod ustawień lokalnych WP (np. es_ES dla hiszpańskiego z Hiszpanii, fr_FR dla francuskiego).

Częste błędy:

• Nazywanie pliku tylko es_ES.mo (To działa tylko dla globalnych plików rdzenia WordPress, a nie dla wtyczek).
• Używanie złego myślnika: my_plugin_es_ES.mo (Podkreślenie) zamiast my-plugin-es_ES.mo (Łącznik).
• Zgadywanie domeny tekstowej. Musisz sprawdzić kod wtyczki (nagłówek style.css lub funkcję load_plugin_textdomain), aby znaleźć dokładny slug.

2. Umieściłeś plik w niewłaściwym folderze

To, gdzie przesyłasz plik, ma takie samo znaczenie, jak to, jak go nazywasz. WordPress szuka w określonych katalogach w określonej kolejności.

• „Bezpieczny” folder systemowy: /wp-content/languages/plugins/ lub /wp-content/languages/themes/.
  • Zalety: Jest bezpieczny przed aktualizacjami wtyczek.
  • Wady: Musisz nazwać plik textdomain-locale.mo.
• Folder autora: /wp-content/plugins/plugin-name/languages/.
  • Zalety: Łatwy do znalezienia.
  • Wady: NIEBEZPIECZEŃSTWO. Kiedy aktualizujesz wtyczkę, ten folder jest czyszczony do czysta. Twoje tłumaczenia znikną.

Najlepsza praktyka: Zawsze umieszczaj swoje niestandardowe pliki .mo w globalnym katalogu /wp-content/languages/, aby zapobiec utracie danych podczas aktualizacji.

3. „Cichy zabójca”: Uszkodzona składnia w pliku .po

Jest to najtrudniejszy problem do debugowania i zdarza się często w przypadku ogólnych narzędzi tłumaczeniowych AI.

WordPress czyta pliki binarne .mo, które są kompilowane z plików tekstowych .po. Jeśli Twój plik .po zawiera błędy składniowe, plik .mo może zostać wygenerowany, ale będzie wewnętrznie „zepsuty”.

Jak to się dzieje? Jeśli tłumacz (człowiek lub AI) zepsuje formatowanie Gettext, ciąg stanie się nieprawidłowy.

• Przykład: Brakujący cudzysłów zamykający ".
• Przykład: Zepsucie zmiennej (zmiana %s na % s).
• Przykład: Zepsucie licznika msgid_plural.

Kiedy WordPress napotyka zepsuty wpis w pliku .mo, często go pomija lub całkowicie przestaje czytać plik, wracając do oryginalnego angielskiego.

4. Zapomniałeś skompilować (.po vs .mo)

WordPress nie może czytać plików .po bezpośrednio. To powszechne błędne przekonanie.

• .po = Czytelne dla ludzi (Portable Object).
• .mo = Czytelne dla maszyn (Machine Object).

Jeśli prześlesz plik my-theme-es_ES.po, ale zapomnisz wygenerować pasujący plik .mo, nic się nie stanie. Musisz go skompilować.

5. Buforowanie (Zwykły podejrzany)

Jeśli używasz wtyczek buforujących (WP Rocket, LiteSpeed) lub buforowania po stronie serwera (Varnish, Redis), Twoja witryna może serwować buforowaną wersję HTML z przed przesłaniem tłumaczenia.

Naprawa: wyczyść wszystkie pamięci podręczne, w tym pamięć podręczną przeglądarki i pamięć podręczną obiektów.

Ostateczna naprawa: Prawidłowe pliki od samego początku

Rozwiązywanie problemów ze ścieżkami i nazwami plików jest łatwe. Rozwiązywanie problemów z uszkodzoną składnią (Powód #3) to koszmar.

Jeśli używasz narzędzia, które psuje zmienne kodu lub uszkadza strukturę Gettext, spędzisz godziny zastanawiając się, dlaczego plik nie działa, nie zdając sobie sprawy, że sam plik jest „zatruty”.

Dlatego zbudowaliśmy SimplePoTranslate.

• Blokada składni: Upewniamy się, że każdy pojedynczy ciąg jest poprawny składniowo, zanim go pobierzesz. Blokujemy zmienne takie jak %s, aby nie można ich było zepsuć.
• Idealne formatowanie: Generujemy czyste, standardowe pliki .po, które w 100% kompilują się do działających plików .mo.
• Brak wymaganych wtyczek: Pobierasz plik i wiesz, że działa. Musisz go tylko przesłać do odpowiedniego folderu.

Przestań zgadywać, dlaczego Twoje tłumaczenia są niewidoczne. Zacznij od pliku, któremu możesz zaufać.

Gotowy na tłumaczenie bez bólu głowy? Zacznij za darmo na SimplePoTranslate.com