Jak dodać translacje w PrestaShop

Sklep internetowy nabiera skrzydeł dopiero wtedy, gdy mówi językiem swoich klientów. W PrestaShop personalizacja treści dla różnych rynków nie wymaga programowania, ale wymaga znajomości narzędzi i kilku dobrych praktyk. W tym poradniku krok po kroku przejdziesz przez dodawanie nowych języków, edycję treści interfejsu, wiadomości e-mail oraz tekstów modułów, a także nauczysz się eksportować i importować paczki tłumaczeń, pracować na plikach i rozwiązywać typowe problemy z widocznością zmian.

Przygotowanie środowiska i podstawowe pojęcia

Co musisz wiedzieć, zanim zaczniesz

Panel tłumaczeń w PrestaShop pozwala zmienić teksty interfejsu sklepu bez dotykania kodu. Zanim wejdziesz do edytora, upewnij się, że masz konto z uprawnieniami do sekcji International oraz dostęp do kopii zapasowej plików i bazy. Przyda się również dostęp do repozytorium projektu, jeśli tłumaczenia chcesz trzymać w plikach i wersjonować je wraz z motywem.

Prace nad tłumaczeniami warto prowadzić w trybie testowym, a dopiero po weryfikacji publikować je na produkcji. Dzięki temu unikniesz sytuacji, w której klienci zobaczą niedokończone teksty lub placeholdery w treści.

Różnice między wersjami 1.6, 1.7 i 8.x

W 1.6 tłumaczenia oparte są o pliki PHP i funkcję {l} w Smarty oraz $this->l w modułach. Od 1.7 i w 8.x działa system oparty o Symfony Translator i domeny tłumaczeń, a pliki mają format XLF. To ważne, bo zmienia lokalizację plików i sposób nadpisywania tekstów. Interfejs w panelu jest podobny, ale nazwy sekcji i ścieżki menu mogą się różnić: w starszych wersjach była to sekcja Localization, nowsze mają International.

Podstawowe pojęcia: język, locale, domena

Język to etykieta, którą widzisz w sklepie, np. Polish. Locale określa wariant języka i formatów, np. pl-PL. Kod ISO (np. pl) odróżnia języki. Domeny tłumaczeń to grupy kluczy, np. Shop.Theme.Catalog lub Admin.Navigation.Header. Zrozumienie tych pojęć ułatwia filtrowanie i namierzanie tekstów, które chcesz zmienić. Dodatkowo pojęcie lokalizacja obejmuje waluty, podatki, jednostki i strefy – te ustawienia znajdziesz obok tłumaczeń i często konfigurujesz równolegle.

Uprawnienia, kopie zapasowe i środowiska

Jeśli korzystasz z ról pracowników, upewnij się, że rola ma dostęp do International oraz Advanced Parameters, by czyścić pamięć podręczną. Przed dużymi zmianami zrób backup. W środowisku developerskim włącz podgląd błędów i ustaw kompilację szablonów na wymuszoną, aby szybciej widzieć efekty.

Gdzie trafiają tłumaczenia

W trybie panelu zmiany zapisywane są w nadpisaniach dla motywu i modułów, tak aby aktualizacje silnika nie kasowały Twoich edycji. W pracy z plikami trafiają do katalogów motywu lub modułów. To bezpieczne podejście, ale wymaga kontroli konfliktów podczas aktualizacji motywu czy rozszerzeń.

Dodawanie nowego języka

Szybka instalacja z paczki

Najprostsza droga to pobranie i zainstalowanie gotowej paczki językowej:

• Przejdź do International › Translations.
• W sekcji Add/Update a language wybierz docelowy język z listy.
• Kliknij dodaj/aktualizuj. Sklep pobierze pliki z repozytorium PrestaShop i zainstaluje tłumaczenia.
• Po zakończeniu odśwież stronę, wejdź do frontu i sprawdź selektor języka.

Jeśli elementy nie są przetłumaczone, to normalne – część treści pochodzi z motywu i modułów, które mogą mieć swoje osobne paczki lub wymagać ręcznej edycji w panelu.

Ręczne dodanie języka w ustawieniach

Gdy paczka nie jest dostępna lub potrzebujesz języka niestandardowego:

• Wejdź w International › Languages.
• Kliknij Add new language i uzupełnij: Name, ISO code, Language code, Date format, Numeral format, kierunek tekstu (LTR/RTL).
• Zapisz i włącz język. Ustaw go jako domyślny w Shop Parameters › General lub w ustawieniach lokalizacji.

