← Nauka

Rozwiązywanie problemów

Każdy wpis tutaj opisuje błąd, który naprawdę komuś się przytrafił. Przy każdym podajemy objaw, przyczynę i rozwiązanie — większość sprowadza się do jednej z trzech rzeczy: frazy nie ma w projekcie, SDK nigdy się nie zainicjalizowało albo symbol zastępczy został zapisany dla niewłaściwego kontekstu.

Nic się nie tłumaczy — wszystkie frazy pozostają w języku źródłowym

Jeśli wszędzie widać tekst źródłowy, to niemal na pewno nie udało się zainicjować SDK. Został zaprojektowany tak, by w razie błędu nie przerywać działania (Twój interfejs nigdy nie może się zepsuć), więc jedynym wyraźnym sygnałem jest konsola przeglądarki — sprawdź ją w pierwszej kolejności. Zwykłe przyczyny, od najbardziej prawdopodobnych:

1. CORS. Pierwszym żądaniem SDK jest authorize-project; jeśli Twoje API nie ma origin aplikacji na liście dozwolonych, przeglądarka je zablokuje i inicjalizacja przerwie się właśnie tutaj. Pamiętaj, że origin to dokładnie schemat + host + port — localhost:5173 i localhost:5174 to różne originy, a serwery deweloperskie zmieniają porty, gdy ich zwykły port jest zajęty. Dodaj do listy dozwolonych każdy port, na którym faktycznie pracujesz.
2. Nieprawidłowe dane uwierzytelniające. Brakujący lub błędnie wpisany identyfikator projektu / klucz API powoduje to samo niepowodzenie wywołania autoryzacji. Konsola pokazuje nieudane żądanie i adres URL.
3. Patrzysz na język bazowy. W języku bazowym „tłumaczenie” jest tekstem źródłowym — nic się widocznie nie zmienia. Aby przetestować, przełącz się na język docelowy.

# The SDK's first call is an authorize-project request.
# If the browser blocks it, NOTHING translates. Check the console for:
Access to fetch at 'https://your-api/api/authorize-project/...'
from origin 'http://localhost:5173' has been blocked by CORS policy

# Fix: allowlist the app's EXACT origin (scheme + host + port) on the API.
CORS_ALLOWED_ORIGINS=http://localhost:5173,https://app.example.com

Jedna fraza się nie tłumaczy (a inne tak)

Fraza w kodzie jest kluczem wyszukiwania — fraza jest kluczem. Jeśli pojedyncza fraza wyświetla się jako tekst źródłowy, a sąsiednie są tłumaczone, tego klucza nie ma w katalogu projektu:

• Nigdy nie została zarejestrowana. Rejestracja odbywa się przez wykrywanie tokenów, a może jej dokonać tylko klucz z uprawnieniami do zapisu. Jeśli fraza powstała, gdy aplikacja działała na kluczu tylko do odczytu, nigdy nie została nigdzie wysłana — uruchom ten ekran raz w trybie deweloperskim z kluczem do zapisu albo dodaj frazę w panelu.
• Tekst się zmienił. Każda edycja — słowo, interpunkcja, nawet biały znak — tworzy nową frazę bez żadnych tłumaczeń. Stare tłumaczenia nadal istnieją pod starym kluczem. Dotyczy to zwłaszcza bloków treści: blok <Translate> jest tokenizowany na podstawie znaczników, więc zmiana tekstu lub struktury bloku zmienia to, co jest wyszukiwane, a blok po cichu wraca do tekstu źródłowego, dopóki nowa postać nie zostanie zarejestrowana i przetłumaczona.
• Tłumaczenie maszynowe jeszcze nie nadążyło. Świeżo zarejestrowana fraza może przez chwilę czekać na swoje tłumaczenia, a język spoza listy docelowej projektu nie otrzyma go w ogóle. Sprawdź frazę w panelu: czy jest zarejestrowana? Czy jest przetłumaczona na ten język?

Dlaczego brakujące frazy nie powodują błędu?

To zamierzone. W środowisku produkcyjnym system tłumaczeń musi w razie problemów wracać do czytelnego tekstu źródłowego, a nie powodować błędów strony — dlatego niezarejestrowana fraza wyświetla się w wersji źródłowej, a SDK milczy. Druga strona medalu: przy kluczu tylko do odczytu brakująca fraza jest cicha. Nic nie jest zapisywane w logach, nic nie jest rejestrowane, a pierwszą informacją o problemie jest użytkownik widzący angielski tekst. Zapobiega temu podział kluczy — pracuj z kluczem do zapisu, aby każda fraza wyświetlana w interfejsie została wykryta, a następnie wdrażaj z kluczem tylko do odczytu.

