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. Hack Fridays bieden een uitstekende gelegenheid om met ons API te experimenteren, en soms worden de resultaten ook daadwerkelijk door gebruikers gebruikt. Ons recent uitgebrachte Google Sheets-DeepL-script was zelfs het resultaat van een Hack Friday-project. Tijdens een Hack Friday in september 2022 ontwikkelden DeepL-softwareontwikkelaar Marvin Becker en ontwikkelaar Tim Cadenbach een prototype DeepL API-invoegtoepassing voor Microsoft Word, waardoor gebruikers rechtstreeks in een Word-document met DeepL kunnen vertalen.

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?

Zakelijke communicatie is een veelvoorkomend gebruiksscenario voor DeepL. DeepL-vertalingen kunnen een internationaal, meertalig personeelsbestand in staat stellen om efficiënt samen te werken en tegelijkertijd gevoelige bedrijfsgegevens veilig te houden. Wij ontvangen regelmatig verzoeken van klanten die hun eigen Office-invoegtoepassing willen ontwikkelen met de DeepL API en op zoek zijn naar bronnen om aan de slag te gaan. 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, Wij zullen ook open-sourcecode verstrekken om u te ondersteunen bij het versnellen van uw project. Bent u gereed voor ? Aan de slag dan maar! 

Tip 0 (optioneel): spieken mag!  

Indien u nog niet bekend bent met de Office API's, raden wij u aan het volgende te lezen: Inzicht in de Office JavaScript API in de documentatie van Microsoft. Kortom, alle Office-producten bieden een gemeenschappelijke API met daarbovenop productspecifieke API's . Het kan ook nuttig zijn om deze tutorial door te nemen voordat u doorgaat naar tip 1. 

Tip 1: een prototype maken met Script Lab 

Script Lab is een open-sourceproject dat wordt beheerd door Microsoft. Je kunt er gebruik van maken om te experimenteren met de Office JavaScript API zonder Excel, Outlook, Word of PowerPoint te hoeven verlaten. Het Script Lab GitHub-repository bevat een tutorial om u 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. U kunt hier je account aanmelden.

Kopiëren en plak de Gist YAML zoals beschreven in de instructies, voeg uw DeepL API-key in de plaatshouder in regel 32 en u kunt ons fragment met slechts een paar klikken uitvoeren.

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-invoegtoepassing 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 en wordt uw invoegtoepassing automatisch geladen. U kunt elke IDE gebruiken voor het ontwikkelen, hoewel de gegenereerde sjabloon het beste werkt met Microsofts eigen code-editors 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. Indien u woordenlijsten in uw invoegtoepassing wilt inschakelen, dient u wat meer werk te verrichten.

Wij hebben geen gebruik gemaakt van DeepL's officiële Node.js-clientbibliotheek voor het project, omdat de bibliotheek niet bedoeld is voor JavaScript-code aan de clientzijde. De reden hiervoor is veiligheid: u zou uw API-key blootstellen wanneer u client-side code aanroept. U kunt het GIST-bestand dat we hierboven hebben gedeeld raadplegen om onze aanpak in meer detail te bekijken (vanaf regel 102).

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.  Microsoft Office en Visual Studio-code uitvoeren in Parallels kunt u apps debuggen en correct aan de invoegtoepassing 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. U kunt meer informatie vinden over het uitrollen en publiceren van Office-invoegtoepassingen in de documentatie van Microsoft. 

Zodra de invoegtoepassing is geïnstalleerd en actief is, kan elke Office-beheerder deze uitrollen voor gebruikers en groepen binnen hun organisatie via het Microsoft 365-beheercentrum. 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. In ons Word-voorbeeld hebben we OnTextSelected gebruikt, terwijl u in Excel waarschijnlijk iets als OnColumnSelected of Row zou gebruiken. Om uw invoegtoepassing in andere apps te laten werken, voegt u de overeenkomstige gebeurtenissen of acties toe waarop u wilt dat uw invoegtoepassing reageert – zo eenvoudig is het. 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. Wij raden u aan de beschikbare artikelen hier te lezen.

Er is ook een uitstekende MS Learn-module die u kan ondersteunen.

Zelf aan de slag

We hopen dat je deze blogpost interessant vond en nu zelf aan de slag wilt gaan. Indien u vragen heeft, kunt u een issue aanmaken in de GitHub-repository met het Script Lab-fragment en ons hiervan op de hoogte stellen.  

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