Skapa ett DeepL API-tillägg för Microsoft Office (på bara en dag)

En gång i månaden deltar DeepL-anställda i en företagsomfattande Hack Friday, där de tar sig an projekt utanför sitt dagliga arbete. Hack Fridays är ett utmärkt tillfälle att experimentera med vårt API, och ibland når resultaten användarna. Vårt nyligen släppta Google Sheets-DeepL-skript var faktiskt resultatet av ett Hack Friday-projekt! Under en Hack Friday i september 2022 byggde DeepL:s mjukvaruutvecklare Marvin Becker och utvecklarevangelisten Tim Cadenbach en prototyp till ett DeepL API-tillägg för Microsoft Word, vilket gör det möjligt för användare att översätta med DeepL direkt i ett Word-dokument.

Du kan se det i aktion här:

Varför var vi intresserade av denna integration?

Företagskommunikation är ett populärt användningsområde för DeepL – DeepL-översättningar gör det möjligt för en global, flerspråkig personalstyrka att samarbeta effektivt samtidigt som känslig företagsinformation hålls säker. Vi får ofta förfrågningar från kunder som vill bygga sitt eget Office-tillägg med DeepL API och letar efter resurser för att komma igång. Vi ville lära dig direkt vad en integration skulle kräva så att du kan ge bättre svar när dina kunder ställer frågor till dig. 

I det här inlägget delar vi med oss av vad vi har lärt oss. Vi tillhandahåller även öppen källkod för att hjälpa dig att komma igång med ditt projekt snabbare. Redo? Låt oss bygga! 

Tips 0 (valfritt): Gör lite hemläxor  

Om du är helt ny när det gäller Office API:er rekommenderar vi att du läser Förstå Office JavaScript API i Microsofts dokumentation. Kort sagt, alla Office-produkter tillhandahåller ett gemensamt API med produktspecifika API:er utöver detta. Det kan också vara bra att bläddra igenom denna handledning innan du går vidare till tips 1. 

Tips 1: Bygg en prototyp med Script Lab (eller använd vår) 

Script Lab är ett öppen källkodsprojekt som underhålls av Microsoft. Script Lab gör det möjligt att experimentera med Office JavaScript API utan att lämna Excel, Outlook, Word eller PowerPoint. The Script Lab GitHub-arkivet innehåller en handledning som hjälper dig att komma igång.

Vi använde Script Lab för att skapa en första prototyp av vårt tillägg, eftersom det är ett perfekt sätt att snabbt skriva kod och se hur den fungerar – och den består bara av en enda JavaScript-, HTML- och CSS-fil.

Även om detta första steg ännu inte är ett tillägg som du kan dela med teammedlemmarna, ger det dig en uppfattning om vad som är möjligt med DeepL API och vilken typ av användarupplevelse du kan erbjuda med ditt tillägg.

Tidigare i inlägget lovade vi er en öppen källkod! Script Lab:s erbjudande är att importera andras ”snippets”, så vi har gjort vårt DeepL-Word-snippet tillgängligt som öppen källkod så att vem som helst kan prova det. Du hittar den på GitHub här.

Du behöver också en DeepL API-nyckel om du vill följa detta steg. Du kan registrera dig för ett konto här.

Kopiera och klistra in Gist YAML enligt instruktionerna, ange din DeepL API-nyckel i platshållaren i rad 32, så kan du köra vårt kodavsnitt med bara några klick.

Det bästa? Script Lab-snippet kan återanvändas när du ställer in tilläggsmalen, så allt arbete du gör i Script Lab kommer att komma till nytta senare.

Tips 2: Skapa ett Office-tilläggsprojekt med Yeoman Generator

Nu när vi har gjort några prototyper i Script Lab och lärt oss grunderna i Office-skriptning kan vi börja skapa ett riktigt tillägg med Yeoman. Yeoman är ett öppet källkodsverktyg som gör det relativt enkelt att starta nya projekt. För Office-tillägg finns det en färdig mall från Microsoft som du kan använda, ofta kallad ”Yo Office”. 

