Upgrade von tmgmt_deepl 2.2.x auf 2.4.x mit dem DeepL-Einrichtungsassistenten
In tmgmt_deepl 2.2.x gab es zwei Plugins (DeepL API Free und Pro), und der API-Key stand im Klartext in der Config des Translator Plugins, also auch in jedem Config-Export. Ab 2.3.x gibt es nur noch ein Plugin, das über die offizielle deepl-php Bibliothek mit DeepL kommuniziert. Den Key verwaltet das Key-Modul, zum Beispiel als Umgebungsvariable.
Damit dieses Upgrade einfach vonstatten geht, bringt die aktuelle Version 2.4.4 einen Upgrade-Assistenten (d.o/3605451).
Änderungen
- Plugins ändern sich. deepl_free und deepl_pro werden durch deepl_api ersetzt, welches den API Endpoint aus dem Key ableitet.
- Key Handling wird ausgelagert. Der Klartext-Key in tmgmt.translator.*.yml wird vom Update entfernt - jeder Translator steht danach ohne Key da.
- Standardwerte wurden angepasst. 20 statt 5 Texte pro Request, Tag-Handling v2, ein wählbares Modell - bestehende Übersetzer-Plugins behalten das alte Verhalten.
- Custom Code greift nicht mehr. Entfernte Hooks werden schlicht nicht mehr aufgerufen, und ein vergessener Config-Export holt die Legacy-Übersetzer zurück.
Der DeepL-Einrichtungsassistent
- Pre-Flight-Checks blockieren drush updb, bevor sich etwas ändert.
- Geführte Key-Migration pro Translator, geprüft gegen DeepL.
- Vorher / jetzt / empfohlen - zeigt die Einstellungen im direkten Vergleich.
- Custom-Code-Scan mit Datei, Zeile und Ersatz.
- Config-Export-Check, Testübersetzung und drush tmgmt-deepl:upgrade-status für CI.
Schritt-für-Schritt-Anleitung
Schritt 1: Code aktualisieren
Am besten aktualisiert man von 2.2.x direkt auf 2.4.x, da der Zwischenschritt von 2.3.x zwar die Legacy-Plugins entfernt, aber nicht den Upgrade-Assistenten enthält.
# Already on Drupal 11.4:
composer require drupal/tmgmt_deepl:^2.4.4 -W
# Moving from Drupal 10 / 11.3 to 11.4 – core and module together:
composer require drupal/core-recommended:^11.4 drupal/core-composer-scaffold:^11.4 drupal/tmgmt_deepl:^2.4.4 -WSchritt 2: Datenbank-Updates ausführen
drush updbEin Pre-Flight-Check stoppt das Update, wenn deepl-php oder das Key-Modul fehlt, und warnt vor Keys, die entfernt werden. Anschließend schreibt das Update die Legacy-Übersetzer um:
Vorher (2.2.x)
plugin: deepl_pro
settings:
auth_key: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'Nachher (2.4.x, nach Abschluss des Assistenten/ Export der Config)
plugin: deepl_api
settings:
auth_key_entity: deepl_api_key
tag_handling_version: v2
max_queries: 20Schritt 3: Einrichtungsseite öffnen und Umgebung prüfen
Die Seite (/admin/tmgmt/translators/deepl-setup) ist im Statusbericht, in der Provider-Übersicht und im Bearbeitungsformular des Translators verlinkt. Der erste Schritt prüft deepl-php, das Key-Modul, offene Updates und Legacy Übersetzer - auch in der zu importierenden Konfiguration.
Ein Klick auf "Add a key" führt zum Upgrade-Assistenten.
Sofern alle umgebungsspezifischen Anforderungen erfüllt sind, kann der Key hinzugefügt werden.
Schritt 4: API-Keys zuweisen
Pro Translator-Plugin kann ein vorhandener Key gewählt oder neu angelegt werden. Dies kann als Umgebungsvariable (empfohlen, Standard DEEPL_API_KEY), als Datei oder in der Konfiguration (dann landet er wie in 2.2.x im Config-Export) erfolgen. Nicht benötigte Übersetzer lassen sich direkt hier löschen.
Neuen Key anlegen oder bestehende Key-Entität auswählen.
Schritt 5: Einstellungen prüfen
Es besteht die Möglichkeit empfohlene Einstellungen zu übernehmen oder aktuelle Einstellungen beizubehalten.
Schritt 6: Glossare synchronisieren (optional)
Ist tmgmt_deepl_glossary aktiviert, importiert ein Klick auf Sync with DeepL die DeepL-Glossare.
Schritt 7: Custom Code anpassen
Auf aktualisierten Sites listet der Scan entfernte API und Hooks auf, zum Beispiel:
Schritt 8: Testen, abschließen und prüfen
Der letzte Schritt listet nicht exportierte Konfiguration auf und ermöglicht eine Test-Übersetzung. Wenn alle Tests erfolgreich sind und die Konfiguration exportiert wurde, kann das Upgrade über eine Klick auf Finish upgrade abgeschlossen werden.
Export der neuen Config und Cache rebuild
Um den Vorgang abzuschließen, müssen wir die Konfiguration exportieren und den Cache neu aufbauen.
drush config:export # deploy new keys and translators with the code
drush tmgmt-deepl:upgrade-status # non-zero exit while something blocks
drush tmgmt-deepl:upgrade-status --finish # finish without the UI
drush cache:rebuildWichtige Hinweise
- Konfiguration exportieren. Sonst stellt der nächste config:import die Legacy-Translator-Plugins wieder her.
- Große Jobs laufen in Timeouts? 5 Texte pro Request sind in den Einstellungen des Translator-Plugin weiterhin wählbar.
- Bestehende DeepL-API-Free/Pro-Abos funktionieren weiter (Free-Accounts sind auf ein Glossar beschränkt).
- Neuinstallationen nutzen denselben Assistenten ohne den Custom-Code-Schritt und enden mit Done.