CLI-Befehle

Die Erweiterung registriert zwei Shopware-Konsolenbefehle. nice-translate:run legt einen Übersetzungsauftrag aus der Shell an, und nice-translate:providers zeigt, welche Anbieter Sie konfiguriert haben.

Beide Befehle stehen bereit, sobald Shopware die Erweiterung installiert und aktiviert hat. Starten Sie sie im Wurzelverzeichnis des Shopware-Projekts, wie jeden anderen bin/console-Befehl.

nice-translate:run

Legt einen Übersetzungsauftrag an und verfolgt auf Wunsch dessen Fortschritt.

bin/console nice-translate:run --to=de-DE

Der Befehl baut dieselbe Auftragskonfiguration auf wie der Übersetzungsassistent und übergibt sie an die Message Queue. Er übersetzt selbst nichts.

Optionen

Option	Beschreibung	Wiederholbar	Standard
--entity	Die zu übersetzende Entität, zum Beispiel product, category, snippet	Ja	product
--to	Das Ziel-Locale, zum Beispiel de-DE, oder all für jede Sprache außer der Systemsprache	Ja	erforderlich, kein Standard
--from	Das Quell-Locale	Nein	die Systemsprache
--provider	deepl, google, openai, anthropic, gemini, mistral oder managed	Nein	die Einstellung Standard-Anbieter, sonst deepl
--mode	missing füllt nur die leeren Felder, all überschreibt die vorhandenen Übersetzungen	Nein	missing
--scope	all verarbeitet jeden Datensatz, missing verarbeitet nur die Datensätze mit mindestens einem berücksichtigten fehlenden Zielfeld	Nein	all
--watch, -w	Fragt den Auftrag ab und zeigt einen Fortschrittsbalken, bis er beendet ist	Nein (Flag)	aus

Geben Sie --entity und --to einmal pro Wert an: --entity=product --entity=category --to=de-DE --to=fr-FR. Unterstützte Inhalte nennt die technischen Entitätsnamen, die --entity akzeptiert.

Der Umfang wählt Datensätze aus, und der Modus wählt Felder aus. --scope entscheidet, welche Datensätze in den Auftrag kommen. --mode entscheidet, ob der Lauf ein bereits übersetztes Feld dieser Datensätze erneut schreibt.

Validierung und Fehlermeldungen

Der Befehl bricht in diesen Fällen ab, bevor er einen Auftrag anlegt:

Situation	Meldung
Sie haben kein --to angegeben	Provide at least one target locale, e.g. --to=de-DE (repeatable), or --to=all.
--mode ist weder missing noch all	Invalid --mode "…". Use "missing" or "all".
--scope ist weder all noch missing	Invalid --scope "…". Use "all" or "missing".
--from passt zu keiner Sprache	No language found for source locale "…".
Ein --to-Locale passt zu keiner Sprache	No language found for locale(s): …
Die angeforderten Ziele entsprechen der Quellsprache	No target languages resolved — the requested locales only match the source language.
--entity ist kein unterstützter Inhaltstyp	The entity "…" is not supported for translation.
Der Anbieter hat weder Schlüssel noch aktives Abonnement	… is not configured. Add an API key in the settings first.
DeepL oder Google kann ein Locale des Laufs nicht zuordnen	The locale "…" is not supported by ….

--to=all löst zu jeder Sprache des Shops außer der Systemsprache auf. Die ermittelte Ausgangssprache fällt immer aus der Zielmenge heraus, deshalb versucht --from=en-GB --to=all nie, britisches Englisch in sich selbst zu übersetzen.

Optionen, die der Befehl nicht anbietet

--mode ist die einzige Auftragsoption, die der Befehl setzt. Alles Übrige behält die Auftragsstandards, und diese ergeben sich aus Ihren Einstellungen:

Verhalten	Wert bei einem CLI-Auftrag
Manuelle Änderungen schützen	ein
Unveränderte Inhalte überspringen	ein
Zusatzfelder einbeziehen	ein
Glossar anwenden	ein, zusätzlich abhängig von Glossar anwenden unter Einstellungen → Erweitert
SEO-Felder kürzen	ein
Tonalität und eigene Anweisungen	die Werte aus Einstellungen → Anbieter
Feldauswahl	keine: jedes übersetzbare Feld des Inhaltstyps, abzüglich der Ausgeschlossenen Felder
Servicestufe (Managed-Anbieter)	Ausgewogen (3 Guthabenpunkte pro Quellzeichen)

