Een DeepL API-invoegtoepassing voor Microsoft Office in één dag

Eén keer per maand nemen de werknemers hier bij DeepL deel aan "Hack Friday": een dag waarop iedereen in het bedrijf mag werken aan projecten die los staan van hun dagelijkse taken. Voor veel van onze IT-collega's die normaal gesproken niets met onze API te maken hebben, zijn Hack Fridays daarom dan ook de perfecte gelegenheid om zelf eens met de API te gaan experimenteren, en zulke projecten leiden zo af en toe tot resultaten die ze gewoon met de wereld moeten delen—en dus ook met onze gebruikers! Kun je je bijvoorbeeld nog herinneren aan ons DeepL-script voor Google Sheets? Want ja, inderdaad, dat was het resultaat van een van onze Hack Friday-projecten!

Afgelopen september werkten onze collega's Marvin Becker en Tim Cadenbach aan hun Hack Friday-project: een invoegtoepassing voor Microsoft Word waarmee direct in Word-documenten kan worden vertaald met behulp van de DeepL API. En aangezien de invoegtoepassing aan het eind van de dag klaar was voor gebruik, zou het natuurlijk zonde zijn als al dat harde werk intern zou blijven.

Als je dit Hack Friday-project dus eens in actie wilt zien, kun je hier een kijkje nemen:

Maar waarom vonden we uitgerekend dit project zo interessant?

Nou, het zit zo: als je aan de gebruikers van DeepL denkt, denk je waarschijnlijk al gauw aan mensen die onze vertaaltool gebruiken om bedrijfscommunicatie te vertalen. Een internationaal personeelsbestand is immers vaak meertalig, en om ervoor te zorgen dat iedereen efficiënt en vooral ook veilig met elkaar kan samenwerken, zijn onze vertalingen een goede oplossing. Het is daarom dan ook geen wonder dat we regelmatig van onze klanten te horen krijgen dat zij hun eigen invoegtoepassing willen maken om zo via de DeepL API te kunnen vertalen. De vraag was echter altijd: hoe begin je nu precies met zo'n project? Dat wilden we zelf natuurlijk ook graag weten—en de lessen die wij daarbij hebben geleerd, delen we ook graag met jou! 

Hieronder geven we je daarom een aantal tips om je te helpen om je eigen project sneller van de grond te krijgen, en daarnaast geven we je ook direct concrete voorbeelden in de vorm van open-source-code.

Klaar? Aan de slag dan maar! 

Tip 0 (optioneel): spieken mag!  

Als je nog nooit met een Office-API hebt gewerkt, raden wij je aan om eerst een kijkje te nemen op deze pagina uit de Microsoft-documentatie over het gebruik van de Office JavaScript API. Kort samengevat is het zo dat alle Office-producten twee soorten toegangspunten bieden: algemene API's en product-specifieke API's. Daarnaast is het wellicht ook verstandig om deze tutorial even door te nemen voordat je verdergaat met tip 1.

En nu, gewapend met deze kennis, wordt het tijd om zelf aan de slag te gaan. 

Tip 1: een prototype maken met Script Lab 

Script Lab is een open-source-project dat door Microsoft wordt onderhouden. Je kunt er gebruik van maken om te experimenteren met de Office JavaScript API zonder Excel, Outlook, Word of PowerPoint te hoeven verlaten. Het GitHub-archief voor Script Lab bevat een tutorial om je op weg te helpen.

Ook wij hebben Script Lab gebruikt om het eerste prototype van onze invoegtoepassing te maken. De reden hiervoor is eenvoudig: het is de ideale manier om snel code te schrijven en deze code daarna ook uit te proberen. Het resultaat is een prototype dat uit slechts één JavaScript-, HTML- en CSS-bestand bestaat.

Hoewel deze eerste versie nog niet klaar is om gedeeld te worden met teamleden, laat dit prototype wel zien wat je precies met de DeepL API zou kunnen bereiken en wat voor een gebruikerservaring je met je invoegtoepassing zou kunnen aanbieden.

Maar genoeg gekletst: wij hebben open-source-code beloofd en die willen we je dan ook graag laten zien! Via Script Lab is het namelijk mogelijk om "snippets" van geschreven code ter beschikking te stellen die andere mensen vervolgens kunnen importeren, dus hebben wij een snippet beschikbaar gemaakt van onze DeepL-code voor Word. Hiervoor kun je terecht op GitHub.

Om de snippet uit te proberen, heb je echter wel een authenticatiesleutel voor de DeepL API nodig. Als je dus nog geen account hebt, kun je je hier aanmelden.

Zodra je bent ingelogd op je account, volg je gewoon deze stappen: eerst kopieer en plak je de Gist YAML zoals beschreven in de instructies; vervolgens voeg je de authenticatiesleutel in op de plaats van de placeholder in regel 32; en ten slotte voer je de snippet uit.

En weet je wat het beste is? De Script Lab-snippet kan opnieuw worden gebruikt wanneer je je eigen sjabloon voor je invoegtoepassing maakt! Alle voorbereidingen die je nu in Script Lab treft, komen later dus nog van pas!

Tip 2: een Office-invoegtoepassing maken met de Yeoman Generator

Nu we een prototype hebben gemaakt in Script Lab en de grondbeginselen van Office-scripting hebben leren kennen, kunnen we aan de slag gaan met het maken van een echte invoegtoepassing met behulp van Yeoman. Yeoman is een open-source-tool waarmee relatief eenvoudig nieuwe projecten kunnen worden gemaakt. Voor Office-invoegtoepassingen is er een sjabloon van Microsoft beschikbaar (vaak "Yo Office" genoemd) dat je kunt gebruiken om van start te gaan. 

