Lokalise i WordPress: integracja tłumaczeń w motywie ZEN.COM

Lokalise da się połączyć z WordPressem tak, że każdy tekst w szablonie motywu ma swój klucz w Lokalise, tłumacze pracują wyłącznie w panelu Lokalise, a strona czyta gotowe tłumaczenia z lokalnej kopii w bazie danych. Tak działa integracja, którą rozwijamy w motywie ZEN.COM od maja 2025 r. Opisujemy, jak wygląda helper w PHP, jak przebiega synchronizacja, co z tytułami SEO i na jakie pułapki trafiliśmy przy audycie treści, gdy projekt w Lokalise urósł do ponad 10 tys. kluczy.

Czym jest Lokalise i po co łączyć go z WordPressem?

Platforma Lokalise służy do zarządzania tłumaczeniami. Każdy tekst ma w niej klucz, na przykład nagłówek sekcji cennika, a pod kluczem leżą wersje w kolejnych językach, które tłumacze uzupełniają w przeglądarce, bez dostępu do kodu ani panelu WordPressa. Tłumacze widzą kontekst, historię zmian i brakujące tłumaczenia, a aplikacje pobierają gotowe teksty przez API.

W WordPressie tłumaczenia zwykle obsługuje WPML albo podobna wtyczka i dopóki treść siedzi w edytorze stron, to wystarcza. ZEN.COM ma jednak większość copy wpisaną w szablony PHP motywu: cenniki, porównania kart, sekcje landingów. Takie teksty ktoś musi wyciągnąć z kodu, przekazać tłumaczom i odłożyć z powrotem, a serwis ma 25 wersji językowych. Ręczne przenoszenie tekstów w tej skali kończy się rozjazdem wersji już po kilku tygodniach, więc teksty z szablonów obsługuje Lokalise, a strony i adresy dalej WPML.

Tłumaczenia w WordPressie wymknęły się spod kontroli? Łączymy WordPress z Lokalise, WPML i własnymi systemami tłumaczeń, porządkujemy klucze i przygotowujemy audyty treści w wielu językach. Opisz, jak dziś pracuje Twój zespół. Strony internetowe →

Jak działa integracja Lokalise z motywem WordPressa?

Integracja to moduł w motywie, około 2 tys. linii PHP. Programista w szablonie nie wpisuje tekstu wprost, tylko wywołuje helper __l(), który zwraca tłumaczenie, albo _el(), który od razu je wypisuje, a każde wywołanie podaje klucz i tekst domyślny po angielsku.

• Domena z klucza. Dwa pierwsze segmenty klucza, np. landing.pricing, wyznaczają domenę, czyli grupę tekstów jednej strony albo modułu.
• Klucze tworzą się same. Gdy w kodzie pojawia się klucz, którego nie ma w Lokalise, integracja go zakłada razem z tekstem domyślnym, więc programista nie zgłasza nowych tekstów ręcznie.
• Placeholdery. Zmienne części tekstu, np. kwota albo nazwa karty, wchodzą jako {arg} i są podstawiane po pobraniu tłumaczenia, więc tłumacz może przestawić je w zdaniu.
• Tekst domyślny jako zabezpieczenie. Gdy tłumaczenia nie ma, strona pokazuje tekst z kodu zamiast pustego miejsca albo nazwy klucza.

Skala pokazuje, czemu ręczna praca nie wchodzi w grę. W motywie jest ponad 8,7 tys. wywołań tych helperów w blisko 350 plikach, a projekt w Lokalise ma 10 819 kluczy.

Skąd WordPress bierze tłumaczenia i jak działa synchronizacja?

Strona nie pyta API Lokalise przy każdym wejściu użytkownika, bo czytanie z zewnętrznego API przy wyświetlaniu strony to proszenie się o kłopoty: limit zapytań, dodatkowe opóźnienie każdej odsłony i awaria po drugiej stronie, na którą nie masz wpływu. Dlatego integracja trzyma lokalną kopię w czterech tabelach bazy WordPressa:

Synchronizacja to zadanie cron uruchamiane co 10 minut i tylko na produkcji. Idzie w dwie strony: nowe klucze, które pojawiły się w kodzie od ostatniego przebiegu, trafiają do Lokalise, a gotowe tłumaczenia wracają do lokalnej bazy WordPressa. Na środowisku testowym zadanie się nie uruchamia, bo każda gałąź z eksperymentalnym tekstem dopisywałaby klucze, których tłumacze nie powinni oglądać.

