Instrukcja o wtyczce "Generator wielojęzycznych stron (shop)"

Generator wielojęzycznych stron - instrukcja konfiguracji i użytkowania.

1. Instalacja wtyczki.

Wtyczkę instaluje się poprzez Instalator Webasyst. Po zakończeniu procesu instalacji przejdź do panelu administracyjnego aplikacji "Shopy-Script → Wtyczki → Generator wielojęzycznych stron", aby rozpocząć konfigurację.

2. Zakładka „Dostawcy AI” - podłączenie AI.

2.1 Włączanie wtyczki.

Aby wtyczka była aktywna, należy ją włączyć. W stanie wyłączonym żadne operacje tłumaczenia ani zarządzanie powiązaniami między stronami nie będą dostępne.

2.2 Wybór dostawcy AI.

Z rozwijanej listy dostępnych dostawców wybierz tego, którego zamierzasz używać:

• ChatGPT (OpenAI) - sprawdzony wybór, wysoka jakość tłumaczeń dla języków europejskich;
• DeepSeek - optymalny stosunek kosztów do jakości generowanych treści;
• Gemini (Google) - doskonałe wyniki przy dużych wolumenach tekstu;
• Qwen (Alibaba) - sprawdza się szczególnie dobrze w przypadku języków azjatyckich.
• OpenRouter - agregator umożliwiający korzystanie z wielu modeli różnych producentów przez jeden klucz API, w tym także z modeli darmowych.

2.3 Konfiguracja dostawcy.

Po wybraniu dostawcy należy podać następujące dane:

Klucz API - token dostępowy umożliwiający komunikację z API wybranego dostawcy. Klucz generuje się w panelu zarządzania danego serwisu (OpenAI, Gemini, DeepSeek, Qwen, OpenRouter).

Po wpisaniu klucza kliknij przycisk „Pobierz modele”. Wtyczka automatycznie pobierze listę dostępnych modeli tekstowych i uzupełni listę rozwijaną modeli.

Następnie wybierz model z listy. Zalecane jest używanie najnowszej stabilnej wersji modelu.

W przypadku OpenRouter model należy wpisać ręcznie. W katalogu modeli OpenRouter dostępnych jest bardzo wiele opcji. Sugerujemy sortowanie wyników według ceny od najniższej - do zadań tłumaczeniowych nie są potrzebne najdroższe modele. Aby skopiować ścieżkę modelu, najedź kursorem na wybrany model, kliknij ikonę kopiowania obok nazwy, a następnie wklej w pole „Model” wtyczki.

2.4 Test połączenia.

Kliknij „Test połączenia”, aby zweryfikować komunikację z dostawcą. W przypadku powodzenia pojawi się zielony komunikat „OK”.

Pamiętaj o zasileniu konta u dostawcy AI. Większość modeli nie oferuje darmowych tokenów ani okresów próbnych. W przypadku braku środków test zakończy się komunikatem o błędzie, a nie „OK”.

2.5 Własny prompt systemowy.

Pole „Spersonalizowany prompt systemowy” pozwala zdefiniować dodatkowy kontekst dla AI, który wpłynie na jakość tłumaczenia. Przykładowy prompt:

Jesteś profesjonalnym tłumaczem. Używaj oficjalnej terminologii. Wszystkie nazwy produktów tłumacz z zachowaniem nazw marek. Używaj standardowych myślników, nie używaj długich pauz.

Jeżeli pole pozostanie puste, wtyczka użyje domyślnego promptu, który w większości przypadków jest wystarczający. Mimo to zalecamy przetestowanie tłumaczenia na jednej lub dwóch stronach przed rozpoczęciem masowego generowania, aby ocenić rezultat i ewentualnie dostosować prompt.

2.6 Precyzyjna regulacja AI podczas generowania.

Maksymalna liczba tokenów.

Parametr ten określa górny limit odpowiedzi AI dla pojedynczego żądania. Jeśli strona zawiera obszerną treść, AI może przekroczyć ten limit - wówczas treść nie zostanie przetłumaczona, a strona zostanie zapisana z oryginalną zawartością. Przetłumaczone zostaną wtedy tylko tytuł, adres URL oraz pola META.