Het proces wordt hier uitgelegd: Office Add-in Yeoman Generator.

Nadat je klaar bent met de setup, kopieer je de code van Script Lab naar de repository die je zojuist hebt aangemaakt. Er moeten weliswaar nog een aantal andere dingen geconfigureerd worden, maar je kunt meteen aan de slag gaan door 'npm run start' uit te voeren. Hierdoor wordt Word gestart samen met je invoegtoepassing.

In principe ben je vrij om zelf te kiezen met welke IDE (integrated developer environment) je programmeert, maar houd er wel rekening mee dat het gegenereerde sjabloon het best werkt met de code-editors die Microsoft zelf heeft gemaakt, namelijk VS Code of Visual Studio. Voor een betere codeer- en debug-ervaring raden wij je aan om Visual Studio te gebruiken.

Tip 3: de DeepL API integreren

Onze implementatie van DeepL is eenvoudig: een JavaScript-script roept het eindpunt voor tekstvertalingen aan. Voor ons prototype was dat voldoende. Als je in je invoegtoepassing daarnaast echter ook gebruik wilt kunnen maken van de woordenlijst-functie, komt er iets meer bij kijken.

We hebben voor dit project geen gebruik gemaakt van de officiële DeepL-clientbibliotheek voor Node.js, omdat deze bibliotheek niet bedoeld is voor JavaScript-code aan de clientzijde. De reden hiervoor is veiligheid: wanneer je code aan de clientzijde aanroept, geef je automatisch je API-authenticatiesleutel prijs, en dat is niet de bedoeling. Daardoor zou deze immers voor iedereen zichtbaar worden.

Je kunt het GIST-bestand dat we hierboven hebben gedeeld, vanaf regel 102 raadplegen om een gedetailleerder beeld van onze aanpak te krijgen.

Tip 4: debuggen voor Mac-gebruikers 

In de afgelopen jaren heeft Microsoft aanzienlijk geïnvesteerd in het verbeteren van hun ondersteuning voor Mac-gebruikers. Hoewel Mac namelijk vrij goed is voor het ontwikkelen van .NET-software, laat Apple voor het ontwikkelen van software voor Windows nog altijd te wensen over. Voor Microsoft Office is dat helaas niet anders. Als gevolg hiervan is het niet mogelijk om Microsoft-software op Mac eenvoudig te debuggen. Tim is een echte Microsoft-fan, dus hij kon zonder problemen doorprogrammeren, maar als Mac-gebruiker moest Marvin debuggen via Parallels, een programma dat hij speciaal hiervoor moest downloaden. 

Door Microsoft Office en Visual Studio code in Parallels te draaien is het echter mogelijk om toepassingen te debuggen en zo aan de invoegtoepassing te werken. Het is geen perfecte oplossing, maar het krijgt de klus geklaard!

Tip 5: De invoegtoepassing delen met gebruikers

Office-toepassingen bezitten een webweergave waarin invoegtoepassingen kunnen worden geladen, waarna ze worden weergegeven met behulp van iFrames. Dit betekent dat je je invoegtoepassing moet hosten op een webserver waar je toegang toe hebt. Voor meer informatie over het publiceren van invoegtoepassingen voor Office kun je terecht op deze pagina uit de Microsoft-documentatie. 

Zodra de invoegtoepassing klaar is, kunnen Office-beheerders deze beschikbaar maken voor gebruikers en groepen in hun organisatie via het beheercentrum van Microsoft 365. Invoegtoepassingen die via het beheercentrum beschikbaar zijn, kunnen meteen worden gebruikt.

Bonus: invoegtoepassingen uitbreiden naar andere Microsoft-toepassingen 

Je kunt je invoegtoepassing ook gemakkelijk uitbreiden naar andere toepassingen. Office-invoegtoepassingen hebben namelijk veel gemeenschappelijke onderdelen, wat betekent dat een invoegtoepassing die in de ene toepassing werkt, ook zou moeten werken in alle andere toepassingen (Outlook, Word, Excel, PowerPoint, Visio en OneNote).

Houd er echter wel rekening mee dat je hier en daar een event zult moeten aanpassen als je van de ene toepassing naar de andere wisselt. Zo hebben we in ons voorbeeld voor Word bijvoorbeeld gebruik gemaakt van het event "OnTextSelected", maar voor Excel zou je waarschijnlijk gebruik willen maken van een ander event zoals "OnColumnSelected".

Om er dus voor te zorgen dat je invoegtoepassing ook in andere toepassingen werkt, moet je er dus aan denken dat je je events en actions telkens aanpast. Je kunt het merendeel van je code echter zonder problemen opnieuw gebruiken.  

In het algemeen doe je er goed aan om je specifieke code om te zetten in een functie die je telkens opnieuw kunt gebruiken wanneer je dat stukje software weer eens nodig hebt. We raden je daarom aan om deze artikelen bij gelegenheid ook nog eens door te nemen.

Daarnaast is er ook een leuke trainingsmodule beschikbaar: MS Learn module.

Zelf aan de slag

We hopen dat je deze blogpost interessant vond en nu zelf aan de slag wilt gaan. Als je vragen hebt, maak dan gerust een issue aan in de GitHub-repository met onze Script Lab-snippet en laat het ons weten.  

We wensen je veel succes met het integreren van de DeepL API in Microsoft Office!