← Lernen

Fehlerbehebung

Jeder Eintrag hier beschreibt einen Fehlerfall, der tatsächlich schon einmal aufgetreten ist. Zu jedem Eintrag gehören das Symptom, die Ursache und die Lösung – die meisten Fälle lassen sich auf eine von drei Ursachen zurückführen: Die Phrase ist nicht im Projekt enthalten, das SDK wurde nie initialisiert, oder ein Platzhalter wurde für den falschen Kontext geschrieben.

Nichts wird übersetzt – jede Phrase bleibt in der Ausgangssprache

Wenn alles den Quelltext anzeigt, ist die Initialisierung des SDK mit großer Wahrscheinlichkeit fehlgeschlagen. Es schlägt absichtlich unauffällig fehl (Ihre Oberfläche darf nie kaputtgehen), sodass die Browserkonsole das einzige deutliche Signal ist – prüfen Sie sie zuerst. Die üblichen Ursachen, nach Wahrscheinlichkeit geordnet:

1. CORS. Die erste Anfrage des SDK ist authorize-project; wenn Ihre API den Origin der App nicht auf die Allowlist setzt, blockiert der Browser sie, und init bricht genau dort ab. Denken Sie daran: Ein Origin besteht aus Schema + Host + Port – localhost:5173 und localhost:5174 sind verschiedene Origins, und Entwicklungsserver weichen auf andere Ports aus, wenn der gewohnte belegt ist. Setzen Sie jeden Port auf die Allowlist, auf dem Sie tatsächlich entwickeln.
2. Falsche Zugangsdaten. Eine fehlende oder falsch eingegebene Projekt-ID bzw. ein falscher API-Schlüssel lässt denselben Autorisierungsaufruf fehlschlagen. Die Konsole zeigt die fehlgeschlagene Anfrage und die URL.
3. Sie sehen gerade die Basis-Locale. In der Basis-Locale ist die „Übersetzung“ der Quelltext – es ändert sich nichts sichtbar. Wechseln Sie zum Testen zu einer Ziel-Locale.

# 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

Eine Phrase wird nicht übersetzt (andere schon)

Die Phrase in Ihrem Code ist der Suchschlüssel – die Phrase ist der Schlüssel. Wird eine einzelne Phrase als Quelltext angezeigt, während die umliegenden übersetzt werden, befindet sich dieser Schlüssel nicht im Katalog des Projekts:

• Sie wurde nie registriert. Die Registrierung erfolgt über die Token-Erkennung, und nur ein Schreibschlüssel kann sie durchführen. Wurde die Phrase erstellt, während die App mit einem schreibgeschützten Schlüssel lief, wurde sie nie irgendwohin gesendet – rufe den Bildschirm einmal in der Entwicklung mit einem Schreibschlüssel auf oder füge die Phrase im Dashboard hinzu.
• Der Text hat sich geändert. Jede Änderung – ein Wort, ein Satzzeichen, sogar ein Leerzeichen – macht daraus eine neue Phrase ohne Übersetzungen. Die alten Übersetzungen existieren weiterhin unter dem alten Schlüssel. Besonders betroffen sind Inhaltsblöcke: Ein <Translate>-Block wird aus seinem Markup tokenisiert, sodass eine Änderung an Text oder Struktur des Blocks ändert, was nachgeschlagen wird, und der Block stillschweigend auf den Quelltext zurückfällt, bis die neue Form registriert und übersetzt ist.
• Die maschinelle Übersetzung ist noch nicht so weit. Eine frisch registrierte Phrase kann ihren Übersetzungen einen Moment hinterherhinken, und für eine Locale außerhalb der Zielliste des Projekts entsteht gar keine. Prüfen Sie die Phrase im Dashboard: registriert? In diese Locale übersetzt?

Warum lösen fehlende Phrasen keinen Fehler aus?

Das ist Absicht. In der Produktion muss ein Übersetzungssystem auf lesbaren Quelltext zurückfallen, niemals auf eine defekte Seite – daher gibt eine nicht registrierte Phrase ihren Quelltext aus, und das SDK bleibt stumm. Die Kehrseite: Bei einem schreibgeschützten Schlüssel ist eine fehlende Phrase lautlos. Es wird nichts protokolliert, nichts registriert, und man erfährt es erst, wenn ein Nutzer Englisch sieht. Vorbeugen lässt sich das mit der Schlüsselaufteilung: Entwickeln Sie mit einem Schreibschlüssel, damit jede Phrase, die Ihre UI rendert, erkannt wird, und liefern Sie dann schreibgeschützt aus.