Po dodaniu języka możesz przetłumaczyć interfejs, e-maile i treści własne (CMS, produkty) w panelu lub w plikach.

Pakiety lokalizacyjne: waluty, strefy, podatki

Oprócz samych tekstów warto doinstalować pakiet lokalizacyjny dla kraju, w którym używasz języka:

• Przejdź do International › Localization.
• Wybierz kraj i zaznacz elementy do importu: waluty, strefy, podatki, jednostki.
• Zaimportuj. Pomoże to w poprawnym formatowaniu cen, dat oraz podatków.

Nie myl tego z tłumaczeniami UI – pakiet lokalizacyjny nie podmienia tekstów interfejsu, ale przygotowuje sklep pod kątem reguł biznesowych danego rynku.

Edytowanie tłumaczeń w panelu

Wejście do edytora i typy tłumaczeń

Główna ścieżka to International › Translations. Zobaczysz moduł edytora z polami:

• Modify translations – wybierz typ: Back office, Front office, Theme translations, Installed modules translations, Email translations.
• Wybór motywu i języka, którego dotyczy edycja.
• Przyciski eksportu i importu paczek językowych.

Filtry pozwalają zawęzić wynik do brakujących tłumaczeń, konkretnej domeny lub wpisać fragment szukanego klucza.

Tłumaczenia motywu: front sklepu

Aby zmienić widoczne dla klientów teksty z warstwy wizualnej, użyj typu Theme/Front office. Następnie:

• Wybierz aktywny motyw i język.
• Wpisz fragment tekstu, który widzisz na stronie, lub poszukaj po domenie Shop.Theme.*.
• Uzupełnij brakujące pola i zapisz. Jeśli to potrzebne, wymuś odświeżenie szablonów.

Jeżeli korzystasz z własnego motywu potomnego, upewnij się, że edytujesz tłumaczenia dla niego. Dzięki temu zmiany nie znikną po aktualizacji bazowego motywu.

Tłumaczenia panelu administracyjnego

Dla sekcji Back office wybierz odpowiedni typ i język. Teksty panelu są pogrupowane w domeny Admin.*. Jeśli nie możesz znaleźć klucza, zawęź wyniki po module lub komponencie. Pamiętaj, że część komunikatów pochodzi z frameworka i może mieć inne nazwy domen.

Tłumaczenia modułów

Wybierz Installed modules translations, a następnie wskaż moduł na liście. Większość autorów dostarcza tłumaczenia, ale jeśli ich brakuje, uzupełnisz je tu. Zwracaj uwagę na zachowanie placeholderów i zmiennych. To szczególnie ważne w rozbudowanych modułyłach, które budują dynamiczne komunikaty i powiadomienia.

E-maile transakcyjne

W Email translations edytujesz zarówno HTML, jak i wersje tekstowe. Dla 1.7/8.x możesz wskazać motyw e-maili oraz język. Pamiętaj o spójności tematów wiadomości i treści – klient widzi oba. Zmieniaj tylko treści między znacznikami i nie usuwaj tokenów, takich jak {firstname}, {shop_name} czy zmienne smarty – silnik generuje z nich dane zamówienia.

Filtrowanie, szybkie wyszukiwanie i brakujące klucze

Jeśli nie znajdujesz tekstu, który widzisz na stronie, sprawdź, czy nie należy do innej domeny lub modułu. W nowych wersjach wygodny jest filtr Missing translations. Czasem tekst pochodzi z tłumaczeń motywu, a nie z modułu, choć komponent wyświetla go w bloku modułu – warto sprawdzić oba miejsca.

Dobre praktyki w edytorze

• Edytuj i zapisuj sekcjami – łatwo wrócisz do bezpieczeństwa wersji.
• Używaj konsekwentnej terminologii w całym sklepie.
• Testuj różne stany interfejsu: puste koszyki, błędy walidacji, brak produktów.
• Po większym zestawie zmian wyczyść cache i odśwież stronę w trybie prywatnym.

Praca z plikami tłumaczeń

Gdzie znajdują się pliki

W 1.7 i 8.x pliki tłumaczeń znajdują się w formacie XLIFF w następujących miejscach:

• Motyw: /themes/nazwa_motywu/translations/locale.xlf
• Moduł: /modules/nazwa_modułu/translations/locale.xlf
• Motyw dla modułu: /themes/nazwa_motywu/modules/nazwa_modułu/translations/locale.xlf
• Rdzeń: zasoby w katalogach PrestaShopBundle lub /translations – nie edytuj bez potrzeby.

