Fehlerbehebung

Jeder Abschnitt beginnt mit einem Symptom, das Sie in der Administration oder auf dem Server sehen. Er nennt danach die Ursache und die Lösung. Wenn Ihr Symptom hier fehlt, lesen Sie die Auftragsdetailseite und das Shopware-Log unter var/log/.

Aufträge bleiben dauerhaft wartend

Symptom. Ein Auftrag steht unter Kataloge → KI-Übersetzung → Aufträge auf Wartend, der Fortschrittsbalken bleibt bei null, und die Erweiterung schreibt nichts.

Ursache. Niemand arbeitet die Message Queue ab. Die gesamte Übersetzungsarbeit läuft über Nachrichten mit niedriger Priorität, und der Auftragsdatensatz hält nur fest, dass jemand den Auftrag angefordert hat.

Lösung. Starten Sie die Worker, die Ihr Shop braucht, unter einem Prozessmanager, damit sie nach einem Neustart wieder hochkommen:

bin/console messenger:consume async low_priority --time-limit=60 --memory-limit=512M

bin/console scheduled-task:run --time-limit=60 --memory-limit=512M

Beide Befehle sind erforderlich. Der Consumer verarbeitet die Übersetzungs-Batches. Der Scheduled-Task-Runner stellt die Startnachrichten und die Batches erneut zu, nachdem ein Worker abgestürzt ist.

Bewegt sich der Auftrag trotz laufender Worker nicht, prüfen Sie den Failure-Transport:

bin/console messenger:failed:show

bin/console messenger:failed:retry

Tipp

Auf einem Entwicklungssystem verarbeitet auch der Browser-Worker der Administration Nachrichten aus der Warteschlange, solange ein Admin-Tab geöffnet ist. Das ist der Grund, warum ein Auftrag auf Ihrem Rechner läuft und in der Produktion stehen bleibt.

Automatisierung beschreibt die vollständige Worker-Einrichtung.

Ein Auftrag wurde mit Fehlern abgeschlossen

Symptom. Der Auftragsstatus lautet Mit Fehlern abgeschlossen, und der Zähler Fehlgeschlagen ist größer als null.

Ursache. Einzelne Datensätze sind fehlgeschlagen, und der Rest des Auftrags war erfolgreich. Jeder Eintrag der Fehlerliste hat die automatischen Wiederholungen für vorübergehende Anbieterprobleme bereits hinter sich.

Lösung. Öffnen Sie den Auftrag und lesen Sie die Tabelle Fehler. Sie führt je Fehlschlag Inhaltstyp, Element, Fehlermeldung und Zeitpunkt auf, bis zu 500 gespeicherte Fehlerzeilen pro Auftrag. Das sind die häufigen Meldungen und ihre Bedeutung:

Was Sie sehen	Was zu tun ist
Der Anbieter meldet ein erschöpftes Kontingent oder einen ungültigen Schlüssel	Den Schlüssel unter Einstellungen → Anbieter aufladen oder ersetzen und testen
Included translation credits are exhausted…	Auf die Verlängerung warten, den Tarif wechseln oder diese Sprache auf einen Anbieter mit eigenem Schlüssel umstellen. Siehe modernice All-in-One
Eine Quell- und eine Zielsprache sind identisch	Die Zuordnung unter Einstellungen → Erweitert → Quellsprachen korrigieren
Der Anbieter hat einen Glossarbegriff verloren	Die Erweiterung erfasst das Feld als fehlgeschlagen und schreibt nichts dafür. Prüfen Sie diesen Glossareintrag. Siehe Glossar
Der Anbieter hat bei der Übersetzung einen Platzhalter verloren	Die Erweiterung sperrt Twig-Variablen, Textbaustein-Platzhalter und URLs vor der Übersetzung. Beschädigt ein Anbieter einen davon, schreibt die Erweiterung nichts für dieses Feld und erfasst einen Fehler
Für ein Locale existiert kein Snippet-Set	Siehe Fehlendes Snippet-Set für eine Zielsprache

Nachdem Sie die Ursache behoben haben, klicken Sie im Auftrag auf Fehlgeschlagene erneut ausführen. Der erneute Anlauf steht nur bei Aufträgen mit dem Status Abgeschlossen oder Mit Fehlern abgeschlossen bereit. Er überspringt außerdem die Datensätze, deren Fehler auf eine teilweise Übersetzung hinweist.

