Automatisierung

Die Erweiterung übersetzt Inhalte auf drei Wegen ohne den Assistenten: automatisch nach dem Speichern eines Datensatzes, nach Zeitplan und über die Kommandozeile. Alle drei stellen ihre Arbeit in die Hintergrund-Warteschlange.

Die Modi im Überblick

Modus	Was ihn auslöst	Legt einen Übersetzungsauftrag an	Was übersetzt wird
Beim Speichern übersetzen	Das Speichern eines beobachteten Datensatzes in der Standardsprache des Shops	Nein	Nur die gespeicherten Datensätze, nur die fehlenden Felder
Geplante Übersetzung	Die stündliche geplante Aufgabe, höchstens einmal pro konfiguriertem Intervall	Ja, einen Auftrag je Anbieter	Datensätze mit fehlenden Übersetzungen
Kommandozeile	Sie selbst oder Ihr eigener Cron-Eintrag	Ja	Die Inhaltstypen und der Umfang, die Sie übergeben

Der Flow-Builder-Trigger hat in dieser Tabelle keine Zeile, denn er löst erst nach dem Abschluss eines Auftrags aus. Er startet nie einen Auftrag.

Message-Queue-Worker

Jede Art von Übersetzungsarbeit geht an die Shopware Message Queue, und ein Worker führt sie aus: Läufe des Assistenten, Schnellübersetzungen, Automatisierung, CLI-Aufträge und die Rücknahme ganzer Aufträge. Wenn kein Worker läuft, bleiben die Aufträge im Status Wartend stehen, und die Automatisierung beim Speichern bringt kein Ergebnis.

Die Erweiterung kennzeichnet ihre eigenen Nachrichten als niedrig priorisiert. Ein Worker kann dem Queue-Verkehr des Shopware-Cores deshalb Vorrang vor einer langen Massenübersetzung geben. Mehr als diese Kennzeichnung steuert die Erweiterung nicht bei. Die Trennung und der Durchsatz in der Praxis hängen von Ihrer eigenen Messenger-Konfiguration und Worker-Konfiguration ab.

Die beiden Befehle

Ihr Server braucht einen Worker für die Transports async und low_priority, und dazu den Scheduled-Task-Runner:

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. messenger:consume führt die Übersetzungen aus, und scheduled-task:run treibt die beiden geplanten Aufgaben der Erweiterung an:

Aufgabe	Standardintervall	Was sie tut
nice_translate.auto_translate	1 Stunde	Prüft, ob ein geplanter Übersetzungslauf fällig ist, und löscht die Verlaufseinträge nach Ablauf der Aufbewahrungsdauer
nice_translate.dispatch_batches	1 Minute	Übergibt Queue-Arbeit erneut, deren Zustellung verloren ging, und leitet das Flow-Builder-Event abgeschlossener Aufträge weiter

Die stündliche Aufgabe bereinigt auch den Verlauf. Der Scheduled-Task-Runner ist deshalb auch in einem Shop wichtig, der die geplante Übersetzung nie einschaltet. Der Übersetzungsverlauf beschreibt die Aufbewahrung.

Betrieb unter einem Prozessmanager

--time-limit und --memory-limit beenden jeden Worker in regelmäßigen Abständen, damit sein Speicherbedarf begrenzt bleibt. Danach muss etwas den Worker neu starten. Betreiben Sie beide Befehle unter einem Prozessmanager. Üblich sind systemd und supervisor. Konfigurieren Sie den Prozessmanager so:

• er startet den Befehl nach jedem Beenden erneut, auch nach einem Deployment und nach einem Absturz;
• er führt den Befehl unter demselben Systembenutzer wie Ihren Webserver aus, aus dem Shopware-Wurzelverzeichnis;
• er startet die Worker nach jedem Deployment neu, damit sie den neuen Code laden.

Die Unit-Definition oder die Programmdefinition selbst finden Sie in der Dokumentation Ihres Hosters oder in der Hosting-Dokumentation von Shopware. Nichts daran ist spezifisch für diese Erweiterung.

Achtung

Ein Shop ohne Worker wirkt aus Sicht des Händlers defekt. Die Aufträge verlassen den Status Wartend nie, die Übersetzungen beim Speichern erscheinen nicht, und der geplante Lauf findet nicht statt. Die Fehlerbehebung zeigt, wie Sie den Betrieb der Worker prüfen.

Mehrere Worker parallel betreiben

Mehrere parallele messenger:consume-Prozesse verkürzen große Aufträge, denn die Worker übersetzen die Batches gleichzeitig. Sie vervielfachen aber auch die Last, die im selben Moment beim Übersetzungsanbieter ankommt, und machen Antworten mit Ratenlimit wahrscheinlicher.

Eine Anfrage, die mit einem Ratenlimit oder einem Serverfehler zurückkommt, wiederholt die Erweiterung bis zu dreimal, mit exponentiell wachsendem Abstand. Einen Retry-After-Hinweis des Anbieters beachtet sie bis zu einer Minute. Was danach immer noch scheitert, landet in der Fehlerliste des Auftrags, und dort greifen Sie es mit Fehlgeschlagene erneut ausführen wieder auf. Wenn sich Fehler wegen Ratenlimits häufen, senken Sie zuerst die Zahl der parallelen Worker.

