Wie man ein Office-Add-In mit der DeepL API in nur einem Tag erstellt

Einmal im Monat nehmen die Mitarbeitenden von DeepL am „Hack Friday“ teil, einem Tag, an dem sie an Projekten arbeiten können, die nicht unbedingt zu ihrem Arbeitsalltag gehören. Dieser Tag bietet die ideale Gelegenheit, mit unserer API herumzuexperimentieren – und manchmal kommen dabei Ergebnisse heraus, von denen auch unsere Nutzer profitieren. Unser kürzlich veröffentlichtes Skript für Google Sheets ist ein solches Hack-Friday-Ergebnis.

Im September 2022 entwarfen unser Softwareentwickler Marvin Becker und unser Developer Evangelist Tim Cadenbach den Prototyp eines Add-Ins für Microsoft Word, das es Nutzern ermöglicht, mit Hilfe der DeepL API direkt in einem Word-Dokument zu übersetzen.

Hier ein kleiner Einblick:

Aber was macht das Projekt so interessant?

DeepL wird oft im beruflichen Umfeld eingesetzt, da es internationalen und mehrsprachigen Teams eine effiziente Zusammenarbeit ermöglicht und gleichzeitig den Schutz sensibler Unternehmensdaten gewährleistet. Immer wieder erreichen uns Anfragen von Kunden, die ihr eigenes Office-Add-In mit der DeepL API erstellen möchten und nach Ressourcen für den Einstieg suchen. Um die Fragen unserer Kunden besser beantworten zu können, wollten wir aus erster Hand erfahren, was es braucht, um eine Integration zu realisieren. 

Unsere Ergebnisse präsentieren wir Ihnen in diesem Blogpost. Außerdem stellen wir Ihnen Open-Source-Code zur Verfügung, damit Sie Ihr Projekt schneller in Angriff nehmen können.

Sind Sie bereit? Dann ab an die Arbeit! 

Tipp 0 (optional): Recherche ist das A und O  

Wenn Sie mit den Office-APIs noch nicht vertraut sind, empfehlen wir Ihnen Grundlegendes zur Office-JavaScript-API in der Dokumentation von Microsoft zu lesen. Kurz und knapp: Alle Office-Produkte bieten eine allgemeine API, die durch anwendungsspezifische APIs ergänzt wird.

Auch dieses Tutorial könnte hilfreich sein, bevor Sie zu Tipp 1 übergehen. 

Tipp 1: Einen Prototyp mit Script Lab erstellen (oder unseren verwenden) 

Script Lab ist ein Open-Source-Projekt, das von Microsoft gepflegt wird. Mit diesem Tool können Sie direkt in Excel, Outlook, Word oder PowerPoint mit der Office-JavaScript-API experimentieren. Das GitHub-Repository von Script Lab enthält ein Tutorial, das Ihnen den Einstieg erleichtert.

Script Lab ist ideal, um Code zu schreiben und ihn schnell in Aktion zu sehen. So konnten wir den ersten Prototyp unseres Add-Ins erstellen, der nur aus einer einzigen JavaScript-, HTML- und CSS-Datei besteht.

Dieser erste Schritt führt Sie zwar noch nicht zum Add-In, das Sie mit Ihren Teammitgliedern teilen können, aber er gibt Ihnen immerhin schon einmal eine Vorstellung davon, welche Möglichkeiten Ihnen die DeepL API bietet und welche Art von Benutzererfahrung Sie mit Ihrem Add-In schaffen können.

Erinnern Sie sich noch? Weiter oben haben wir Ihnen Open-Source-Code versprochen. Script Lab bietet die Möglichkeit, „Snippets“ von anderen zu importieren. Daher haben wir das von uns erstellte Word-Snippet als Open Source zur Verfügung gestellt, so dass auch Sie es verwenden können. Sie finden es hier auf GitHub.

Zusätzlich benötigen Sie einen API-Authentifizierungsschlüssel, um diesen Schritt auszuführen. Wenn Sie noch kein DeepL-Konto haben, können Sie hier DeepL API Free oder Pro buchen.

Führen Sie anschließend einfach die folgenden Schritte aus: Kopieren Sie zunächst die Gist-YAML-Datei und fügen Sie sie wie in der Anleitung beschrieben ein; fügen Sie anschließend Ihren Authentifizierungsschlüssel für die DeepL API in den Platzhalter in Zeile 32 ein, und schon können Sie unser Snippet ausführen.

Das Beste daran? Das Script Lab-Snippet kann wiederverwendet werden, wenn Sie die Add-In-Vorlage einrichten! Alle Vorbereitungen, die Sie jetzt in Script Lab treffen, werden sich also später als nützlich erweisen.

Tipp 2: Ein Office-Add-In mit dem Yeoman-Generator erstellen

Nachdem wir nun einen Prototyp in Script Lab erstellt und die Grundlagen der Office-Skripterstellung kennengelernt haben, können wir mit der Erstellung des eigentlichen Add-Ins mit Yeoman loslegen. Yeoman ist ein Open-Source-Tool, mit dem sich relativ einfach neue Projekte erstellen lassen. Für Office-Add-Ins kann eine von Microsoft erstellte Vorlage verwendet werden, die auch als „Yo Office“ bekannt ist. 

