Niedziałające tłumaczenie w WordPressie potrafi zatrzymać wdrożenie, mimo że plik PO zawiera poprawny przekład. Najczęściej problem leży w domenie tekstowej, locale, ścieżce pliku albo sposobie, w jaki motyw lub wtyczka ładuje tłumaczenia.
Krótka odpowiedź
WordPress localization to dostosowanie tekstów interfejsu komponentu do języka i ustawień regionalnych witryny. Sprawdź domenę tekstową i locale, przygotuj plik PO, wygeneruj MO i zapisz oba w ścieżce obsługiwanej przez komponent.
Dla własnych tłumaczeń Loco Translate oferuje katalog `wp-content/languages/loco`, ale pliki Custom wymagają aktywnej wtyczki Loco Translate i poprawnego mechanizmu ładowania przez motyw lub wtyczkę.
Usługi KC Mobile
Potrzebujesz pomocy w tym temacie?
Czytasz poradnik „WordPress localization: lokalizacja motywu i wtyczek krok po kroku”. Napisz, co chcesz zrobić i na jakim etapie jesteś. Ustalimy, czy możemy pomóc i jaki zakres prac będzie potrzebny.
Co oznacza localization w WordPressie?
Localization, czyli l10n, dostosowuje interfejs gotowego komponentu do języka i ustawień regionalnych. Internacjonalizacja, czyli i18n, oznacza przygotowanie kodu tak, aby jego teksty dało się wyodrębnić i przetłumaczyć. Plik językowy nie naprawi tekstu wpisanego na stałe w szablonie PHP, HTML lub JavaScript.
Lokalizacja motywu lub wtyczki obejmuje teksty interfejsu, takie jak etykiety, komunikaty walidacji i nazwy ustawień. Nie tłumaczy wpisów, produktów, adresów URL ani metadanych SEO. Do zarządzania treściami w kilku językach służą inne rozwiązania, opisane w poradniku o wielojęzycznym WordPressie i SEO.
Domena tekstowa identyfikuje komponent, a locale wskazuje język i wariant regionalny, dla przykładu `pl_PL`. Nazwy te muszą odpowiadać temu, czego oczekuje kod. Pliki PO i MO dostarczają tłumaczenia dla rozpoznanych ciągów, a w przypadku części skryptów JavaScript potrzebne są dodatkowo pliki JSON.
Czytasz poradnik „WordPress localization: lokalizacja motywu i wtyczek krok po kroku”. Napisz, co chcesz zrobić i na jakim etapie jesteś. Ustalimy, czy możemy pomóc i jaki zakres prac będzie potrzebny. Omów temat tego poradnika
Jak sprawdzić, czy motyw lub wtyczka obsługuje tłumaczenia?
Zacznij od domeny tekstowej, katalogu językowego i źródła komunikatu, którego nie da się przetłumaczyć. W panelu WordPressa sprawdź slug w `Wtyczki > Zainstalowane wtyczki` albo identyfikator aktywnego motywu w `Wygląd > Motywy`. Następnie poszukaj katalogu `languages` i plików `.pot`, `.po`, `.mo` lub `.json` w plikach komponentu albo jego repozytorium.
Wtyczka zwykle deklaruje domenę tekstową w nagłówku głównego pliku, a motyw w `style.css`. W kodzie szukaj wywołań gettext, między innymi `__()`, `_e()` i `_n()`, które otrzymują domenę tekstową. WordPress opisuje wymagania dla motywów w dokumentacji internacjonalizacji motywów i w przewodniku internacjonalizacji wtyczek.
| Kontrola | Gdzie szukać | Co mówi wynik |
|---|---|---|
| Domena tekstowa | Nagłówek wtyczki, `style.css`, wywołania gettext | Określa identyfikator tłumaczenia i część nazw plików |
| Szablon POT | Katalog `languages` lub repozytorium producenta | Zawiera ciągi źródłowe do przełożenia |
| Pliki PO i MO | Katalog komponentu albo `wp-content/languages` | Mogą zawierać tłumaczenia producenta lub własny override |
| Nieprzetłumaczony tekst | Strona, panel i kod PHP lub JavaScript | Może być brakującym wpisem albo tekstem zapisanym na stałe |
Jeśli tekstu nie widać w katalogu Loco Translate ani w plikach PO, sprawdź źródło komponentu. Ciąg może być zapisany bezpośrednio w szablonie lub generowany przez JavaScript. W tym drugim przypadku komponent powinien korzystać z mechanizmu tłumaczeń skryptów WordPressa i dopasowanego pliku JSON.
Jak przygotować pliki PO i MO oraz bezpiecznie przechowywać tłumaczenia?
Ustal domenę tekstową i locale witryny, zanim utworzysz plik tłumaczenia. Locale sprawdzisz w `Ustawienia > Ogólne > Język witryny`; dla polskiej instalacji typową wartością jest `pl_PL`, ale nazwę trzeba potwierdzić dla konkretnej witryny i komponentu.
POT to szablon zawierający ciągi źródłowe, PO przechowuje tekst oryginalny i przekład, a MO jest skompilowaną wersją używaną przez WordPressa. Edytuj PO, zachowuj placeholdery takie jak `%s` i `%1$d`, a po zapisie wygeneruj MO. Nie tłumacz zmiennych ani nie zmieniaj liczby symboli zastępczych, bo może to uszkodzić komunikat.
| Narzędzie lub ścieżka | Kiedy użyć | Ryzyko i warunek |
|---|---|---|
| Loco Translate | Szybka edycja w panelu, menu `Loco Translate > Wtyczki` albo `Motywy` | Lokalizacja Custom wymaga aktywnej wtyczki i działającego ładowania przez komponent |
| Poedit | Praca lokalna na POT lub PO i przekazanie plików przez SFTP | Trzeba wysłać pliki do właściwej lokalizacji i sprawdzić, czy powstał MO |
| Edytor tekstu | Kontrolowana korekta PO w repozytorium | Łatwo uszkodzić składnię, kodowanie lub zapis liczby mnogiej |
| `wp-content/languages/loco` | Własne pliki Custom Loco | Chroni pliki przed typowymi aktualizacjami, ale nie działa bez wtyczki Loco Translate i poprawnego mechanizmu ładowania |
| Katalog motywu lub wtyczki | Tłumaczenie dostarczane razem z komponentem | Aktualizacja komponentu może zastąpić pliki; stosuj jako jego autor lub świadomie zarządzając własnym kodem |
| `wp-content/languages/plugins` lub `themes` | Pliki systemowe zarządzane przez WordPressa | Aktualizacja pakietów językowych może zmienić lub nadpisać plik |
W Loco wybierz komponent, dodaj język i wskaż lokalizację `Custom`, jeśli tworzysz własny override. Po aktualizacji katalogu źródłowego użyj `Sync`, przejrzyj nowe, usunięte i oznaczone jako fuzzy wpisy, a dopiero potem zapisz tłumaczenie. Synchronizacja nie zwalnia z ponownej kontroli przekładów, których tekst źródłowy się zmienił.
Dokumentacja Loco wskazuje, że katalog Custom znajduje się w `wp-content/languages/loco`, a jego ładowanie zapewnia sama wtyczka. Komponent musi też rejestrować lokalizację i ładować tłumaczenia w prawidłowej kolejności. Jeżeli Loco Translate jest wyłączone albo motyw lub wtyczka wywołuje tłumaczenia zbyt wcześnie, plik może istnieć na serwerze i nie pojawić się na stronie. Szczegóły opisuje instrukcja ładowania plików Loco Translate.
Poedit sprawdza się, gdy pliki wersjonujesz lokalnie lub trzymasz w repozytorium. Po edycji zweryfikuj ostrzeżenia o placeholderach, zapisz PO i sprawdź, czy obok znajduje się MO. Nie modyfikuj bezpośrednio plików dostawcy, jeśli nie masz procedury odtworzenia zmian po aktualizacji. Trzymaj kopię PO i MO, a po aktualizacji komponentu porównaj nowe ciągi z poprzednią wersją.
Jak ustawić język i formaty regionalne WordPressa?
Język witryny ustawisz przez `Ustawienia > Ogólne > Język witryny`, a po zapisaniu sprawdzisz, czy WordPress używa oczekiwanego locale. To ustawienie wpływa na wybór tłumaczeń i język witryny, ale nie tłumaczy treści stron ani tekstów wpisanych na stałe w kodzie.
Język panelu administratora może zależeć także od profilu konkretnego użytkownika. Zaloguj się na konto, otwórz `Użytkownicy > Profil` i sprawdź pole `Język`; dokumentacja WordPressa potwierdza, że zmienia ono język ekranu administracyjnego bez zmiany języka widocznego dla odwiedzających. Dlatego jeden administrator może widzieć panel po angielsku, choć witryna i użytkownicy mają ustawiony polski.
| Ustawienie | Co kontroluje | Co sprawdzić przy rozbieżności |
|---|---|---|
| Język witryny | Locale witryny i część interfejsu | Ustawienie w `Ustawienia > Ogólne` oraz dostępność pakietu językowego |
| Język profilu | Panel konkretnego użytkownika | `Użytkownicy > Profil > Język` |
| Strefa czasowa | Interpretację czasu publikacji i zdarzeń | Wybierz miasto z odpowiednią strefą, jeśli jest dostępne |
| Format daty i godziny | Sposób prezentacji dat przez motyw | Nie każda wtyczka ani ekran administracyjny stosuje globalny format |
| Początek tygodnia | Kalendarze korzystające z ustawienia WordPressa | Własny kalendarz może stosować odrębną konfigurację |
Dokumentacja ekranu Ustawienia ogólne WordPressa wyjaśnia, że format daty i czasu jest przeznaczony dla motywów i nie zmienia wszystkich dat w panelu. Jeśli godzina zamówienia jest nieprawidłowa, sprawdź ustawienie WordPressa, konfigurację wtyczki i strefę serwera.
Jak diagnozować brak tłumaczenia na stronie?
Sprawdź kolejno locale, domenę tekstową, ścieżkę, format pliku, mechanizm ładowania i cache. Najpierw ustal, czy tekst pochodzi z motywu, wtyczki, WordPressa, JavaScriptu czy treści zapisanej w bazie. Taka kolejność odróżnia błędny plik od komunikatu, którego nie obejmuje mechanizm gettext.
| Objaw | Prawdopodobna przyczyna | Test i następny krok |
|---|---|---|
| Cały komponent pozostaje w języku źródłowym | Błędne locale albo brak tłumaczenia dla niego | Porównaj `Język witryny` z nazwą pliku, na przykład `pl_PL` |
| Część tekstów działa, a część nie | Zła domena, brakujący wpis lub tekst na stałe | Porównaj domenę z nagłówkiem komponentu i wyszukaj ciąg w kodzie |
| PO ma przekłady, ale strona pokazuje oryginał | Brak MO, zła ścieżka albo nazwa pliku | Sprawdź plik na serwerze przez SFTP i dopasuj nazwę do domeny i locale |
| Custom działa w edytorze, ale nie na stronie | Loco jest wyłączone albo loader uruchamia się za późno | Włącz Loco i sprawdź kolejność ładowania tłumaczeń |
| Panel jest po polsku, witryna nie | Różne ustawienia panelu i witryny | Porównaj `Ustawienia > Ogólne` z językiem profilu użytkownika |
| Nie tłumaczy się tylko element JavaScript | Brak albo błędna rejestracja pliku JSON | Sprawdź `wp_set_script_translations()` i plik JSON dla skryptu |
| Loco nie może zapisać pliku | WordPress blokuje modyfikację plików lub zapis | Sprawdź ustawienia hostingu i komunikat wtyczki, nie omijaj blokady bez diagnozy |
Komunikat `File modification is disallowed by your WordPress config` oznacza, że konfiguracja WordPressa nie zezwala na daną modyfikację pliku. Loco Translate respektuje tę blokadę. Producent zaleca ustalić jej przyczynę z administratorem lub hostingiem zamiast rozszerzać uprawnienia bez analizy; więcej informacji znajduje się w dokumentacji dostępu do plików Loco.
Po sprawdzeniu plików wyczyść cache wtyczki, hostingu i CDN, a następnie otwórz stronę w prywatnym oknie. Jeśli nie tłumaczy się jeden przycisk, wyszukaj jego dokładną treść w PHP i JavaScript. Tekst zakodowany na stałe wymaga zmiany kodu, a nie kolejnego pliku PO. Przy zmianach na stronie lokalnej możesz skorzystać z poradnika konfiguracji Local WP lub porównać Local, wp-env i inne środowiska WordPress.
Kto powinien odpowiadać za lokalizację WordPressa?
Administrator odpowiada za ustawienia i bezpieczne wdrożenie pliku, tłumacz za jakość językową, a programista za poprawki w kodzie. Przydzielenie zadania według źródła problemu ogranicza ryzyko, że ktoś zmieni pliki komponentu bez możliwości odtworzenia zmian.
| Rola | Typowa zmiana | Wymagany dostęp | Ryzyko przy błędzie |
|---|---|---|---|
| Administrator | Locale, ustawienia regionalne, Loco Translate i kontrola po aktualizacji | Panel WordPressa, kopia zapasowa | Zapis w lokalizacji zarządzanej przez aktualizacje |
| Tłumacz | Przekład komunikatów, kontekst i odmiana | Edytor PO lub uprawnienia do tłumaczeń | Zmieniony placeholder lub niejednoznaczny komunikat |
| Programista | Domena, funkcje gettext, ścieżka lub tłumaczenia JavaScript | Kod, repozytorium i środowisko testowe | Błąd PHP lub JavaScript wpływający na działanie komponentu |
Programista jest potrzebny, gdy tekst jest zakodowany na stałe, brakuje domeny tekstowej albo komponent ładuje pliki w nieprawidłowym momencie. Jeśli problem dotyczy także innych funkcji, na przykład wyszukiwarki, rozdziel przyczynę od tłumaczenia: poradniki o konfiguracji Ajax Search Lite i Better Search Replace opisują odrębne zadania administracyjne.
Perspektywa KC Mobile. W pracach nad WordPressem najpierw ustalamy, który komponent generuje komunikat. Podobny tekst może pochodzić z motywu, wtyczki, własnego szablonu lub skryptu, a każdy z tych przypadków wymaga innej poprawki. Jeżeli lokalizacja wymaga modyfikacji kodu albo testu po aktualizacji, opieka nad WordPressem może objąć diagnozę i utrzymanie witryny zgodnie z zakresem usługi. Przy przenosinach warto też sprawdzić, czy kopia obejmuje własne pliki PO, MO i JSON, opisane w poradniku o migracji WordPressa na nowy hosting.
Więcej poradników w tym temacie
Wspomniane narzędzia
Najczęściej zadawane pytania
Co oznacza WordPress localization?
Jak przetłumaczyć motyw WordPress?
Jak przetłumaczyć wtyczkę WordPress?
Do czego służą pliki PO i MO w WordPressie?
Czy aktualizacja WordPressa może nadpisać tłumaczenia?
Dlaczego język panelu różni się od języka witryny?
Krzysztof Czapnik
Founder & Technical Lead, KC Mobile
Projektuję i rozwijam strony WordPress, sklepy WooCommerce oraz aplikacje internetowe. Łączę projektowanie z programowaniem, integracjami i technicznym SEO. Projekty KC Mobile prowadzę osobiście.
Potrzebujesz pomocy z tym tematem? Napisz - odpowiem osobiście w 24h.
Potrzebujesz pomocy w tym temacie?
Czytasz poradnik „WordPress localization: lokalizacja motywu i wtyczek krok po kroku”. Napisz, co chcesz zrobić i na jakim etapie jesteś. Ustalimy, czy możemy pomóc i jaki zakres prac będzie potrzebny.