Drobiazg, który ma znaczenie przy dużym ruchu: tabele zakłada migracja uruchamiana raz, jako jednorazowe zadanie cron, a po jej wykonaniu WordPress zapisuje flagę w opcjach. Sprawdzanie schematu bazy przy każdym żądaniu to praca, której serwer nie musi wykonywać przy każdej odsłonie.

Czy tytuły i opisy SEO też mogą iść przez Lokalise?

Mogą i w ZEN.COM idą. Tytuły i opisy meta z Yoast SEO trafiają do Lokalise jako osobne klucze, a przetłumaczone wersje zapisują się w tabeli SEO. Dzięki temu tłumacz pracuje nad tytułem strony w tym samym miejscu co nad jej nagłówkiem, a zespół SEO nie musi przeklikiwać każdej wersji językowej w panelu WordPressa.

Przy wielu językach zmienia to też kontrolę jakości, bo w Lokalise brakujące tłumaczenia tytułów da się wyfiltrować jednym kliknięciem, a w WordPressie trzeba by otwierać każdą stronę w każdej wersji językowej po kolei.

Jak znaleźć, który klucz Lokalise odpowiada za tekst na stronie?

To pytanie zadaje każdy, kto dostaje zgłoszenie „na stronie X jest literówka”, a w motywie z tysiącami kluczy zgadywanie po treści nie działa. Integracja ma więc tryb debug, który zamiast tłumaczeń pokazuje nazwy kluczy. Redaktor otwiera stronę z tym trybem, odczytuje klucz i szuka go w Lokalise.

Odwrotne pytanie jest trudniejsze: na których stronach występuje dany klucz? We wrześniu 2026 r. przygotowaliśmy audyt słów w polskich tekstach, który dla każdego trafienia miał podać klucz, treść i realny adres strony. Po drodze trafiliśmy na trzy problemy.

1. Eksport jest za duży na jeden raz. Pełne pobranie kluczy z tłumaczeniami we wszystkich językach to około 500 MB JSON-a i PHP kończy pamięć. Skrypt pobiera klucze stronami i przetwarza każdą stronę od razu, bez trzymania całości w pamięci.
2. Klucz nie wie, na jakiej jest stronie. Wiele kluczy siedzi w fragmentach szablonów dołączanych do innych szablonów. Skrypt śledzi więc, który plik dołącza który, aż dojdzie do szablonu przypisanego do konkretnej strony w WordPressie. Realny adres dostało 371 z 386 trafień, czyli 96%. Reszta to teksty w menu, które są na każdej stronie, strony bez polskiej wersji i strony jeszcze nieopublikowane.
3. Dwa polskie języki w jednym projekcie. Projekt w Lokalise miał zarówno pl, jak i pl_PL, a teksty były wpisane raz w jeden, raz w drugi. Helper w motywie zamienia pl na pl_PL, ale część stron miała treść tylko w pl. Przy czytaniu jednego języka audyt pokazywał 96 trafień, a po uwzględnieniu obu języków i pustych wartości, o których niżej, 386.

Ostatni punkt ma też drugie dno. Przy łączeniu dwóch źródeł w PHP łatwo napisać $a ?? $b, tymczasem operator ?? przechodzi do drugiej wartości tylko wtedy, gdy pierwszej nie ma albo jest null. Pusty string uznaje za poprawną wartość, więc klucz z pustym pl_PL i pełnym pl wypada z wyników bez żadnego błędu. Tu potrzebny jest jawny warunek !empty().

Co sprawdzić, zanim połączysz Lokalise z WordPressem?

• Które teksty idą przez Lokalise, a które zostają w edytorze WordPressa albo w WPML. Granica powinna być jasna dla redaktorów.
• Ile wersji tego samego języka jest w projekcie Lokalise i która jest docelowa dla strony.
• Czy strona przeżyje awarię API, czyli czy ma lokalną kopię i tekst domyślny.
• Które środowisko synchronizuje się z projektem. Najlepiej tylko produkcja.
• Jak redaktor znajdzie klucz dla tekstu, który widzi na stronie.

Po zmianach w tłumaczeniach przydaje się też przejście po stronach i sprawdzenie, czy nigdzie nie został tekst w złym języku.

Masz WordPressa w wielu językach i teksty rozsiane po szablonach, wtyczkach i arkuszach? Projektujemy i utrzymujemy strony internetowe z integracjami tłumaczeń, a o samej stronie ZEN.COM piszemy w case study. Jak ustawić wersje językowe pod różne rynki, opisujemy w artykule o WPML i geolokalizacji.