Zalecenie: dla stron o długości do 2000-3000 znaków domyślna wartość 4096 tokenów jest w pełni wystarczająca. Przy większej ilości tekstu zwiększ limit do 8192 lub 16384. Zbyt wysoka wartość może jednak spowodować przekroczenie limitu czasu wykonania, co również skutkuje pominięciem strony.

Opóźnienie między stronami.

Jest to przerwa pomiędzy kolejnymi żądaniami do AI podczas generowania masowego. Wartość można ustawić w zakresie od 0 do 30000 ms. Ustawienie to jest przydatne, gdy dostawca AI nakłada ograniczenia na liczbę żądań na minutę (RPM) i zwraca błędy typu „Too many requests” lub „Rate limit exceeded”.

Zalecenia: zacznij od 500-1000 ms. Jeśli błędy występują nadal, zwiększaj opóźnienie stopniowo o 500 ms. Jeżeli nie ma błędów, pozostaw wartość 0 (bez opóźnienia). Pamiętaj, że błąd „Operation timed out” nie jest związany z tym ustawieniem - w takiej sytuacji zwiększ „Maks. liczba tokenów”.

2.7 Linki w treści.

Opcja „Linki w treści” decyduje o sposobie postępowania z odnośnikami (href, src) podczas tłumaczenia strony:

• Kopiuj bez zmian (domyślnie) - wszystkie atrybuty href i src pozostają niezmienione. Jest to zalecane ustawienie w większości przypadków.
• Pozostaw puste - wewnętrzne odnośniki href oraz src zostaną usunięte w przetłumaczonych stronach. Rozwiązanie to sprawdza się, gdy każda wersja językowa korzysta z własnych obrazów i linków wewnętrznych.

2.8 Konfiguracja zadania CRON.

Wtyczka wymaga obowiązkowego skonfigurowania zadania CRON. Komendę znajdziesz w ustawieniach wtyczki - zadanie musi być uruchamiane co minutę. Bez aktywnego zadania CRON generowanie stron nie będzie działać! Mechanizm ten został celowo zaprojektowany w ten sposób, aby cały proces generowania odbywał się w tle i nie spowalniał działania witryny sklepowej podczas oczekiwania na odpowiedzi od AI.

3. Zakładka „Lokalizacje” - konfiguracja języków.

W tym miejscu określasz język źródłowy oraz docelowe języki, na które strony mają być tłumaczone.

3.1 Lokalizacja bazowa.

Wybierz język bazowy, w którym utworzone są oryginalne strony Twojej witryny sklepowej. Na przykład, jeśli treści są po polsku, wybierz "Polski (pl_PL)".

3.2 Docelowe lokalizacje.

Zaznacz języki, na które mają zostać przetłumaczone strony. Możesz wybrać dowolną liczbę języków jednocześnie.

3.3 Zarządzanie lokalizacjami.

Klikając „+ Dodaj nową lokalizację” możesz dodać język, którego nie ma na liście. Otworzy się okno modalne, w którym należy skonfigurować:

• Lokalizacja - wybór z listy rozwijanej.
• Waluta - domyślna waluta dla danego regionu.
• Oryginalne nazwy - w języku ojczystym:
  • Język (przykład: „Deutsch”);
  • Kraj (przykład: „Deutschland”).
• Nazwy po angielsku:
  • Język (przykład: „German”);
  • Kraj (przykład: „Germany”).
• Separator tysięcy - najczęściej spacja lub przecinek.
• Separator dziesiętny - najczęściej kropka lub przecinek.
• Liczba miejsc po przecinku - liczba cyfr po przecinku dla wartości niecałkowitych, np. ceny lub wagi produktu.
• Pierwszy dzień tygodnia - przykładowo niedziela lub poniedziałek.
• Kierunek pisma - LTR (od lewej do prawej) lub RTL (od prawej do lewej, dla języka arabskiego, hebrajskiego itp.).

Po dokonaniu wyboru nie zapomnij kliknąć "Zapisz"!

Ważne! Każda lokalizacja docelowa wymaga osobnej strony głównej (root) w Mapie witryny aplikacji „Shopy-Script”. Przykładowo: dla języka polskiego - /pl/, dla angielskiego - /en/, a jeśli główna aplikacja w witrynie sklepowej to nie „Shopy-Script”, to odpowiednio /pl/shop/ i /en/shop/. Wtyczka nie tworzy routingu automatycznie.

