Internationalization Plugin für den Camunda Modeler

In diesem Blogpost stellen wir unser I18N-Plugin für den Camunda Modeler vor und erklären, welche Herausforderungen bei der Implementierung auftraten und wie neue Sprachen hinzugefügt oder bestehende Sprachen angepasst werden können.

TL;DR: Mit unserem I18N-Plugin für den Camunda Modeler kann der Modeler auch in anderen Sprachen genutzt werden. Deutsch ist bereits integriert. Der fertige Modeler kann im GitHub-Repository Camunda Modeler I18N Plugin gefunden werden. Dort ist auch beschrieben, wie das Plugin installiert und angepasst werden kann.

Im Rahmen eines unserer Kundenprojekte ist geplant, den Camunda Modeler für Nicht-Entwicklungsabteilungen bereitzustellen. Im Zuge dessen ist es notwendig, die Oberfläche auch auf Deutsch anzubieten. Da dies auch für andere Projekte interessant sein könnte, entschlossen wir uns, das Projekt Open Source bereitzustellen.

Wir konnten in der Vergangenheit bei der Entwicklung individueller Modellierungstools bereits einige Erfahrungen mit dem Camunda Modeler und dem darunterliegenden Framework bpmn.io sammeln, um uns von der fehlenden Dokumentation nicht abschrecken zu lassen.

Konzeption

Der Camunda Modeler besteht aus mehreren Teilen, die alle einzeln implementiert wurden und daher bei der Konzeption berücksichtigt werden müssen. Die wichtigsten davon sind hier kurz beschrieben:

• bpmn.js, cmmn.js und dmn.js: Diese Open-Source-Libraries sind Teil von bpmn.io und erlauben die Modellierung von Diagrammen in BPMN, CMMN und DMN.
• bpmn.js-properties-panel: Dieser Teil enthält das Seitenpanel, welches die Konfiguration einzelner Elemente in BPMN erlaubt. Entsprechende Properties Panels existieren auch für CMMN und DMN.
• diagram.js: Diese Library übernimmt die eigentliche Darstellung der Elemente.

Der Camunda Modeler bietet bereits die Möglichkeit, Übersetzungen bereitzustellen, indem an nahezu allen Stellen eine translate()-Funktion aufgerufen wird, bevor Strings in der Oberfläche dargestellt werden. Allerdings existierte bisher nur eine funktionslose Implementierung davon.

Die meisten der oben genannten Teile nutzen ebenfalls diese zentrale Funktion, weshalb wir uns bei der Umsetzung darauf konzentrierten. Unser primäres Ziel war es, den Modeler sowohl auf Deutsch als auch auf Englisch bereitzustellen und die Sprache jederzeit in der Oberfläche dauerhaft, also auch über Neustarts hinweg persistent, wechseln zu können.

Erstellung des Plugins

Zum Erstellen von Plugins stellt Camunda ein Demo-Repository bereit, welches wir als Ausgangspunkt verwendeten und nach und nach ergänzten und verbesserten. Für interessierte steht sämtlicher Quellcode ausführlich dokumentiert in unserem GitHub-Repository bereit.

Die eigentliche Implementierung der Übersetzungsfunktion liegt in der Datei client/i18n-extension/translate.js. Die dort am Ende zurückgegebene Funktion ersetzt die oben erwähnte No-Op-Implementierung der translate()-Funktion. Über die darüber eingebundenen Event-Listener kann die Sprache zur Laufzeit jederzeit geändert werden.

Die dafür notwendigen Events werden in der Menü-Komponente ausgelöst, welche in der Datei menu/menu.js liegt. Aus der darin gespeicherten Konfiguration wird das Menü generiert, welches das Wechseln der Sprache in der Oberfläche erlaubt.

Der komplizierteste Teil war dabei das Speichern der gewählten Sprache über Neustarts hinweg. Wir wollten diese Einstellung in die config.json-Datei des Modelers speichern, wofür allerdings keine direkte Schnittstelle bereitstand. Über viel Trial&Error und ein gewisses Maß an „Reverse Engineering“ konnten wir schließlich die in der Klasse client/configuration/Config.js gesetzte Implementierung entwerfen.

Diese kann auch jederzeit in anderen Plugins verwendet werden, um zur Laufzeit Konfigurationswerte in die config.json zu speichern und wieder zu lesen!

Jetzt war nur noch die eigentliche Übersetzung der verwendeten Strings notwendig. Dabei trennten wir die Strings nach dem Teil des Modelers, in dem sie auftaucht, darunter bpmn.js, dmn.js, das Properties Panel und sonstige Teile.

Die Bibliothek cmmn.js verwendet die translate()-Funktion nicht, weshalb dafür auch keine entsprechende Datei existiert. Bei dmn.js funktionieren die Übersetzungen in der neuesten Version analog zu bpmn.js.

Fazit

Das Einbinden der Übersetzungen war dank unserer Erfahrungen kein großes Problem. Die fehlende Dokumentation und der Wunsch, die gewählte Sprache zu speichern, stellte uns aber vor einige Herausforderungen.

Das Projekt inklusive einer Anleitung zum Hinzufügen neuer Sprachen ist in unserem GitHub-Repository zu finden. Pull Requests mit verbesserten Übersetzungen, neuen Sprachen und sonstigen Weiterentwicklungen sind immer gern gesehen!