Instrukcja o wtyczce "Generator wielojęzycznych stron"

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

1. Instalacja wtyczki.

Zainstaluj wtyczkę za pomocą Instalatora. Po zakończeniu instalacji przejdź do aplikacji "Witryna → Wtyczki → Generator wielojęzycznych stron".

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

2.1 Włączenie wtyczki.

Włącz wtyczkę. Jeśli wtyczka jest wyłączona, żadne tłumaczenia nie będą działać, w tym również powiązania pomiędzy stronami w różnych lokalizacjach.

2.2 Wybór dostawcy AI.

Wybierz jednego z dostępnych dostawców z listy rozwijanej:

• ChatGPT (OpenAI) - najpopularniejszy wybór, doskonała jakość tłumaczeń dla języków europejskich;
• DeepSeek - świetny balans pomiędzy ceną a jakością;
• Gemini (Google) - bardzo wysoka jakość, szczególnie przy dużych ilościach treści;
• Qwen (Alibaba) - dobry wybór dla języków azjatyckich.

2.3 Konfiguracja dostawcy.

Dla wybranego dostawcy uzupełnij:

Klucz API - klucz dostępu do API dostawcy. Możesz go uzyskać w panelu odpowiedniego dostawcy (OpenAI, Gemini, DeepSeek, Qwen).

Po wprowadzeniu klucza API kliknij przycisk „Pobierz modele” - wtyczka pobierze od dostawcy listę dostępnych modeli tekstowych i automatycznie wypełni listę rozwijaną.

Po załadowaniu wybierz model z listy. Zaleca się korzystanie z najnowszego stabilnego modelu.

2.4 Test połączenia.

Kliknij „Test połączenia” - wtyczka wyśle testowe zapytanie do AI i wyświetli wynik. Jeśli połączenie działa poprawnie, zobaczysz zielony komunikat „OK”.

Nie zapomnij doładować salda u swojego dostawcy, ponieważ większość modeli AI nie oferuje darmowych tokenów ani okresu próbnego. W takim przypadku zamiast komunikatu „OK” w teście zostanie wyświetlona odpowiednia informacja.

2.5 Własny prompt systemowy.

Pole tekstowe „Spersonalizowane systemowe prompt” umożliwia zdefiniowanie ogólnego kontekstu dla AI. Na przykład:

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 pozostawisz to pole puste, AI użyje domyślnego promptu wtyczki, który w większości przypadków jest w pełni wystarczający. Zalecamy jednak przed rozpoczęciem masowego generowania stron przetestować tłumaczenie na jednej lub dwóch stronach, aby ocenić rezultat i w razie potrzeby dostosować prompt.

2.6 Precyzyjna regulacja AI podczas generowania.

Maksymalna liczba tokenów.

Ogranicza rozmiar odpowiedzi AI dla pojedynczego zapytania. Jeżeli strona zawiera dużo treści, AI może nie zmieścić się w tym limicie. W takim przypadku tłumaczenie treści zostanie pominięte, a strona zostanie zapisana z oryginalną zawartością w języku bazowym. Przetłumaczone zostaną tytuł (nazwa), adres URL oraz pola META.

Zalecenie: dla krótkich stron (do 2000-3000 znaków) wystarczy 4096 tokenów (wartość domyślna). W przypadku stron zawierających większą ilość tekstu zwiększ limit do 8192 lub 16384. Zbyt wysoka wartość może spowodować przekroczenie limitu czasu podczas generowania (zobacz pole „Opóźnienie między stronami”), co doprowadzi do błędu i pominięcia generowania strony.

Opóźnienie między stronami.

Przerwa pomiędzy zapytaniami do AI podczas masowego generowania (od 0 do 30000 ms). Jest potrzebna, jeśli Twój dostawca AI ogranicza liczbę zapytań na minutę (RPM) i zwraca błąd „Too many requests” lub „Rate limit exceeded”.

Zalecenia: zacznij od wartości 500-1000 ms. Jeżeli błędy nadal występują, zwiększaj opóźnienie o 500 ms aż do uzyskania stabilnej pracy. Jeśli błędów nie ma, pozostaw wartość 0 (bez opóźnienia). Limity czasu po stronie AI (błąd „Operation timed out”) nie są związane z tym ustawieniem - w takich przypadkach zwiększ wartość „Maks. liczba tokenów”.

2.7 Zachowanie linków.

Lista rozwijana „Zachowanie linków” określa sposób obsługi linków (href, src) podczas tłumaczenia:

• Kopiuj bez zmian (domyślnie) - wszystkie linki pozostają takie same jak w oryginale. Zalecane w większości przypadków.
• Pozostaw puste - wszystkie linki (z wyjątkiem zewnętrznych) zostaną wyczyszczone podczas generowania przetłumaczonych stron. Jest to przydatne, jeśli dla każdego języka używasz własnych obrazów i wewnętrznych linków.

2.8 Konfiguracja zadania CRON.