Processen beskrivs här: Kontorsprogramstillägg Yeoman Generator.

Efter att ha följt installationsinstruktionerna kopierar du koden från Script Lab till ditt nyskapade arkiv. Det finns mer att konfigurera, men du kan komma igång direkt genom att köra 'npm run start'. Detta startar Word och laddar automatiskt in ditt tillägg. Du kan använda valfri IDE för utveckling, men den genererade mallen fungerar bäst med Microsofts egna kodredaktörer VS Code eller Visual Studio. För en bättre kodnings- och felsökningsupplevelse rekommenderar vi att du använder Visual Studio.

Tips 3: Implementering av DeepL API

Vår implementering av DeepL är enkel – ett JavaScript-hämtningsskript anropar slutpunkten för översättning av text. För vår enkel prototyp var det tillräckligt. Om du vill aktivera Ordlistor i ditt tillägg måste du lägga ner lite mer arbete.

Vi använde inte DeepL:s officiella Node.js-klientbibliotek för projektet eftersom biblioteket inte är avsett för JavaScript-kod på klientsidan. Anledningen till detta är säkerhet – du skulle exponera din API-nyckel när du anropar kod på klientsidan. Du kan titta på GIST-filen som vi delade ovan för att se vår metod mer i detalj (från rad 102).

Tips 4: Felsökning för Mac-användare 

Under de senaste åren har Microsoft gjort betydande investeringar till support av Mac-användare. Även om Mac-stödet är ganska bra för .NET Core-utveckling, är det fortfarande inte tillräckligt bra för kärnutveckling i Windows – inklusive Microsoft Office-apps. Tyvärr är Microsoft-app-versionerna för Mac-användare inte konfigurerade för enkel felsökning. Tim är en lojal Microsoft-användare (och MVP!), så han hade inga problem, men Mac-användaren Marvin behövde ladda ner Parallels för att kunna felsöka ordentligt.  Kör Microsoft Office och Visual Studio-kod i Parallels kan du felsöka appar och arbeta med tillägget på rätt sätt. Det är inte en 100 % perfekt lösning, men den fungerar!

Tips 5: Dela ditt tillägg med användare

Office-tillägg laddas in i webbvyn som körs i Office-appar och visas med hjälp av iFrames, så du måste lagra dem på en webbserver som du har tillgång till. Du kan läsa mer om hur du driftsätter och publicerar Office-tillägg i Microsofts Dokumentation. 

När tillägget är installerat och igång kan alla Office-administratörer driftsätta det till användare och grupper i sin organisation via Microsoft 365-administrationscentret. Tillägg som driftsätts via admincenter kan användas direkt.

Bonus: Utöka ditt tillägg till andra Microsoft-apps 

Det är enkelt att utöka ditt tillägg till andra appar. Office-tillägg har många gemensamma komponenter, och ett tillägg för en applikation bör fungera i alla applikationer som stöds (Outlook, Word, Excel, PowerPoint, Visio och OneNote).

Alla app har dock olika händelser. I vårt Word-exempel har vi använt OnTextSelected, medan du i Excel antagligen skulle använda något som OnColumnSelected eller Row. För att ditt tillägg ska fungera i andra appar lägger du till motsvarande händelser eller åtgärder som du vill att tillägget ska reagera på – så enkelt är det. Det mesta av din kod kan återanvändas i olika applikationer.  

Det rekommenderas generellt att omvandla din specifika kod till en funktion som du kan återanvända och återanvända med de applikationsspecifika funktioner du behöver. Vi rekommenderar att du läser igenom artiklarna som finns här.

Det finns också en bra MS lär dig-modul som kan vara till hjälp.

Sammanfattning

Vi hoppas att du tyckte att denna översikt var till hjälp! Om du har några frågor är du välkommen att skapa ett ärende i GitHub-arkivet med Script Lab-snippet och meddela oss.  

Vi önskar dig lycka till på din resa med DeepL API-Microsoft Office.