Der Verbindungstest lehnt einen Anbieterschlüssel ab

Symptom. Verbindung testen unter Einstellungen → Anbieter antwortet mit Der Verbindungstest ist fehlgeschlagen. Bitte prüfen Sie den API-Schlüssel und versuchen Sie es erneut.

Ursache. Der Anbieter hat den gespeicherten oder eingegebenen Schlüssel abgelehnt, oder der Schlüssel erreicht den Endpunkt nicht, gegen den die Erweiterung prüft.

Lösung. Arbeiten Sie die Punkte für Ihren Anbieter durch:

• DeepL: Schlüssel der API Free enden auf :fx. Fügen Sie den Schlüssel exakt so ein, wie DeepL ihn ausgestellt hat, denn die Erweiterung wählt anhand dieser Endung den kostenlosen Endpunkt. Ein Schlüssel ohne die Endung geht an den kostenpflichtigen Endpunkt und schlägt fehl.
• Google Translate: Die Prüfung ruft den Sprachen-Endpunkt der Cloud Translation API auf. Aktivieren Sie die Cloud Translation API für das Projekt, und bestätigen Sie, dass jede Schlüsselbeschränkung diese API weiterhin zulässt.
• OpenAI, Anthropic, Gemini, Mistral: Die Prüfung ruft den Modell-Listen-Endpunkt des Anbieters auf. Ein Schlüssel, der keine Modelle auflisten darf, scheitert am Test, selbst wenn die Übersetzung selbst arbeiten würde. Diese Anbieter lehnen außerdem Konten ohne aktive Abrechnung ab.
• Jeder Anbieter: Der Test sendet den Wert, der gerade im Feld steht, gespeichert oder nicht. Ein Schlüssel mit führendem Leerzeichen, Zeilenumbruch oder fehlendem Ende schlägt fehl. Fügen Sie ihn erneut ein und testen Sie noch einmal.
• modernice All-in-One: Hier gibt es keinen Schlüssel zu testen. Das Status-Banner unter Einstellungen → Abonnement zeigt, wo das Problem liegt (die Store-Verbindung, die Berechtigung oder die Erreichbarkeit des Dienstes).

Ein erfolgreicher Test aktualisiert außerdem die Live-Modellliste. Wenn sich das Auswahlfeld Modell nach dem Test füllt, ist das eine zweite Bestätigung für einen funktionierenden Schlüssel.

Ratenlimits und Timeouts

Symptom. Große Läufe enden mit Fehlern zu Ratenlimits, Timeouts oder vorübergehenden Anbieterstörungen.

Ursache. Der Anbieter hat die Anfragen gedrosselt oder mit einem vorübergehenden Serverfehler geantwortet.

Was die Erweiterung bereits tut. Sie wiederholt jede Anbieteranfrage bei HTTP 429, 500, 502, 503 und 529 sowie bei Transportfehlern bis zu dreimal. Der Backoff ist exponentiell, startet bei 500 ms und verdoppelt sich pro Versuch. Einen Retry-After-Header des Anbieters beachtet sie, mit 60 Sekunden als Maximum. Beim Managed-Anbieter wiederholt sie nur 429 und 503. Einen Chunk, der weiterhin fehlschlägt, halbiert sie und wiederholt jede Hälfte. Was dann noch scheitert, landet in der Fehlerliste des Auftrags.

Lösung.

1. Senken Sie die Parallelität: Betreiben Sie weniger parallele messenger:consume-Worker. Jeder zusätzliche Worker vervielfacht die gleichzeitigen Anfragen an den Anbieter.
2. Prüfen Sie die Stufe Ihres Kontos. Neue Konten bei OpenAI und Anthropic starten mit niedrigen Ratenlimits, die mit steigenden Ausgaben wachsen.
3. Übersetzen Sie die fehlgeschlagenen Datensätze später mit Fehlgeschlagene erneut ausführen. Nach einer Drosselungsphase gehen dieselben Inhalte in der Regel durch.

Hinweis

Batch-Größe unter Einstellungen → Erweitert steuert, wie viele Datensätze in einer Warteschlangen-Nachricht stecken. Sie steuert nicht, wie viele Anfragen gleichzeitig laufen. Ein kleinerer Wert macht den Fortschritt feingliedriger. Er senkt die Last beim Anbieter nicht.

Fehlendes Snippet-Set für eine Zielsprache