W 1.6 znajdziesz pliki PHP: dla motywu w /themes/nazwa/lang/iso.php, a dla modułów w /modules/nazwa/translations/iso.php. Aktualizacje przenoszą część treści do nowego systemu, ale jeśli utrzymujesz starszy sklep, trzymaj się właściwego formatu.

Nadpisy i pierwszeństwo

PrestaShop stosuje priorytet: tłumaczenia w motywie i jego katalogach modułów mają pierwszeństwo przed domyślnymi w module, a te z kolei nadpisują rdzeń. Dzięki temu najłatwiej trwale modyfikować teksty poprzez pliki w katalogu motywu, co docenisz przy wdrożeniach CI/CD i pracy zespołowej.

Tworzenie własnych kluczy w module i motywie

Jeśli tworzysz własny moduł lub zmieniasz szablon, wstawiaj tłumaczenia poprzez funkcje zgodne z wersją sklepu i określaj domeny zgodnie z konwencją Modules.Nazwa.Admin lub Shop.Theme.Obszar. To ułatwi późniejsze wyszukiwanie i spójność. Dla motywów trzymaj strukturę i pliki w katalogu translations, a statyczne komunikaty w Smarty otaczaj funkcją tłumaczenia z poprawną domeną.

Eksport i import paczek

W International › Translations znajdziesz sekcję Export a language:

• Wybierz język i motyw.
• Kliknij Export – pobierzesz paczkę ZIP z plikami tłumaczeń.
• Dodaj paczkę do repozytorium lub przekaż ją na inne środowisko.

Dla importu użyj Import a language i wskaż paczkę ZIP. Jeśli chcesz, aby pliki trafiły do motywu, przygotuj paczkę z właściwą strukturą katalogów. Ta metoda świetnie sprawdza się przy migracjach i wdrożeniach etapowych.

Wersjonowanie i współpraca zespołowa

Zalecaj trzymanie zmian w repozytorium i przeglądy kodu dla tłumaczeń plikowych. W praktyce:

• Wymuszaj UTF-8 bez BOM w edytorze.
• Ustal konwencję nazw domen tłumaczeń dla projektu.
• Łącz PR-y z linkami do zrzutów ekranu – łatwiej ocenić kontekst.
• Na CI uruchamiaj budowę artefaktów i testy dymne pod kątem brakujących kluczy.

Warto też oznaczać tłumaczenia wymagające rewizji komentarzem w pliku XLIFF. Dzięki temu tłumacze i deweloperzy wiedzą, które ciągi wymagają weryfikacji UX.

Motyw i warstwa wizualna

Własny motyw daje pełną kontrolę nad brzmieniem komunikatów. Aby nie stracić tłumaczeń po aktualizacji, korzystaj z motywu potomnego i umieszczaj pliki w jego katalogach translations oraz modules. W razie zmiany grafiki i layoutu upewnij się, że nowe szablony odwołują się do tych samych kluczy, albo przygotuj migrację tłumaczeń do nowych domen.

Najczęstsze problemy i dobre praktyki

Tłumaczenia nie wyświetlają się

Najczęstszą przyczyną jest pamięć podręczna. Włącz tryb developerski na czas pracy lub po zapisaniu tłumaczeń wyczyść Advanced Parameters › Performance i kliknij Clear cache. Dodatkowo w sekcji Smarty ustaw rekompilację szablonów, aby wymuszać efekt zmian. Jeśli to nie pomaga, sprawdź, czy tekst nie pochodzi z innej domeny niż ta, którą edytowałeś.

Konflikt moduł vs motyw

Tekst w widoku modułu bywa fizycznie zdefiniowany w szablonie motywu, który nadpisuje plik modułu. Rozwiązanie: sprawdź katalog /themes/nazwa/modules/nazwa_modułu i poszukaj tam kluczy tłumaczeń. Edytuj je w panelu jako tłumaczenia modułu dla wybranego motywu, albo w pliku XLIFF w katalogu motywu.

Placeholdery i zmienne

Nie usuwaj i nie zmieniaj kolejności placeholderów typu %s, %d, {firstname}, {date}. Jeśli musisz zmienić szyk zdania, dopasuj go tak, by placeholdery zachowały sens. W przeciwnym razie ryzykujesz błędy czasu wykonania lub niespójne komunikaty.

Języki RTL i znaki specjalne

Dla języków pisanych od prawej do lewej włącz RTL w ustawieniach języka i sprawdź kaskadę stylów motywu. Upewnij się, że pliki fontów wspierają znaki diakrytyczne. Unikaj wklejania formatowanych znaków spoza UTF-8 – trzymaj się czystego tekstu i encji HTML tam, gdzie to konieczne.