Wenn Sie eine andere Servicestufe oder einen Lauf ohne Schutz manueller Änderungen brauchen, starten Sie den Auftrag im Assistenten. Einzelne Felder wählen Sie auch im Assistenten nicht aus. Nutzen Sie dafür options.fields am Auftrags-Endpunkt der Admin-API.

Die Kostenschätzungen gibt es nur im Assistenten. Ein CLI-Auftrag bekommt keine.

Wie der Befehl mit der Warteschlange zusammenspielt

Der Befehl schreibt einen Auftragsdatensatz im Status Wartend und übergibt eine Startnachricht an den Transport von Shopware mit niedriger Priorität. Die eigentliche Übersetzung erledigen die Queue-Worker:

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

Der Befehl gibt die ID des neuen Auftrags und einen Hinweis aus:

The job is processed by the message queue. Make sure workers are running (bin/console messenger:consume).

Daraus folgen zwei Dinge:

• Ohne laufende Worker bleibt der Auftrag dauerhaft Wartend, und --watch kehrt nie zurück. Siehe Fehlerbehebung.
• Wenn der Befehl die Startnachricht nicht übergeben kann, ist er trotzdem erfolgreich und gibt die Auftrags-ID aus. Der festgeschriebene Datensatz im Status Wartend ist eine dauerhafte Startmarkierung. Die Wiederherstellungsaufgabe der Erweiterung übergibt die Nachricht bei einem späteren Durchlauf erneut, sofern scheduled-task:run läuft.

--watch

Mit --watch fragt der Befehl den Auftragsdatensatz alle zwei Sekunden ab und aktualisiert einen Fortschrittsbalken. Nachdem der Auftrag einen Endstatus erreicht hat, gibt der Befehl eine Übersichtstabelle mit den Spalten Status, Processed, Failed, Skipped, Total, Characters und Cost aus:

 ----------- ----------- -------- --------- ------- ------------ -------------
  Status      Processed   Failed   Skipped   Total   Characters   Cost
 ----------- ----------- -------- --------- ------- ------------ -------------
  completed   1240        0        86        1326    412903       10.3226 USD
 ----------- ----------- -------- --------- ------- ------------ -------------

Hat der Auftrag eine Fehlermeldung erfasst, gibt der Befehl sie als Warnung unter der Tabelle aus.

Exit-Codes: Der Befehl liefert nur dann einen Fehler-Exit-Code, wenn der Endstatus failed lautet. Ein Auftrag, der als completed_with_errors oder cancelled endet, wird erfolgreich beendet. Ein Build-Schritt, der auf einzelne fehlgeschlagene Datensätze reagieren muss, wertet deshalb den Auftrag selbst aus. --watch hat kein Timeout. Es wartet, bis der Auftrag beendet ist oder bis der Auftragsdatensatz verschwindet (The translation job no longer exists., Fehler-Exit-Code).

Beispiele

Die fehlenden deutschen und französischen Übersetzungen für Produkte und Kategorien mit DeepL ergänzen und den Fortschritt live verfolgen:

bin/console nice-translate:run --entity=product --entity=category --to=de-DE --to=fr-FR --provider=deepl --watch

Ein nächtlicher Nachlauf für alles, was noch unübersetzt ist, in jede Sprache außer der Systemsprache, mit dem konfigurierten Standard-Anbieter. --scope=missing hält den Auftrag klein, denn der Lauf überspringt die bereits vollständigen Datensätze:

bin/console nice-translate:run --to=all --scope=missing

Alle Produkttexte mit Anthropic Claude von britischem Englisch nach Deutsch neu übersetzen und die vorhandenen deutschen Werte überschreiben. Die von Hand bearbeiteten Übersetzungen bleiben erhalten, denn der Schutz manueller Änderungen bleibt aktiv:

bin/console nice-translate:run --entity=product --from=en-GB --to=de-DE --provider=anthropic --mode=all