Symptom. Der Assistent warnt mit Für "{locale}" existiert kein Snippet-Set. Textbausteine können nicht in diese Sprache übersetzt werden. oder Für die Quellsprache "{locale}" existiert kein Snippet-Set — Textbausteine werden übersprungen., und Storefront-Textbausteine tragen nichts zum Lauf bei.

Ursache. Die Erweiterung ermittelt Snippet-Sets über deren ISO-Code und legt selbst keines an. Ohne Set für das Quell-Locale hat sie nichts zum Lesen. Ohne Set für das Ziel-Locale hat sie kein Ziel zum Schreiben.

Lösung. Legen Sie in der Textbaustein-Verwaltung von Shopware ein Snippet-Set an, dessen ISO-Code dem Locale der Sprache entspricht. Starten Sie die Übersetzung danach erneut. Haben mehrere Sets denselben ISO-Code, wählt die Erweiterung immer das älteste, nach Anlagedatum und danach nach ID.

Die Erweiterung kann ein Locale dem gewählten Anbieter nicht zuordnen

Symptom. Der Assistent warnt mit Die Sprache "{locale}" kann für {provider} nicht zugeordnet werden., oder ein CLI-Lauf bricht mit The locale "…" is not supported by …. ab.

Ursache. DeepL und Google Translate erwarten ihre eigenen Sprachcodes. Die Erweiterung bildet die Shopware-Locales darauf ab, darunter pt-PT und pt-BR, vereinfachtes und traditionelles Chinesisch sowie Norwegisch Bokmål. Hat sie für ein Locale keine Zuordnung, lehnt sie es ab.

Lösung. Weisen Sie dieser Sprache unter Einstellungen → Anbieter → Anbieter je Zielsprache einen anderen Anbieter zu, oder nutzen Sie modernice All-in-One dafür. Die LLM-Anbieter und modernice All-in-One erhalten die Sprache als englischen Anzeigenamen, deshalb begrenzt die Codezuordnung bei ihnen nicht, welche Sprachen sie annehmen.

Zwei verwandte Warnungen kommen aus derselben Prüfung:

• Google Translate unterscheidet nicht zwischen britischem und amerikanischem Englisch — beide Varianten werden als generisches Englisch übersetzt. Nutzen Sie einen anderen Anbieter, wenn Sie en-GB und en-US getrennt pflegen.
• Quell- und Zielsprache sind für "{language}" identisch — diese Einträge werden fehlschlagen. Legen Sie die richtige Quelle für dieses Ziel unter Einstellungen → Erweitert → Quellsprachen fest. Alternativ wählen Sie im Assistenten eine Ausgangssprache aus.

Die Erweiterung überschreibt die Übersetzungen nicht

Symptom. Ein Lauf meldet viele Übersprungen, und die vorhandenen Übersetzungen bleiben unverändert.

Ursache. Eine von drei Schutzstufen hat die Felder übersprungen. Die Erweiterung wertet sie für jedes Feld in dieser Reihenfolge aus:

1. Übersetzungsmodus steht auf Nur fehlende Übersetzungen ergänzen (empfohlen), und das Feld hat in dieser Sprache bereits eine Übersetzung.
2. Unveränderte Inhalte überspringen ist aktiv, und der Quelltext hat sich seit der letzten Übersetzung dieses Feldes nicht geändert.
3. Manuelle Änderungen schützen ist aktiv, und die aktuelle Übersetzung entspricht nicht mehr dem letzten Wert der Erweiterung. Ein Mensch hat diese Übersetzung bearbeitet.

Woran Sie die Schutzstufe erkennen. Nur der Schutz manueller Änderungen hinterlässt eine Spur. Er schreibt NiceTranslate: skipping manually edited translation. mit dem betroffenen Feldschlüssel auf Log-Level info in das Shopware-Log. Die Übersprünge aus dem Modus „nur fehlende“ und aus dem Überspringen unveränderter Inhalte protokolliert die Erweiterung nicht. Steht die Meldung im Log, schützt die Erweiterung gerade eine Handbearbeitung. Fehlt sie, hatte das Feld bereits eine Übersetzung (Modus „nur fehlende“) oder sein Quelltext ist unverändert. Der Verlauf bietet eine zweite Prüfmöglichkeit: Vergleichen Sie den letzten Wert der Erweiterung mit dem Wert, den diese Sprache aktuell enthält. Weichen die beiden Werte ab, hat jemand die Übersetzung von Hand bearbeitet.