3.4 Zmiana języka bazowego.

Jeżeli zmienisz język bazowy (np. z polskiego na angielski), dotychczasowa lokalizacja bazowa zostanie automatycznie przeniesiona do listy języków docelowych. Istniejące powiązania między stronami pozostaną nienaruszone i będą działać w obie strony.

3.5 Dodatkowe parametry strony.

Wtyczka umożliwia przenoszenie danych z pola „Dodatkowe parametry” do tłumaczonej strony. Jeśli wartość parametru stanowi zwykły tekst w języku bazowym, zostanie ona automatycznie przetłumaczona. Obsługiwane jest również rozszerzenie „Zarządzanie dodatkowymi parametrami” (advancedparams) dla Shopy-Script - pola input, textarea, html, select, radio, a także pliki i obrazy są poprawnie kopiowane do nowej strony.

4. Integracja z aplikacją Multilang.

Jeśli w systemie zainstalowana jest aplikacja Multilang, wtyczka automatycznie wykorzysta jej mechanizmy po włączeniu opcji "Obsługa Multilang" w ustawieniach.

Korzyści z integracji:

• Po zmianie języka na froncie automatycznie wyświetlana jest odpowiednia przetłumaczona wersja strony.
• Możliwa jest synchronizacja lokalizacji - wtyczka przeskanuje istniejące powiązania i utworzy odpowiadające im wpisy w aplikacji Multilang.

Uwaga: Aplikacja Multilang nadal obsługuje pozostałe aplikacje (Shop, Blog itd.) w standardowy sposób. Wtyczka przejmuje wyłącznie logikę stron aplikacji "Shopy-Script".

5. Zakładka „Strony główne”.

W tej sekcji przypisujesz stronom głównym (root) odpowiednie języki. Wtyczka obsługuje wiele witryn (domen), co umożliwia niezależną konfigurację stron głównych dla każdego storefrontu:

Po przypisaniu języka do strony głównej dla każdej domeny zapisz zmiany. Umożliwi to na zakładce „Strony” szybkie przełączanie się między domenami i pracę z właściwymi lokalizacjami.

6. Zakładka „Strony” - generowanie stron.

Jest to główny panel roboczy do masowego zarządzania tłumaczeniami.

6.1 Wybór domeny i lokalizacji docelowej.

Na początek określ:

1. Domena (storefront) - witrynę sklepową, dla której wtyczka będzie generować strony.
2. Docelowa lokalizacja - język, na który mają być tłumaczone strony.

Następnie kliknij "Załaduj strony".

6.2 Drzewo stron.

Wtyczka wyświetli dwa panele:

• Lewy panel - hierarchiczne drzewo stron języka bazowego (źródło).
• Prawy panel - lustrzane odbicie pokazujące stan tłumaczenia każdej strony dla wybranego języka docelowego.

6.3 Statusy stron.

Każda strona w prawym panelu posiada jeden z poniższych statusów:

• Nieprzetłumaczona - tłumaczenie nie istnieje. Zaznacz pole, aby dodać je do kolejki generowania.
• ✓ - tłumaczenie zostało utworzone. Widoczna jest przetłumaczona nazwa i ikona z adresem URL.
• ⚠ - oryginał uległ zmianie po utworzeniu tłumaczenia. Zalecana jest aktualizacja. Widoczna jest ikona z adresem URL.
• ⚠ - AI nie przetłumaczyło treści z powodu przekroczenia limitu tokenów. Strona została utworzona - nagłówek, URL i meta są przetłumaczone, ale główna treść pozostała w języku źródłowym. Edytuj stronę ręcznie lub zwiększ limit tokenów i wygeneruj ponownie.

6.4 Zaznaczanie stron do generowania.

Do szybkiego wyboru wielu stron służy filtr umożliwiający masowe zaznaczanie:

• Wszystkie - zaznacza wszystkie strony w drzewie.
• Wszystkie nieutworzone - zaznacza wyłącznie strony jeszcze nieprzetłumaczone.
• Wszystkie zmienione - zaznacza strony wymagające aktualizacji po zmianie oryginału.

6.5 Generowanie masowe.

1. Zaznacz strony przeznaczone do tłumaczenia.
2. Kliknij przycisk „Generuj wybrane”.