Der Vorgang wird hier erklärt: Erstellen von Office-Add-In-Projekten mithilfe des Yeoman-Generators.

Nachdem Sie die Einrichtung abgeschlossen haben, kopieren Sie den Code von Script Lab in Ihr neu erstelltes Repository. Es gibt noch ein paar weitere Dinge zu konfigurieren, aber Sie können sofort loslegen, indem Sie „npm run start“ ausführen. Mit diesem Befehl wird Word gestartet und das Add-In automatisch geladen.

Im Prinzip können Sie frei wählen, mit welcher IDE Sie arbeiten möchten. Bedenken Sie aber, dass die generierte Vorlage am besten mit den von Microsoft entwickelten Code-Editoren VS Code oder Visual Studio funktioniert. Wir empfehlen die Verwendung von Visual Studio, da wir hier bessere Erfahrungen beim Coden und Debuggen gemacht haben.

Tipp 3: Die DeepL API implementieren

Die Implementierung von DeepL ist einfach: Ein JavaScript-Skript ruft den Endpunkt der Textübersetzung auf. Für unseren Prototyp war das ausreichend. Wenn Sie jedoch Glossare in Ihrem Add-In verwenden möchten, müssen Sie etwas mehr Zeit investieren.

Wir haben für dieses Projekt nicht die offizielle Node.js-Clientbibliothek von DeepL verwendet, da diese Bibliothek nicht für clientseitigen JavaScript-Code gedacht ist. Der Grund hierfür ist die Sicherheit: Sie würden Ihren API-Authentifizierungsschlüssel beim Aufrufen von clientseitigem Code preisgeben.

Sie können sich die oben gezeigte GIST-Datei ab Zeile 102 ansehen, um sich ein genaueres Bild von unserem Ansatz zu machen.

Tipp 4: Debuggen für Mac-Benutzer 

In den letzten Jahren hat Microsoft erheblich in die Verbesserung seiner Unterstützung für Mac-Benutzer investiert. Obwohl Mac-Systeme für die Entwicklung mit .NET Core recht gut geeignet sind, lässt Apple bei der Entwicklung von Software für Windows – und somit für Microsoft Office-Anwendungen – noch einiges zu wünschen übrig. Daher ist es auch nicht so einfach, Microsoft-Software auf dem Mac zu debuggen. Tim schwört auf Microsoft (und ist sogar ein MVP!), daher hatte er keine Probleme. Mac-Benutzer Marvin hingegen musste Parallels herunterladen, um richtig debuggen zu können. 

Wir empfehlen Ihnen daher, Microsoft Office und Visual Studio Code in Parallels auszuführen, um Anwendungen zu debuggen und das Add-In entsprechend zu bearbeiten. Das ist zwar keine 100%ige Lösung, aber sie erfüllt ihren Zweck!

Tipp 5: Ihr Add-In mit Benutzern teilen

Office-Add-Ins werden auf die in den Office-Anwendungen verwendete Webansicht geladen und mithilfe von iFrames angezeigt. Das bedeutet, dass Sie Ihr Add-In auf einem Webserver hosten müssen, auf den Sie Zugriff haben. Weitere Informationen dazu finden Sie in der Microsoft-Dokumentation unter Bereitstellen und Veröffentlichen von Office-Add-Ins. 

Sobald das Add-In einsatzbereit ist, kann jeder Office-Administrator es den Benutzern in seinem Unternehmen über das Microsoft 365 Admin Center zur Verfügung stellen. Add-Ins, die über das Admin Center bereitgestellt werden, können sofort verwendet werden.

Bonus: Ihr Add-In auf andere Microsoft-Anwendungen erweitern 

Sie können Ihr Add-In ganz einfach auf andere Anwendungen erweitern. Office Add-Ins haben viele Komponenten gemeinsam und können in der Regel in allen Anwendungen der Suite verwendet werden, d. h. in Outlook, Word, Excel, PowerPoint, Visio und OneNote.

Alle Anwendungen haben jedoch unterschiedliche Ereignisse. In unserem Add-In für Word haben wir beispielsweise OnTextSelected verwendet, während Sie in Excel wahrscheinlich so etwas wie OnColumnSelected oder Row verwenden würden.

Damit Ihr Add-In in anderen Anwendungen funktioniert, fügen Sie ganz einfach die entsprechenden Ereignisse oder Aktionen hinzu, auf die Ihr Add-In reagieren soll. Der Großteil Ihres Codes kann in anderen Anwendungen wiederverwendet werden.  

Im Allgemeinen empfiehlt es sich, Ihren spezifischen Code in eine Funktion umzuwandeln, die Sie wiederverwenden und mit den erforderlichen Anwendungsspezifika erneut aufrufen können. Diese Artikel könnten dabei hilfreich sein.

Außerdem finden Sie hier ein nützliches Lernmodul von Microsoft.

Zu guter Letzt

Wir hoffen, dass Sie diesen kleinen Überblick hilfreich fanden! Wenn Sie Fragen haben, können Sie gerne ein Issue im GitHub-Repository mit dem Script Lab-Snippet erstellen.  

Gutes Gelingen!