Wie Sie die Schutzstufen übergehen. Im Assistentenschritt Anbieter & Optionen:

• Setzen Sie Übersetzungsmodus auf Alle Felder neu übersetzen, um auch die Felder mit vorhandener Übersetzung zu schreiben.
• Schalten Sie Unveränderte Inhalte überspringen aus, um auch unveränderten Quelltext neu zu übersetzen.
• Schalten Sie Manuelle Änderungen schützen aus, um auch von Hand bearbeitete Übersetzungen zu überschreiben.

Der Assistent zeigt zu dieser Abwägung einen Hinweis: „Alle Felder neu übersetzen“ überschreibt vorhandene Übersetzungen in den Zielsprachen. Manuell bearbeitete Übersetzungen bleiben unangetastet, solange „Manuelle Änderungen schützen“ aktiviert ist.

Achtung

Die Automatisierung beim Speichern und nach Zeitplan nutzt immer den Modus „nur fehlende“, das Überspringen unveränderter Inhalte und den Schutz manueller Änderungen. Sie kann eine vorhandene oder von Hand bearbeitete Übersetzung nie überschreiben.

Bestätigen Sie vor einem solchen Lauf, dass die Verlaufsaufzeichnung eingeschaltet ist. Sie nehmen den Lauf danach über den Übersetzungsverlauf zurück.

Die geplante Übersetzung startet nie

Symptom. Geplante Übersetzung ist aktiv, aber es erscheinen keine Aufträge mit dem Titel Scheduled (…): ….

Ursache und Lösung, in der Reihenfolge, in der sich das Prüfen lohnt:

1. Der Scheduled-Task-Runner läuft nicht. Die Aufgabe nice_translate.auto_translate prüft stündlich, ob ein Lauf fällig ist. Ohne bin/console scheduled-task:run findet diese Prüfung nie statt, und auch die Verlaufsbereinigung bleibt aus.
2. Das Intervall ist noch nicht abgelaufen. Ein Lauf startet höchstens einmal pro konfiguriertem Intervall. Vergleichen Sie Letzte Ausführung unter Einstellungen → Automatisierung mit dem gewählten Intervall, bevor Sie einen Fehler annehmen.
3. Ein anderer Auftrag ist wartend oder in Bearbeitung. Solange ein Übersetzungsauftrag Wartend oder In Bearbeitung ist, überspringt die Aufgabe stillschweigend und erfasst keinen Lauf. Sie versucht es bei der nächsten stündlichen Prüfung erneut. Ein Auftrag, der in Wartend feststeckt, blockiert den Zeitplan deshalb dauerhaft. Beheben Sie das zuerst.
4. Die Inhaltstypen oder die Zielsprachen sind leer. Geplante Läufe nutzen die Inhaltstypen aus der Karte Geplante Übersetzung. Sie nutzen die Zielsprachen aus der Karte Beim Speichern übersetzen darüber. Ist eine dieser Listen leer, erfasst die Aufgabe den Lauf und legt nichts an. Letzte Ausführung rückt danach vor, während die Erweiterung nichts übersetzt.

Die Erweiterung übersetzt die Inhalte von CMS-Elementen nicht

Symptom. Eine Erlebniswelt ist Teil des Laufs, aber der Text in einzelnen Elementen bleibt in der Ausgangssprache.

Ursache. Die Erweiterung durchläuft die Slot-Konfiguration von CMS-Seiten generisch, anhand von Schlüsselnamen und Werteform, ohne die einzelnen Elementtypen zu kennen. Genau das lässt Drittanbieter-Elemente überhaupt funktionieren, und genau dort liegen auch die Grenzen:

• Die Erweiterung übersetzt nur die Konfigurationseinträge mit statischer Quelle. Ein Wert, den ein Slot aus einem anderen Datensatz bezieht, gehört zu diesem Datensatz. Übersetzen Sie deshalb das Produkt oder die Kategorie dahinter.
• Die Erweiterung berücksichtigt einen Wert, wenn sein Schlüssel zu den erkannten Textschlüsseln gehört (content, text, title, subTitle, subtitle, description, label, buttonText, linkText, altText, placeholder, tagline, quote, author), oder wenn der Wert selbst HTML-Markup enthält.
• Diese Schlüssel lässt die Erweiterung immer unverändert: url, media, mediaId, mediaUrl, color, backgroundColor, cssClass, class, elementId, icon, iconName, videoId, navigationId, categoryId, productId, productStreamId, code.
• Die Erweiterung überspringt die Werte, die eine URL, eine 32-stellige hexadezimale ID oder eine Zahl sind, und die Werte, die mit # beginnen. Sie überspringt außerdem die kurzen CSS-artigen Werte unter cssClass, class, verticalAlign, displayMode und boxLayout.
• Die gesperrten Systemlayouts von Shopware schließt die Erweiterung aus dem Lauf und aus der Eintragszahl des Assistenten aus. Die Abdeckungsmatrix im Dashboard ist die Ausnahme: Ihr Wert Gesamt zählt jede Zeile in cms_page in der Live-Version, deshalb enthält sie die gesperrten Layouts.

Lösung. Ein eigenes Element, das seinen Text unter einem Schlüssel außerhalb dieser Liste speichert, erkennt die Erweiterung nicht, und keine Konfiguration pro Element ändert das. Verlagern Sie den Text in ein erkanntes Element, oder pflegen Sie die Übersetzung dieses Elements von Hand. Testen Sie ungewöhnliche Elemente vor einem Massenlauf in einem Staging-Shop. Über den Übersetzungsverlauf nehmen Sie die Änderungen bei Bedarf zurück.

Der Verlauf ist leer

Symptom. Kataloge → KI-Übersetzung → Verlauf zeigt Übersetzte Felder erscheinen hier, sobald eine Übersetzung mit aktivierter Verlaufsaufzeichnung ausgeführt wurde., obwohl die Erweiterung Übersetzungen geschrieben hat.

Ursache und Lösung:

• Die Aufzeichnung ist aus. Schalten Sie Übersetzungsverlauf aufzeichnen unter Einstellungen → Erweitert → Übersetzungsverlauf ein. Die Erweiterung schreibt den Verlauf nur für die Läufe, die bei aktiver Aufzeichnung stattfinden. Nachträglich kann sie ihn nicht rekonstruieren.
• Die Aufbewahrungsdauer ist abgelaufen. Einträge, die älter sind als die Aufbewahrungsdauer (Tage) (Standard 30), löscht die Erweiterung automatisch, auch bei ausgeschalteter Aufzeichnung. Erhöhen Sie den Wert, wenn Sie ein längeres Zeitfenster zum Zurücknehmen brauchen.
• Die Erweiterung hat nichts geschrieben. Nur die Felder, die die Erweiterung geändert hat, erzeugen einen Eintrag. Ein Lauf, der jedes Feld übersprungen hat, erfasst nichts.

Zwei Details gehen leicht unter. Die Bereinigung läuft bei jedem stündlichen Durchlauf der Aufgabe nice_translate.auto_translate, mit eingeschalteter oder ausgeschalteter geplanter Übersetzung. Bei gestopptem Scheduled-Task-Runner löscht die Erweiterung deshalb auch nichts. Und die Automatisierung beim Speichern schreibt Verlaufseinträge ohne Auftrag, deshalb erscheinen diese Zeilen im globalen Verlauf, aber nie auf einer Auftragsdetailseite.

Queue-Worker hinter einem Datenbank-Proxy mit Connection Pooling

Symptom. Nach einer erneuten Zustellung oder einem Worker-Absturz scheinen Batches doppelt zu laufen, oder die Zähler des Auftrags ergeben keine schlüssige Summe.

Ursache. Die Erweiterung serialisiert die doppelten Zustellungen desselben Batches über einen Advisory Lock von MySQL oder MariaDB (GET_LOCK / RELEASE_LOCK). Dieser Lock gehört zu einer Datenbank-Session und muss für den gesamten Handler-Aufruf auf derselben Session bleiben. Ein Proxy, der auf Transaktionsebene poolt oder Sessions multiplext, kann Lock und Arbeit auf unterschiedliche Sessions verteilen, und damit wird der Schutz wirkungslos.

Lösung. Richten Sie die Worker-Prozesse direkt auf MySQL oder MariaDB aus, oder konfigurieren Sie den Proxy so, dass er für diese Verbindungen die Session-Bindung erhält (Session-Level Pinning). Datenbank-Proxys ohne Session-Bindung sind für Queue-Worker keine unterstützte Konfiguration.