Datenbank-Sessions müssen fest gebunden bleiben

Die Erweiterung serialisiert jeden Batch über einen Advisory Lock von MySQL (GET_LOCK / RELEASE_LOCK). Dieser Lock verhindert eine zweite Übersetzung derselben Datensätze nach einer erneuten Zustellung, und damit eine zweite Abrechnung. Ein Advisory Lock gehört zu einer Datenbank-Session, deshalb muss ein Worker dieselbe Verbindung über den gesamten Handler-Aufruf halten.

Datenbank-Proxys, die Transaktionen poolen oder Sessions multiplexen, sind nicht unterstützt, solange sie die Verbindungsbindung nicht erhalten. Ihr Hosting entscheidet über diese Bindung, und die Erweiterung hat dafür keine Einstellung. Siehe Voraussetzungen.

Der Admin-Worker ist nur für Entwicklungssysteme

Auf einem Entwicklungssystem verarbeitet auch der browserbasierte Admin-Worker von Shopware die Queue, solange die Administration geöffnet ist. Zum Ausprobieren der Erweiterung genügt das. Der Admin-Worker stoppt in dem Moment, in dem jemand den Browser-Tab schließt, und eignet sich deshalb nicht für den Produktivbetrieb. Führen Sie im Produktivbetrieb die beiden Befehle von oben aus.

Beim Speichern übersetzen

Öffnen Sie Kataloge → KI-Übersetzung, klicken Sie auf Einstellungen und gehen Sie auf den Tab Automatisierung. Aktivieren Sie danach Inhalte nach dem Speichern automatisch übersetzen. Von diesem Moment an stellt jedes Speichern eines beobachteten Datensatzes in der Standardsprache des Shops dessen fehlende Übersetzungen im Hintergrund in die Warteschlange.

Einstellung	Wirkung
Inhaltstypen	Die Entitäten, die die Erweiterung beobachtet: Produkte, Kategorien, Hersteller, Erlebniswelten (CMS). Nichts außerhalb dieser Liste löst eine Übersetzung beim Speichern aus.
Zielsprachen	Die Sprachen, in die ein Speichervorgang übersetzt wird. Die Systemstandardsprache ist niemals Zielsprache. Wenn Sie das Feld leer lassen, passiert nichts.
Anbieter	Entweder ein Anbieter für jede Zielsprache oder Sprachzuordnung / Standard verwenden.

Wie die Erweiterung den Anbieter auflöst

Mit ausgewähltem Sprachzuordnung / Standard verwenden löst die Erweiterung jede Zielsprache in dieser Reihenfolge auf:

1. der Anbieter, den Einstellungen → Anbieter → Anbieter je Zielsprache dieser Sprache zuordnet;
2. der Standard-Anbieter aus demselben Tab;
3. DeepL als eingebauter Fallback.

Wenn Sie einen konkreten Anbieter auswählen, übersteuert dieser Anbieter die ganze Kette für jede Zielsprache. Manuelle Übersetzungen bleiben davon unberührt und behalten den Anbieter aus dem Assistenten oder aus dem Dialog für die Schnellübersetzung. Übersetzungsanbieter beschreibt die Zuordnung selbst.

Manchmal kann die Erweiterung für eine Zielsprache keinen Anbieter auflösen, etwa weil jemand den zugeordneten Anbieter entfernt hat. Sie überspringt diese Sprache dann und schreibt das Problem in das Shopware-Log. Der Speichervorgang selbst ist trotzdem erfolgreich.

Was ein Lauf beim Speichern tut

• Der Lauf füllt nur die fehlenden Felder. Die Automatisierung beim Speichern überschreibt nie eine vorhandene Übersetzung, unabhängig von den Voreinstellungen des Assistenten.
• Der Lauf überspringt unveränderte Inhalte und schützt von Hand bearbeitete Übersetzungen, genau wie ein Lauf des Assistenten mit diesen Optionen. Siehe Schutzmechanismen.
• Die Erweiterung ignoriert Löschvorgänge und zählt nur die Schreibvorgänge in der Live-Version des Shops.
• Schleifensicherung: Die Erweiterung kennzeichnet ihre eigenen Schreibvorgänge, deshalb löst eine geschriebene Übersetzung nie einen weiteren Lauf beim Speichern aus.

Wo Sie das Ergebnis sehen

Läufe beim Speichern erscheinen nicht in der Auftragsliste. Sie legen keinen Auftragsdatensatz an, deshalb gibt es unter Aufträge keinen Eintrag, keinen Fortschrittsbalken, keine Schätzung und keine Kostenzeile je Auftrag. Das Dashboard erfasst ihren monatlichen Verbrauch an Zeichen und Tokens trotzdem. Siehe Kosten & Verbrauch.