# 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

Mein Platzhalter wird wörtlich angezeigt – „Hi %name%“ oder „Hi {name}“

• In t()-Aufrufen sind Platzhalter einfache geschweifte Klammern {name}, und die Interpolation läuft nur, wenn Sie die Parameter übergeben: t('Hello, {name}!', 'Greetings', { name }).
• In <Translate>-/<Phrase>-Markup unter React, Vue oder Svelte schreiben Sie Platzhalter als %name%. Der Framework-Compiler verarbeitet ein einfaches {name} als Ausdruck, bevor das SDK es überhaupt zu sehen bekommt; %name% übersteht die Kompilierung, und das SDK normalisiert es bei der Erfassung wieder zu {name}. Einfaches {name} ist in reinem HTML unproblematisch, da es dort keine Template-Syntax gibt, mit der es kollidieren könnte.
• Parameter fehlen? Wenn keine params übergeben werden, wird die Vorlage unverändert gerendert – das ist der wörtliche Platzhalter %name%, den Sie sehen.

Es funktioniert, geht aber kaputt, nachdem ich mehrmals zwischen Sprachen hin- und hergewechselt habe

Aktualisiere das SDK. Tatsächlich behobene Fehler in diesem Bereich: Die Rückkehr zur Start-/SSR-Locale ließ den vorherigen Katalog aktiv (behoben in langsys-js-typescript 0.2.2), und Verbraucher von Content-Block-Translate/Phrase konnten bei einem serverseitig vorbefüllten Katalog endlos hängen bleiben (behoben in 0.2.3). Wenn du Strings in veralteter Locale oder Blöcke siehst, die nie aufgelöst werden, vergleiche zuerst deine installierte Version mit dem Changelog des Basis-SDK, bevor du deinen eigenen Code debuggst.

Serverseitig: Die Seite liefert einen 500-Fehler, statt eingeschränkt weiterzulaufen

Der Client des PHP-SDK wirft beim Erstellen ohne Zugangsdaten einen Fehler – daher scheitert eine Laravel-App (oder reine PHP-App) mit leerem LANGSYS_API_KEY bereits bei der Container-Auflösung, noch bevor eine Übersetzung läuft. Hinterlege die Zugangsdaten (oder binde bei einer App, die auch ohne sie starten muss, einen Platzhalter-Client ein, wie es die Demo-Apps tun). Sobald Zugangsdaten vorhanden sind, werden Laufzeitfehler der API abgefangen: Ist die API nicht erreichbar oder lehnt sie Anfragen ab, wird der Quelltext angezeigt und die Ausnahme gemeldet – die Seite fällt nie aus.

Serverseitig: Die erste Anfrage hängt, danach ist alles schnell

Das HTTP-Timeout des PHP-SDK beträgt 30 Sekunden, und eine API-Instanz, die gerade aus dem Leerlauf aufwacht, kann bereits beim allerersten Aufruf nahe daran kommen. Diese Anfrage wird entweder langsam abgeschlossen (und wärmt den Katalog-Cache auf – alles Weitere wird aus dem Cache ausgeliefert) oder läuft in ein Timeout und gibt den Quelltext aus. Wenn Ihr erster Seitenaufruf nach einer ruhigen Phase langsam ist, liegt es daran: Die API wärmt sich auf, es liegt nicht an Ihrer Integration.

Serverseitig: Ich habe mit einem Schreibschlüssel gerendert, aber die Phrase erscheint nicht im Dashboard

Erkannte Phrasen werden während der Anfrage in eine Warteschlange gestellt und erst nach dem Absenden der Antwort übermittelt – das ist die Terminable Middleware von Laravel. Aktualisiere das Dashboard einen Moment nach dem Laden der Seite, nicht währenddessen. Stelle bei langlebigen Worker-Laufzeitumgebungen (Octane, FrankenPHP, RoadRunner) sicher, dass du die mitgelieferte Integration des SDK verwendest – der einfache PHP-Shutdown-Hook wird zwischen Worker-Anfragen nie ausgelöst.

Server-Rendering: Übersetzungen einer Anfrage gelangen in eine andere

Das JS-Basis-SDK hält jeweils den Katalog einer einzigen Sprache – es ist ein Singleton auf Modulebene. Ein Node-Server, der für parallele Anfragen unterschiedliche Sprachen rendert, läuft in Race Conditions. Lade den Katalog pro Anfrage und initialisiere den Client damit, wie im Muster der Leitfäden für Next.js, Nuxt und SvelteKit, oder betreibe eine Sprache pro Prozess.