Inhalt
Systemvoraussetzungen
- PHP 7+ muss verwendet werden. Wir empfehlen Version 7.2
- Guzzle muss installiert sein, das ist i.d.R. vorinstalliert.
- Es sollte auf dem Server eine Möglichkeit zur Ausführung von Cron-Jobs vorhanden sein. Als Workaround funktioniert auch ein regelmäßiger Aufruf einer URL.
Prozessdokumentation
Datenstruktur
Das Modul benötigt folgende DB-Tabellen, um seine Daten zu organisieren:
- ettm_project
- ettm_project2article
- ettm_project2attribute
- ettm_project2category
- ettm_project2cms
- ettm_importjobs
Eine Übersetzung wird im Rahmen eines Projekts abgearbeitet. Ein Projekt enthält, mit Ausnahme des Projektnames, hauptsächlich technische Informationen. Hierzu gehören IDs im Lokal- und Fernsystem, Ausgangs- und Zielsprachen, Zeiten der Veränderung und interne Statistiken.
Das Projekt kann mittels einer N-zu-M Beziehung einem Produkt, einem Attribut, einer Kategorie oder einer Inhaltsseite zugeordnet werden. Einem Projekt können also mehrere Kategorien zugeordnet werden und einer Kategorie mehrere Projekte. Diese Zuordnung referenziert lediglich das Projekt mit der Zielzeile der entsprechenden Tabelle.
Das Modul kommuniziert mit der Eurotext Translation API. Nach dem Export werden bei Eurotext im entsprechenden Projekt sogenannte Items angelegt. Der translationMANAGER richtet sich während des Importes an diese Items und erstellt anhand dieser eine Importliste. Jedes Element dieser Importliste ist eine Zeile innerhalb der Tabelle ettm_importjobs und enthält die ID des Items bei Eurotext.
Export
Beim Export wird die Liste der ausgewählten Elemente iteriert. Jedes Element hat innerhalb der Datenbank eine eigene Haupttabelle und ggf. mehrere Zusatztabellen. Hierbei speichert die Haupttabelle beispielsweise die Namen der Attribute, die Zusatztabelle enthält die Werte der Attribute.
Für jede Tabelle jedes Elements wird ein Item erstellt. Ein Item ist ein JSON Objekt. Falls die Übersetzung schon vorhanden ist und laut Projekteinstellungen die bereits übersetzten Items übersprungen werden müssen, wird das Item als “skipped” markiert. Die Tabelle und die ID der Zeile werden in Meta übergeben.
Sobald die Item-Liste erstellt ist, wird jedes Item – eines nach dem anderen – an Eurotext geschickt. Dabei werden erfolgreiche/fehlerhafte Übertragungen sowie übersprungene Items gezählt. Diese Zähler werden verwendet, um den Projektfortschritt zu berechnen.
Import
Beim Import werden zunächst alle Items des Projekts ausgelesen. Dadurch entsteht eine Import-Liste.
Danach wird jedes einzelne Item in dieser Liste von der Eurotext Translation API heruntergeladen und die übersetzten Felder in der Zieltabelle werden überschrieben.
Asynchrone Verarbeitung
Um die Belastung des Shopsystems konstant zu halten, werden Importe und Exporte komplett asynchron abgearbeitet. Dafür sind Cron-Jobs einzurichten. Jeder Job nimmt X Elemente pro Aufruf und verarbeitet diese. Durch die Einstellung der pro Aufruf zu verarbeitenden Elemente kann ein Optimum zwischen Belastung und Geschwindigkeit gefunden werden.
Einrichtung der Cron Jobs
Es gibt insgesamt 3 Cron Jobs. Die Aufgaben werden in PHP Dateien erledigt. Man kann sie sowohl auf dem Server ausführen, als auch über direkten Browseraufruf:
- https://www.domain.de/modules/eurotext/translationmanager6/cron/translation_cron.php
- https://www.domain.de/modules/eurotext/translationmanager6/cron/export_cron.php
- https://www.domain.de/modules/eurotext/translationmanager6/cron/import_cron.phpl
Es ist nicht vorgeschrieben, wie oft sie aufgerufen werden müssen. Jedoch sollte das Intervall so gewählt werden, dass keine unnötigen Ressourcen belegt werden. Wir empfehlen ein Intervall von 30 min für den Import Cron-Job, bis das Projekt abgeschlossen ist.
- export_cron.php Exportiert die Items vom Shop zur Eurotext Translation API.
- import_cron.php Importiert die Items von der Eurotext Translation API in den Shop.
- translation:cron.php Prüft den Status bei den Items des Projekts. Wenn der Status aller Projekt-Items in der API “finished” lautet, wird das Projekt als “Bereit für Import” markiert.
Update 28.07.2020
Seit v2.3.0 werden Multishop-Konfigurationen unterstützt. Jeder Subshop bekommt einen eigenen Cron Job, der mit einem GET Parameter shopId aufgerufen werden kann. Der Parameter entspricht der aktuellen Shop-Id des Subshops.
Beispiel: https://www.domain.de/modules/eurotext/translationmanager6/cron/translation_cron.php?shopId=4
Benutzerdokumentation
Export
Als Export ist die Übertragung der einzelnen Elemente an Eurotext zur Übersetzung zu verstehen. Damit ein Export stattfinden kann, muss zuerst ein Projekt angelegt werden.
Dafür klickt man in der Menünavigation auf “Translationmanager > Export” oder auf einer Projektdetailseite im unteren Bereich der Seite auf “Neues Projekt” .
Danach muss zwingend ein Projektname angegeben werden. Es muss mindestens eine Zielsprache ausgewählt sein. Optional können weitere Zielsprachen ausgewählt werden.
Wenn man einen Projektnamen vergeben und Zielsprache(n) ausgewählt hat, kann das Projekt gespeichert werden. Beim Speichern wird das Projekt sowohl in der internen Shopdatenbank gespeichert, als auch in der Eurotext API-Datenbank angelegt und mit dem lokalen Eintrag verlinkt.
Nach dem Speichern erscheint das Projekt in der Projektliste im oberen Teil des Bildschirms. Der Status lautet nun “Neu”. Im mittleren Teil des Bildschirms wird ein neuer Bereich aktiv und sichtbar: “Elemente für Übersetzung auswählen”.
Hier können Kategorien, Attribute, Artikel und CMS-Seiten ausgewählt werden. Dafür klickt man auf den Link unter der entsprechenden Headline, z.B. “Artikel auswählen”. Es erscheint ein Popup, in dem man die einzelnen Elemente durch drag&drop auswählen kann.
Sobald man mindestens ein Element ausgewählt hat, wird ein neuer Bereich aktiv: “Daten übermitteln”.
Hier kann man festlegen, ob alle ausgewählten Elemente übersetzt werden sollen oder nur die, die noch keine Übersetzung haben.
ACHTUNG: Falls die Einstellung “Bereits übersetzte Elemente überspringen” NICHT ausgewählt wird, werden beim Import bereits existierende Übersetzungen in den vorhandenen Datenbankfeldern überschrieben.
Starten Sie den Export über den entsprechenden Bereich “Export starten”
ACHTUNG: Sobald der Export gestartet wurde, kann die Auswahl nicht mehr editiert werden.
Nun werden die ausgewählten Elemente markiert. Dadurch kann der Cron-Job sie erfassen und an Eurotext übermitteln. Das Projekt selbst bekommt den Status “Export läuft” und es wird der Fortschrittsbalken angezeigt. Im mittleren Bereich wird ein neuer Bereich sichtbar: “Status”. Hier sieht man den Verlauf des Exports in Zahlen.
Sobald der Export abgeschlossen wird, wird der Projektstatus auf “Exportiert” geändert und im mittleren Bereich wird der Bereich “Übersetzung starten” sichtbar.
Übersetzung starten
Wenn der Export abgeschlossen ist, wurden alle Elemente an die Eurotext Translation API übermittelt. Klicken Sie auf “Übersetzung starten”, um das Übersetzungsprojekt zu beginnen.
Das Projekt bekommt nun den Status “Übersetzung läuft” und der Fortschrittsbalken wird angezeigt.
Sobald die Übersetzung fertig ist, wird das Projekt nicht mehr in der Liste bei “Export” angezeigt. Stattdessen erscheint er nun in der Projektliste unter “TranslationManager > Import” und ist bereit für den Import.
Sie erhalten außerdem eine Information vom Eurotext Projektteam, dass die Übersetzung geliefert wurde und importiert werden kann.
Import
Um den Import zu starten, muss auf den Button “Import starten” geklickt werden.
Das setzt den Status auf “Import läuft”. Im Hintergrund werden einzelne Items von Eurotext heruntergeladen und in die lokale Datenbank geschrieben. Es sind keine weiteren Arbeitsschritte notwendig.
Sobald der Import abgeschlossen ist, bekommt das Projekt den Status “Importiert”.
Die Übersetzungen liegen nun in Ihrem OXID 6 Shop vor.