Die Änderungen selbst sehen Sie Feld für Feld. Bei aktiver Verlaufsaufzeichnung erscheint jedes geänderte Feld im globalen Übersetzungsverlauf, und Sie setzen es dort zurück. Der Link Übersetzungsverlauf öffnen auf der Karte führt direkt dorthin. Siehe Übersetzungsverlauf.

Geplante Übersetzung

Die Option Fehlende Übersetzungen zeitgesteuert ergänzen auf demselben Tab legt in einem festen Intervall Aufträge für unübersetzte Inhalte an. Am meisten profitieren Kataloge, die ein ERP oder ein nächtlicher Import befüllt, denn dort sitzt niemand in der Administration und startet einen Lauf.

Die geplante Aufgabe nice_translate.auto_translate prüft stündlich, ob ein Lauf fällig ist. Das konfigurierte Intervall entscheidet, wie oft ein Lauf tatsächlich fällig wird:

Intervall	Läuft höchstens
Stündlich	einmal pro Stunde
Alle 6 Stunden	einmal alle 6 Stunden
Alle 12 Stunden	einmal alle 12 Stunden
Täglich (empfohlen)	einmal pro Tag
Wöchentlich	einmal pro Woche

Eine Prüfung startet einen Lauf erst, wenn seit dem letzten Lauf das konfigurierte Intervall verstrichen ist. Bei täglichem Intervall ist das ein Lauf auf 24 Prüfungen. Solange der Schalter aus ist, endet jede Prüfung ohne Lauf, unabhängig vom eingestellten Intervall.

Inhaltstypen hat für geplante Läufe eine eigene Einstellung, mit denselben vier Optionen wie beim Speichern. Zielsprachen ist gemeinsam: Die geplante Übersetzung nutzt die Sprachen aus der Karte für die Übersetzung beim Speichern darüber.

Letzte Ausführung zeigt den Zeitpunkt des letzten geplanten Laufs oder Noch nie. Wenn die Erweiterung einen Lauf überspringt, weil ein anderer Auftrag wartet oder läuft, bleibt der Wert unverändert, und die nächste stündliche Prüfung versucht es erneut.

Ein Auftrag je Anbieter

Die Erweiterung gruppiert die Zielsprachen nach ihrem aufgelösten Anbieter, und jede Gruppe wird zu einem eigenen Auftrag. Ein fest gewählter Anbieter ergibt einen einzigen Auftrag. Sprachzuordnung / Standard verwenden ergibt einen Auftrag je Anbieter, auf den eine Zielsprache auflöst. Die Gruppierung hält Prüfungen, Schätzungen, Kosten und Bezeichnungen anbieterbezogen.

Geplante Aufträge tragen im Titel das Präfix Scheduled (<provider>): , deshalb erkennen Sie sie in der Auftragsliste leicht:

Scheduled (DeepL): Products, Categories → Deutsch, Français

Jeder geplante Auftrag nutzt eine feste Konfiguration. Die Erweiterung wählt nur Datensätze mit mindestens einer fehlenden Übersetzung aus. Sie füllt nur die fehlenden Felder, überspringt unveränderte Inhalte und schützt die manuellen Änderungen. Eine interaktive Schätzung erscheint nicht, denn niemand ist da, der sie bestätigen könnte.

Wann die Erweiterung einen Lauf überspringt

Solange irgendein Übersetzungsauftrag wartet oder läuft, tut die geplante Aufgabe nichts und lässt Letzte Ausführung unverändert. Bei der nächsten stündlichen Prüfung versucht sie es erneut. Ein Auftrag, der mangels Worker auf Wartend hängen bleibt, blockiert die geplante Übersetzung deshalb vollständig.

Flow Builder

Wenn ein Auftrag abgeschlossen ist, löst die Erweiterung das Business-Event Übersetzungsauftrag abgeschlossen (nice_translate.job.finished) aus. Im Flow Builder erscheint es als Trigger KI-Übersetzung → Auftrag → Abgeschlossen.

Das Event enthält die Auftrags-ID, den Titel, den Endstatus und die Zähler für verarbeitete, fehlgeschlagene und übersprungene Elemente. Es enthält außerdem die E-Mail-Adresse des Benutzers, der den Auftrag angelegt hat. Die Aktion E-Mail versenden von Shopware adressiert diese Person deshalb ohne weitere Konfiguration.

Der Trigger löst bei jedem abgeschlossenen Auftrag aus, auch bei den geplanten. Die Automatisierung beim Speichern legt keinen Auftrag an und erzeugt deshalb kein Event. Events & Flow Builder dokumentiert die Payload, die verfügbaren Variablen und das Verhalten beim Mailversand.

Automatisierung über die Kommandozeile

bin/console nice-translate:run legt dieselbe Art von Auftrag an wie der Assistent. Es ist das richtige Werkzeug für eigene Cron-Einträge, Deployment-Skripte und einmalige Katalogmigrationen. Der Befehl legt den Auftrag an und kehrt zurück. Die Arbeit erledigen danach die Queue-Worker, genau wie bei einem Auftrag aus der Administration.

CLI-Befehle dokumentiert die Optionen, den Umgang mit Locales, --watch und den Befehl zum Auflisten der Anbieter.