# Development — write key: new phrases are discovered,
# registered, and machine-translated as you build.
VITE_LANGSYS_API_KEY=write-key

# Production — read-only key: fetches the finished catalog only.
# Unregistered phrases silently render their source text.
VITE_LANGSYS_API_KEY=read-only-key

Mój placeholder wyświetla się dosłownie — „Hi %name%" lub „Hi {name}"

• W wywołaniach t() placeholdery mają pojedyncze nawiasy klamrowe {name}, a interpolacja działa tylko wtedy, gdy przekażesz parametry: t('Hello, {name}!', 'Greetings', { name }).
• W znacznikach <Translate>/<Phrase> w React, Vue lub Svelte zapisuj symbole zastępcze jako %name%. Kompilator frameworka traktuje samo {name} jak wyrażenie, zanim SDK w ogóle je zobaczy; %name% przetrwa kompilację, a SDK przy przechwytywaniu normalizuje je z powrotem do {name}. Zwykłe {name} jest w porządku w czystym HTML, gdzie nie ma składni szablonów, z którą mogłoby kolidować.
• Brakuje parametrów? Jeśli nie przekażesz params, szablon zostanie wyrenderowany bez zmian — to właśnie ten dosłowny %name%, który widzisz.

Działa, a potem przestaje po kilkukrotnym przełączaniu języków tam i z powrotem

Zaktualizuj SDK. Rzeczywiste, naprawione błędy w tym obszarze: powrót do początkowej lokalizacji/SSR pozostawiał aktywny poprzedni katalog (naprawione w langsys-js-typescript 0.2.2), a komponenty korzystające z bloków treści Translate/Phrase mogły zawieszać się w nieskończoność przy katalogu zasianym po stronie serwera (naprawione w 0.2.3). Jeśli widzisz teksty w nieaktualnej lokalizacji lub bloki, które nigdy się nie rozwiązują, sprawdź zainstalowaną wersję w dzienniku zmian bazowego SDK, zanim zaczniesz debugować własny kod.

Po stronie serwera: strona zwraca błąd 500 zamiast działać w trybie ograniczonym

Klient SDK dla PHP zgłasza wyjątek, gdy zostanie utworzony bez poświadczeń — dlatego aplikacja Laravel (lub zwykła aplikacja PHP) z pustym LANGSYS_API_KEY kończy się błędem już podczas rozwiązywania zależności w kontenerze, zanim wykona się jakiekolwiek tłumaczenie. Ustaw poświadczenia (albo, jeśli aplikacja musi się uruchamiać bez nich, zbinduj klienta zastępczego tak, jak robią to aplikacje demonstracyjne). Gdy poświadczenia są ustawione, awarie API w czasie działania są obsługiwane łagodnie: gdy API jest nieosiągalne lub odmawia obsługi, wyświetlany jest tekst źródłowy, a wyjątek jest raportowany — strona nigdy nie przestaje działać.

Po stronie serwera: pierwsze żądanie się zawiesza, a potem wszystko działa szybko

Limit czasu HTTP w SDK dla PHP wynosi 30 sekund, a instancja API wybudzana z bezczynności może się do niego zbliżyć już przy pierwszym wywołaniu. To żądanie albo zakończy się powoli (i rozgrzeje pamięć podręczną katalogu — wszystko po nim jest serwowane z pamięci podręcznej), albo przekroczy limit czasu i wyświetli tekst źródłowy. Jeśli pierwsze wczytanie strony po dłuższej przerwie jest wolne, to jest właśnie powód — to rozgrzewa się API, a nie problem z Twoją integracją.

Po stronie serwera: wyrenderowałem z kluczem zapisu, ale frazy nie ma w panelu

Wykryte frazy trafiają do kolejki w trakcie żądania i są wysyłane po wysłaniu odpowiedzi — to tzw. terminable middleware w Laravelu. Odśwież panel chwilę po załadowaniu strony, a nie w trakcie. W długo działających środowiskach workerów (Octane, FrankenPHP, RoadRunner) upewnij się, że korzystasz z integracji dostarczonej w SDK — zwykły hook zamknięcia PHP nigdy nie uruchamia się między żądaniami workera.

Renderowanie po stronie serwera: tłumaczenia z jednego żądania przenikają do innego

Bazowy pakiet SDK dla JS przechowuje katalog tylko jednego języka naraz — to singleton na poziomie modułu. Serwer Node renderujący różne języki dla równoległych żądań wpadnie w wyścig. Pobieraj katalog dla każdego żądania i na jego podstawie inicjuj klienta, tak jak we wzorcu z przewodników po Next.js, Nuxt i SvelteKit, albo uruchom jeden język na proces.