Wtyczka rozpocznie przetwarzanie stron jedna po drugiej:

• Nie odświeżaj strony podczas generowania! Postęp możesz śledzić na pasku postępu.
• Dla każdej strony AI tworzy:
  • Nagłówek - przetłumaczona nazwa strony;
  • META Title - tytuł SEO w języku docelowym;
  • URL - przyjazny adres w języku docelowym;
  • Treść - kompletna zawartość HTML z zachowaniem układu;
  • META Keywords - przetłumaczone słowa kluczowe;
  • META Description - przetłumaczony opis;
  • Open Graph - przetłumaczone pola og:title i og:description (jeśli istnieją);
  • Dodatkowe parametry (jeśli istnieją) - tłumaczona jest wyłącznie wartość po znaku „=”, nazwa parametru pozostaje bez zmian.

Po zakończeniu obok każdej przetworzonej strony pojawi się link prowadzący do edytora.

Ważne! Wszystkie nowo utworzone strony są domyślnie zapisywane jako wersja robocza. Przed opublikowaniem zalecamy sprawdzenie jakości tłumaczenia i poprawności kodu HTML w edytorze.

7. Tłumaczenie z poziomu edytora stron.

Tłumaczenie można również wykonać bezpośrednio ze standardowego edytora stron aplikacji „Shopy-Script”, bez wchodzenia w ustawienia wtyczki.

7.1 Przycisk „Tłumacz”.

Otwórz stronę w edytorze. Obok selektorów wyboru edytora pojawi się przycisk „Tłumacz”. Kliknięcie otwiera okno modalne konfiguracji tłumaczenia.

7.2 Okno modalne tłumaczenia.

W oknie modalnym dostępne są następujące informacje:

• Bieżąca strona - nazwa edytowanej strony.
• Lokalizacja - adres URL bieżącej strony.
• Istniejące tłumaczenia - lista powiązanych tłumaczeń na inne języki (jeśli istnieją).
• Utwórz/Aktualizuj tłumaczenie - sekcja wyboru języków docelowych (dostępne są wyłącznie języki dozwolone w ustawieniach wtyczki).

Po wybraniu języków masz do wyboru dwie opcje:

1. Utworzyć i przetłumaczyć - generuje nowe tłumaczenia dla wybranych języków.
2. Aktualizować tłumaczenie - ponownie generuje istniejące tłumaczenia.

7.3 Postęp i wynik.

Po uruchomieniu generowania wyświetlony zostanie pasek postępu. Po zakończeniu otrzymasz bezpośrednie linki do edycji każdej utworzonej lub zaktualizowanej strony.

7.4 Przełącznik języków.

W edytorze strony pojawi się rozwijana lista przełącznika języków (jeśli istnieje co najmniej jedno powiązane tłumaczenie). Umożliwia on błyskawiczne przejście między wersjami językowymi tej samej strony bez powrotu do listy stron.

Funkcja ta znacznie przyspiesza pracę, pozwalając szybko porównać treść lub nanieść poprawki bez opuszczania edytora.

8. Co dzieje się podczas tłumaczenia (szczegóły techniczne).

8.1 Zachowanie struktury.

AI otrzymuje pełen kod HTML strony i tłumaczy wyłącznie widoczną treść tekstową. Bez zmian pozostają:

• Znaczniki HTML i klasy CSS;
• Obrazy, filmy oraz ścieżki do plików;
• Skrypty JavaScript i bloki style;
• Kod Smarty ({$var}, {if}, {foreach}, itd.);
• Atrybuty data-* oraz identyfikatory elementów (ID).

8.2 Dodatkowe parametry.

Dane META (title, keywords, description, og:title, og:description) - podlegają tłumaczeniu przez AI.
Obrazy Open Graph oraz pola OG zawierające linki - kopiowane bez zmian.
Dodatkowe parametry (klucz=wartość) - tłumaczeniu podlega wyłącznie wartość, klucz pozostaje niezmieniony (funkcja dostępna po włączeniu odpowiedniej opcji).

8.3 Aktualizacja po zmianie oryginału.

Po modyfikacji strony źródłowej wtyczka oznaczy powiązane tłumaczenia ikoną ⚠. Wystarczy kliknąć przycisk aktualizacji w oknie tłumaczenia, aby AI ponownie przetworzyło treść.