Storefront-Textbausteine über modernice All-in-One ins Niederländische übersetzen. Für das Quell-Locale und für das Ziel-Locale muss ein Snippet-Set vorhanden sein, sonst überspringt die Erweiterung die Textbausteine:

bin/console nice-translate:run --entity=snippet --to=nl-NL --provider=managed

In einem Deployment-Skript einen Nachlauf für importierte Kategorien starten und den Schritt fehlschlagen lassen, wenn der Auftrag fehlschlägt:

bin/console nice-translate:run --entity=category --to=all --scope=missing --watch

nice-translate:providers

Listet die Übersetzungsanbieter und ihren Konfigurationsstatus auf.

bin/console nice-translate:providers

Die einfache Ausgabe ist eine Tabelle mit einer Zeile je registriertem Anbieter, in der Reihenfolge der Registrierung:

Spalte	Inhalt
ID	Die Anbieter-ID, die Sie an --provider übergeben
Provider	Die Anbieterbezeichnung, die die Administration anzeigt
Configured	yes, sobald ein API-Schlüssel hinterlegt ist; bei managed bedeutet yes, dass das Abonnement aktiv ist

 ----------- ---------------------- ------------
  ID          Provider               Configured
 ----------- ---------------------- ------------
  deepl       DeepL                  yes
  google      Google Translate       no
  openai      OpenAI (ChatGPT)       no
  anthropic   Anthropic Claude       yes
  gemini      Google Gemini          no
  mistral     Mistral                no
  managed     modernice All-in-One   no
 ----------- ---------------------- ------------

Die Ausgabe enthält auch die eigenen Anbieter, die ein anderes Plugin registriert. Siehe Eigene Anbieter.

--test

bin/console nice-translate:providers --test

--test prüft die gespeicherten Zugangsdaten gegen die Anbieter-APIs und ergänzt zwei Spalten:

Spalte	Werte
Credentials	valid oder invalid, jeweils mit — und der Meldung des Anbieters, sofern vorhanden; skipped (not configured) für die Anbieter ohne Schlüssel; error — <message>, wenn die Prüfung selbst fehlgeschlagen ist
Quota	<used> / <limit>, oder <used> / unlimited, wenn der Anbieter kein Limit meldet, oder -, wenn der Anbieter kein Kontingent ausweist

Nur DeepL und modernice All-in-One melden ein Kontingent. DeepL liefert die verbrauchten Zeichen und das Zeichenlimit des Schlüssels. Der Managed-Anbieter liefert die verbrauchten und die enthaltenen Guthabenpunkte. Google Translate, OpenAI, Anthropic, Gemini und Mistral prüft die Erweiterung gegen ihre Modell- oder Sprachlisten-Endpunkte, und diese Endpunkte melden kein Kontingent.

Der Befehl prüft die bereits gespeicherten Schlüssel. Die Schaltfläche Verbindung testen unter Einstellungen → Anbieter prüft den Schlüssel, der gerade im Feld steht, gespeichert oder nicht.

Berechtigungen und Ausführungskontext

Konsolenbefehle laufen außerhalb der Administration, im System-Kontext von Shopware. Die Rollen nice_translate.viewer und nice_translate.editor aus Berechtigungen (ACL) gelten für die Administration und die Admin-API. Die CLI schränken sie nicht ein. Jede Person mit Shell-Zugriff auf den Shop kann Übersetzungsaufträge anlegen.

Achtung

Ein CLI-Auftrag hat keinen Administrations-Benutzer als Ersteller. Der Flow-Builder-Trigger Übersetzungsauftrag abgeschlossen enthält für solche Aufträge deshalb keinen Mail-Empfänger. Eine E-Mail versenden-Aktion muss dann einen festen Empfänger adressieren statt des Auftragserstellers. Siehe Events & Flow Builder.

Aufträge von der Kommandozeile erscheinen unter Kataloge → KI-Übersetzung → Aufträge wie jeder andere Auftrag. Sie haben denselben Fortschritt, dieselbe Fehlerliste und dieselben Aktionen Fehlgeschlagene erneut ausführen und Alle Übersetzungen rückgängig machen.