Aby wtyczka działała prawidłowo, należy obowiązkowo skonfigurować zadanie CRON z komendą podaną w ustawieniach wtyczki i uruchamiać je co minutę. Bez poprawnie skonfigurowanego zadania CRON wtyczka nie będzie generować stron! Działanie wtyczki zostało celowo oparte na zadaniu CRON, dzięki czemu cały proces generowania odbywa się w tle i nie obciąża witryny podczas tworzenia stron oraz oczekiwania na odpowiedzi od dostawcy AI.

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

Na tej zakładce określasz, z jakiego języka oraz na jakie języki mają być tłumaczone (generowane) strony.

3.1 Lokalizacja bazowa.

Wybierz język bazowy - jest to język, w którym zostały utworzone oryginalne strony. Przykładowo, jeśli Twoja witryna jest w języku Polskim, wybierz "Polski (pl_PL)".

3.2 Docelowe lokalizacje.

Zaznacz pola wyboru przy językach, na które mają zostać przetłumaczone strony. Możesz wybrać kilka języków jednocześnie.

3.3 Zarządzanie lokalizacjami.

Za pomocą odnośnika „+ Dodaj nową lokalizację” możesz dodać nową lokalizację, jeśli nie znajduje się ona na liście. Otworzy się okno modalne, w którym należy podać:

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

Po wybraniu lokalizacji nie zapomnij kliknąć przycisku "Zapisz"!

Ważne! Dla każdej lokalizacji docelowej w Mapie witryny musi zostać utworzona oddzielna strona główna (root) w aplikacji „Witryna”. Przykładowo dla języka polskiego - /pl/, dla angielskiego - /en/, a jeśli główną aplikacją w Twojej witrynie nie jest „Witryna”, to na przykład /pl/site/ oraz /en/site/. Wtyczka nie tworzy tras (routingu) automatycznie.

3.4 Uwaga dotycząca zmiany języka bazowego.

Jeżeli zdecydujesz się zmienić język bazowy (na przykład z polskiego na angielski), poprzednia lokalizacja bazowa zostanie automatycznie dodana do listy lokalizacji docelowych. Powiązania pomiędzy stronami zostaną zachowane i będą działać w obu kierunkach.

3.5 Przeniesienie i tłumaczenie „Dodatkowych parametrów” strony.

W razie potrzeby można również włączyć przeniesienie wszystkich danych z pola „Dodatkowe parametry”. W takim przypadku, jeśli wartości będą stanowiły zwykły tekst w języku bazowym, zostaną one również przetłumaczone na język docelowy podczas generowania:

8. Integracja z aplikacją Multilang.

Jeżeli na Twojej stronie zainstalowana jest aplikacja Multilang, wtyczka automatycznie zsynchronizuje się z nią po włączeniu w ustawieniach opcji "Obsługa Multilang".

Co to daje:

• Po zmianie języka na frontendzie automatycznie wyświetlana jest właściwa przetłumaczona wersja strony.
• Można zsynchronizować lokalizacje - wtyczka przeskanuje wszystkie powiązania i utworzy odpowiednie skojarzenia z aplikacją Multilang.

Uwaga: Multilang nadal działa dla wszystkich pozostałych aplikacji (Shop, Blog itd.) w standardowy sposób. Wtyczka przejmuje wyłącznie logikę obsługi stron aplikacji "Witryna".

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

W tej sekcji należy skonfigurować dla każdego języka stronę główną (root), na podstawie której zostanie zbudowana cała struktura pozostałych stron w danej lokalizacji. Wtyczka obsługuje funkcję wielu witryn, co pozwala na wybór osobnych stron głównych dla różnych lokalizacji dla każdej domeny (witryny):

Nie zapomnij zapisać zmian po przypisaniu języka do strony głównej dla każdej domeny – pozwoli to na następnej zakładce „Strony” szybko przechodzić między domenami w celu pracy z właściwymi lokalizacjami witryny.

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

To główna zakładka przeznaczona do masowej pracy z tłumaczeniami.

5.1 Wybór domeny i lokalizacji docelowej.

Najpierw wybierz:

1. Domena - domenę (witryna), z którą będzie pracowała wtyczka.
2. Docelowa lokalizacja - język, który ma zostać wygenerowany (przetłumaczony).

Następnie kliknij przycisk "Załaduj strony".

5.2 Praca z załadowanym drzewem stron.

Wtyczka wyświetli dwie kolumny:

• Po lewej - drzewo stron lokalizacji bazowej (strony źródłowe).
• Po prawej - lustrzane drzewo pokazujące status każdej strony dla wybranej lokalizacji docelowej.

5.3 Statusy stron.

Dla każdej strony wyświetlany jest jeden z poniższych statusów:

• Nieprzetłumaczona - tłumaczenie nie zostało jeszcze utworzone. Zaznacz pole wyboru, aby wygenerować tłumaczenie.
• ✓ - tłumaczenie istnieje. Wyświetlana jest przetłumaczona nazwa oraz ikona z adresem URL strony.
• ⚠ - oryginał został zmieniony po utworzeniu tłumaczenia. Zaleca się zaktualizowanie tłumaczenia. Wyświetlana jest również ikona z adresem URL strony.
• ⚠ - AI nie zdołało przetłumaczyć treści strony z powodu przekroczenia limitu „Maks. liczba tokenów”. Sama strona została utworzona – przetłumaczono nagłówek, adres URL i pola meta, ale główny tekst strony pozostał w języku źródłowym. Przejdź do utworzonej strony w edytorze, ręcznie przetłumacz treść, a po zapisaniu ta ikona zniknie. Możesz też zwiększyć wartość „Maks. liczba tokenów” w ustawieniach wtyczki i ponownie wygenerować stronę.

5.4 Wybór stron do masowego generowania (tłumaczenia).

Aby szybko wybrać większą liczbę stron, dostępny jest wygodny filtr umożliwiający zaznaczenie stron do masowego przetwarzania:

• Wszystkie - zaznacza wszystkie strony.
• Wszystkie nieutworzone - zaznacza wyłącznie strony, które nigdy wcześniej nie były generowane i nie mają jeszcze powiązań.
• Wszystkie zmienione - zaznacza strony, które mają już powiązane tłumaczenia, ale wymagają aktualizacji (na przykład po zmianie strony bazowej).

5.5 Masowe generowanie.

1. Zaznacz wymagane strony.
2. Kliknij przycisk „Generuj wybrane”.

Wtyczka rozpocznie kolejno przetwarzanie każdej strony:

• Nie odświeżaj strony do momentu zakończenia generowania! Postęp procesu możesz śledzić za pomocą paska postępu, który pokazuje liczbę przetworzonych stron względem całkowitej liczby.
• Dla każdej strony AI utworzy:
  • Nagłówek - przetłumaczoną nazwę strony;
  • META Title - przetłumaczony tytuł dla wyszukiwarek;
  • URL - przyjazny dla SEO adres w języku tłumaczenia;
  • Treść - pełną zawartość HTML z zachowaniem układu strony;
  • 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ść znajdująca się po znaku „=”, nazwa parametru pozostaje bez zmian.

Po zakończeniu procesu obok każdej utworzonej strony pojawi się odnośnik prowadzący bezpośrednio do jej edycji:

Ważne! Wszystkie nowo utworzone strony są zapisywane jako wersja robocza. Przed publikacją otwórz każdą z nich i sprawdź jakość tłumaczenia oraz poprawność kodu HTML.

6. Tłumaczenie z poziomu edytora stron.

Możesz przetłumaczyć dowolną stronę bezpośrednio w standardowym edytorze aplikacji „Witryna”, bez konieczności przechodzenia do ustawień wtyczki.

6.1 Przycisk „Tłumacz”.

Otwórz dowolną stronę w edytorze. Obok wyboru edytora pojawi się przycisk „Tłumacz”. Po jego kliknięciu zostanie otwarte okno modalne konfiguracji.

6.2 Okno modalne tłumaczenia.

W oknie modalnym wyświetlane są:

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

Po wybraniu odpowiednich języków możesz:

1. Utworzyć i przetłumaczyć - aby utworzyć nowe tłumaczenia.
2. Aktualizować tłumaczenie - aby ponownie wygenerować istniejące tłumaczenia.

6.3 Postęp i wynik.

Po rozpoczęciu procesu zostanie wyświetlony pasek postępu. Po pomyślnym zakończeniu otrzymasz bezpośrednie linki do edycji każdej utworzonej lub zaktualizowanej strony.

6.4 Przełącznik języków.

Dla wygodnego przełączania się pomiędzy różnymi wersjami językowymi powiązanych stron w edytorze pojawi się specjalny przełącznik języków (jeśli istnieje co najmniej jedno powiązane tłumaczenie) - rozwijana lista ze wszystkimi dostępnymi tłumaczeniami bieżącej strony. Wybierz język, a przejdziesz bezpośrednio do edycji odpowiedniej przetłumaczonej strony.

Oszczędza to czas, ponieważ pozwala szybko porównać treść lub wprowadzić poprawki do tłumaczenia bez konieczności wracania do listy stron.

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

7.1 Zachowanie struktury.

AI otrzymuje pełny kod HTML strony i tłumaczy wyłącznie widoczny tekst, pozostawiając bez zmian:

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

7.2 Dodatkowe parametry.

Dane META (title, keywords, description, og:title, og:description) - są tłumaczone przez AI.
Obrazy Open Graph oraz pozostałe pola OG zawierające odnośniki - są kopiowane bez zmian.
Dodatkowe parametry (klucz=wartość) - w razie potrzeby są tłumaczone przez AI, przy czym klucz pozostaje niezmieniony (funkcja jest dostępna po włączeniu odpowiedniej opcji).

7.3 Zachowanie po aktualizacji oryginału.

Jeżeli zmienisz oryginalną stronę, wtyczka oznaczy ją ikoną ⚠. Wystarczy kliknąć przycisk aktualizacji w oknie tłumaczenia, a AI ponownie wygeneruje treść.