Aktualizacje i trwałość zmian

Po aktualizacji modułu niekiedy dochodzi do zmiany domen lub kluczy. Jeśli tłumaczenie zniknęło, sprawdź log zmian modułu i porównaj pliki XLIFF. Trzymając tłumaczenia po stronie motywu, minimalizujesz ryzyko nadpisania przez instalator pakietu. Unikaj edycji plików w katalogach rdzenia – przy kolejnej aktualizacji zostaną nadpisane.

Wydajność i pamięć podręczna

W dużych katalogach produktowych lub przy wielu językach odświeżanie tłumaczeń może chwilę potrwać. Zaplanuj „okna zmian” poza godzinami szczytu i wykorzystuj narzędzia do przeładowania cache warstwy front-end, jeśli korzystasz z CDN. Monitoruj logi po masowym imporcie tłumaczeń.

Sklepy wielodomenowe

W trybie multistore ustaw kontekst odpowiedniego sklepu przed edycją tłumaczeń, zwłaszcza jeśli każdy sklep ma inny motyw. Teksty panelu są wspólne, ale tłumaczenia motywu i e-maili zależą od aktywnego motywu w danym sklepie. Po wdrożeniu przejdź przez każdy sklep i sprawdź, czy selektor języka, e-maile i stronice CMS działają poprawnie.

E-maile: obrazy, tematy i testy

Pamiętaj, aby zaktualizować także wersję tekstową e-maili – część klientów i filtrów antyspamowych zwraca na nią uwagę. Jeśli używasz obrazów w e-mailach, sprawdź ścieżki po eksporcie i imporcie paczek. Wysyłaj testy z poziomu zamówienia lub modułów e-mail, by sprawdzić rzeczywisty wygląd w skrzynkach.

Integracje z narzędziami CAT i zewnętrzne słowniki

Format XLIFF dobrze współpracuje z narzędziami CAT. Jeśli tłumaczy wielu specjalistów, rozważ proces: eksport paczki, praca w narzędziu, import z powrotem i review w środowisku testowym. Utrzymuj glosariusz terminów dla sklepu, aby zachować spójność języka marketingowego i transakcyjnego.

Kontrola jakości i checklisty

• Sprawdź koszyk, checkout, maile zamówienia, zwroty i powiadomienia.
• Przejrzyj menu, stopkę, breadcrumb i komunikaty walidacji.
• Zweryfikuj tłumaczenia atrybutów i cech produktów, jeśli są wyświetlane w filtrach.
• Na mobile upewnij się, że długość tekstów nie psuje layoutu przy zawijaniu wierszy.

Po każdym wdrożeniu odnotuj wersje paczek i zakres zmian. Przyda się to przy debugowaniu oraz jako dokumentacja projektu.

Narzędzia deweloperskie i logowanie

Jeśli w logach widzisz ostrzeżenia o brakującym kluczu tłumaczenia, odtwórz sytuację i zanotuj domenę. Dobre logowanie i etykiety commitów upraszczają późniejszą nawigację po zmianach w repozytorium. Gdy pracujesz na środowisku Docker, upewnij się, że wolumeny zawierają aktualne pliki tłumaczeń i że kontener nie buforuje przestarzałych danych.

Warstwa treściowa poza UI

Pamiętaj, że tłumaczenia interfejsu to tylko część pracy. Strony CMS, opisy produktów, atrybuty, cechy, kategorie i banery wymagają osobnej lokalizacji. Zadbaj o spójność języka, odmianę nazw własnych i dostosowanie jednostek miary. Wykorzystaj listy eksportu i importu CSV dla produktów, aby szybciej wprowadzać wielojęzyczne opisy.

Najlepsze praktyki procesu

• Plan: zdefiniuj zakres, role i narzędzia, zanim zaczniesz.
• Konwencja: stosuj spójne domeny i nazewnictwo kluczy.
• Recenzja: podwójne sprawdzenie językowe i funkcjonalne w stagingu.
• Publikacja: okno wdrożeniowe i monitorowanie błędów.
• Utrzymanie: cykliczne przeglądy po aktualizacjach modułów i motywu.

Trzymając się tych zasad, skrócisz czas wdrożenia tłumaczeń i ograniczysz ryzyko regresji w kolejnych wersjach, a Twoje szablony oraz komunikaty pozostaną spójne na wszystkich stronach i kanałach.