Systemanforderungen
- Shopware 6.4+
- PHP 8.0+
- MySQL/MariaDB 10.3+
- 500 MB freier Festplattenspeicher für Backups
- Netzwerkzugriff auf api-free.deepl.com
Installationsschritte
- Plugin installieren
bin/console plugin:refresh
bin/console plugin:install --activate TopdataMachineTranslationsSW6
- DeepL API-Key konfigurieren
Dauerhafte Konfiguration (empfohlen):
# Zur Umgebungskonfiguration hinzufügen (z.B. .env)
DEEPL_FREE_API_KEY=Ihr-API-Key-hier
Temporäre Verwendung:
DEEPL_FREE_API_KEY=Ihr-Key-hier bin/console topdata:translate [...]
- Installation überprüfen
bin/console topdata:translate --list-languages
Nach der Installation
- Backup-Verzeichnis:
/tmp/database-backups(über Plugin-Einstellungen konfigurierbar) - Empfehlung für Erstinstallation:
--table-Option zum Testen einzelner Tabellen verwenden
Umgebungsvariablen
DEEPL_FREE_API_KEY
- Erforderlich: Ja
- Beschreibung: DeepL API-Authentifizierungsschlüssel
- Format: Zeichenkette
- Beispiel:
export DEEPL_FREE_API_KEY=Ihr-Key-hier
Befehlsoptionen
--table
- Typ: Mehrfachangaben möglich
- Beschreibung: Spezifische zu übersetzende Tabellen
- Beispiel:
--table=product_translation --table=category_translation
--from
- Standard:
de-DE - Beschreibung: Quellsprache (4-stelliger Code)
- Unterstützte Formate:
xx-XXoderxx
--to
- Standard:
cs-CZ - Beschreibung: Zielsprache (4-stelliger Code)
- Hinweis: Wird automatisch in 2-stelliges Format für DeepL API konvertiert
--no-backup
- Typ: Flag
- Beschreibung: Deaktiviert automatische Backups
- Risiko: In Produktivumgebungen nicht empfohlen
Backup-Einstellungen
- Speicherort:
/tmp/database-backups - Aufbewahrung: Manuelle Bereinigung erforderlich
- Format: SQL-Dump pro Tabelle mit Zeitstempel
Übersetzungseinstellungen
- Ausgenommene Spalten:
- Felder mit Endung
_idoder_config created_at/updated_atZeitstempel
- Felder mit Endung
- Batch-Größe: Einzelne Zeilenverarbeitung
- Fehlerbehandlung: Überspringt fehlgeschlagene Übersetzungen, setzt mit nächster Spalte fort
Konfigurations-XML Übersetzungsbefehl
Der Befehl topdata:machine-translations:translate-config-xml übersetzt Konfigurations-XML-Dateien mit dem DeepL-Übersetzungsdienst. Dieser Befehl wurde entwickelt, um bestimmte Textelemente in Shopware 6 Konfigurations-XML-Dateien automatisch in verschiedene Zielsprachen zu übersetzen.
Zweck
Dieser Befehl verarbeitet Shopware 6 Konfigurations-XML-Dateien und übersetzt übersetzbare Textelemente in die angegebenen Zielsprachen. Er unterstützt die Übersetzung von:
<title>Elementen<label>Elementen<helpText>Elementen<resetOption>Elementen
Voraussetzungen
Bevor Sie diesen Befehl verwenden, stellen Sie sicher:
- DeepL API-Schlüssel ist als
DEEPL_FREE_API_KEYUmgebungsvariable konfiguriert - Die XML-Datei existiert und ist gültig
- Quell- und Zielsprachcodes sind korrekt formatiert (z.B.
de-DE,cs-CZ,en-GB)
Verwendung
bin/console topdata:machine-translations:translate-config-xml <datei> --from=<quelle> --to=<ziel1> [--to=<ziel2> ...] [optionen]
Argumente
| Argument | Erforderlich | Beschreibung |
|---|---|---|
file | Ja | Pfad zur zu übersetzenden XML-Datei |
Optionen
| Option | Kurzform | Erforderlich | Beschreibung |
|---|---|---|---|
--from | -f | Ja | Quellsprachcode (z.B. de-DE) |
--to | -t | Ja | Zielsprachcode(n). Kann mehrfach angegeben werden (z.B. --to=cs-CZ --to=sk-SK) |
--force | - | Nein | Übersetzung erzwingen, auch wenn Übersetzung bereits existiert |
--no-backup | - | Nein | Keine Sicherungskopie der Originaldatei erstellen |
Beispiele
Grundlegende Übersetzung
Eine deutsche Konfigurationsdatei ins Tschechische übersetzen:
bin/console topdata:machine-translations:translate-config-xml config.xml --from=de-DE --to=cs-CZ
Mehrere Zielsprachen
Auf einmal in mehrere Sprachen übersetzen:
bin/console topdata:machine-translations:translate-config-xml config.xml --from=de-DE --to=cs-CZ --to=sk-SK --to=en-GB
Bestehende Übersetzungen überschreiben
Bestehende Übersetzungen für angegebene Sprachen überschreiben:
bin/console topdata:machine-translations:translate-config-xml config.xml --from=de-DE --to=cs-CZ --force
Ohne Sicherungskopie
Ohne Erstellung einer Sicherungsdatei übersetzen:
bin/console topdata:machine-translations:translate-config-xml config.xml --from=de-DE --to=cs-CZ --no-backup
Verhaltensdetails
Sicherungskopie-Erstellung
Standardmäßig erstellt der Befehl eine Sicherungskopie der Originaldatei vor Änderungen. Die Sicherungsdatei folgt dem Muster:
<dateiname>.backup.JJJJ-MM-TT_HH-MM-SS
Übersetzungslogik
- Quelltext-Erkennung: Der Befehl sucht zuerst nach untergeordneten
<text>Elementen mit der angegebenen Quellsprache (--from). Falls keine gefunden werden, wird der Textinhalt des übergeordneten Elements verwendet. - Bestehende Übersetzungsprüfung: Vor der Übersetzung wird geprüft, ob bereits eine Übersetzung für die Zielsprache existiert. Bestehende Übersetzungen werden übersprungen.
Snippet-JSON Übersetzungsbefehl
Der Befehl topdata:machine-translations:translate-snippets-json übersetzt Shopware-Plugin-Snippet-JSON-Dateien (src/Resources/snippet/*.json) mit DeepL. Er unterstützt die Verarbeitung eines einzelnen Plugins oder aller Plugins in einem Plugin-Root-Verzeichnis.
Zweck
Mit diesem Befehl können Locale-Dateien aus einer Quell-Locale erstellt oder aktualisiert werden, wobei die Snippet-Struktur und bestehende Übersetzungen (ohne --force) erhalten bleiben.
Voraussetzungen
- DeepL API-Schlüssel ist als
DEEPL_FREE_API_KEYgesetzt - Quell-Snippet-Datei existiert, z.B.
de-DE.json - Plugin-Snippet-Pfad folgt
src/Resources/snippet/
Verwendung
bin/console topdata:machine-translations:translate-snippets-json [--plugin=<name> ...|--all-plugins] --from=<quell-locale> --to=<ziel-locale> [--to=<ziel-locale> ...] [optionen]
Optionen
| Option | Kurzform | Erforderlich | Beschreibung |
|---|---|---|---|
--plugin | -p | Ja* | Technischer Plugin-Name. Wiederholbar, kommagetrennte Werte werden unterstützt |
--all-plugins | - | Ja* | Alle Plugin-Verzeichnisse in --plugins-root verarbeiten |
--plugins-root | - | Nein | Root-Verzeichnis mit Plugins (Standard: /www/custom/plugins) |
--from | -f | Ja | Quell-Locale-Datei ohne Endung, z.B. de-DE |
--to | -t | Ja | Ziel-Locale(s), mehrfach möglich |
--force | - | Nein | Bestehende, nicht-leere Zielübersetzungen überschreiben |
--dry-run | - | Nein | Verarbeitung nur anzeigen, keine Dateien schreiben |
--no-backup | - | Nein | Sicherung für bestehende Zieldateien überspringen |
--skip-empty | - | Nein | Leere Quell-Strings nicht übersetzen |
* Genau ein Auswahlmodus ist erforderlich: --plugin oder --all-plugins.
Beispiele
Ein Plugin übersetzen
bin/console topdata:machine-translations:translate-snippets-json --plugin=SwagBasicExample --from=de-DE --to=en-GB
Ein Plugin in mehrere Locales übersetzen
bin/console topdata:machine-translations:translate-snippets-json --plugin=SwagBasicExample --from=de-DE --to=en-GB --to=cs-CZ
Dry-Run über alle Plugins
bin/console topdata:machine-translations:translate-snippets-json --all-plugins --from=de-DE --to=en-GB --dry-run
Bestehende Werte überschreiben
bin/console topdata:machine-translations:translate-snippets-json --plugin=MyPlugin --from=de-DE --to=en-GB --force
Verhaltensdetails
- Quelldatei:
<plugin>/src/Resources/snippet/<from>.json - Zieldateien:
<plugin>/src/Resources/snippet/<to>.json - Bestehende, nicht-leere Zielwerte bleiben standardmäßig erhalten
- Verschachtelte JSON-Key-Struktur wird rekursiv beibehalten
- Für bestehende Zieldateien werden Sicherungen erstellt, außer bei
--no-backup - Fehlt die Quell-Snippet-Datei, wird das Plugin übersprungen und in der Zusammenfassung angezeigt
Exit-Verhalten
SUCCESS, wenn mindestens ein Plugin erfolgreich verarbeitet wurdeFAILURE, wenn alle Plugin-Jobs fehlschlagen oder übersprungen werden