Building a DeepL API add-in for Microsoft Office (in just one day)

Once per month, DeepL employees participate in a company-wide Hack Friday, taking on projects outside of their day-to-day work. Hack Fridays are a great opportunity to tinker with our API, and sometimes the results make it to users. In fact, our recently released Google Sheets-DeepL script was the result of a Hack Friday project! On a Hack Friday in September 2022, DeepL software developer Marvin Becker and developer evangelist Tim Cadenbach built a prototype DeepL API add-in for Microsoft Word, making it possible for users to translate with DeepL directly in a Word document.

You can see it in action here:

Why were we interested in this integration?

Business communication is a popular DeepL use case—DeepL translations can enable a global, multilingual workforce to collaborate efficiently while keeping sensitive company data secure. We often hear requests from customers who want to build their own Office Add-in with the DeepL API and are looking for resources to get started. We wanted to learn first-hand what an integration would require so that we can provide better answers when our customers ask us questions. 

In this post, we’ll share what we learned. We'll also provide open-source code to help you get your project off the ground more quickly. Ready? Let’s build! 

Tip 0 (optional): Do a little homework  

If you’re brand new to the Office APIs, we suggest reading Understanding the Office JavaScript API in Microsoft’s documentation. In short, all Office products provide a Common API with product-specific APIs on top. It could also be helpful to skim through this tutorial before moving to Tip 1. 

Tip 1: Building a prototype with Script Lab (or use ours) 

Script Lab is an open-source project maintained by Microsoft. Script Lab makes it possible to experiment with the Office JavaScript API without leaving Excel, Outlook, Word, or PowerPoint. The Script Lab GitHub repository includes a tutorial to help you get started.

We used Script Lab to create an initial prototype of our add-in because it's an ideal way to quickly write code and see it in action—and it consists of only a single JavaScript, HTML, and CSS file.

While this initial step isn’t the add-in you can share with team members just yet, it gives you an idea of what is possible with the DeepL API and what sort of user experience you'll be able to provide with your add-in.

Earlier in the post, we promised you an open-source code! Script Lab offers a way to import someone else’s “snippet”, so we’ve open sourced the DeepL-Word snippet we created so that anyone can give it a try. You can find it in GitHub here.

You’ll also need a DeepL API key if you'd like to follow along with this step. You can sign up for an account here.

Simply copy and paste the Gist YAML as outlined in the instructions, insert your DeepL API key in the placeholder in line 32, and you'll be able to run our snippet in just a few clicks.

The best part? The Script Lab snippet can be repurposed as you're setting up the add-in template, so all the work you do in Script Lab will come in handy later.

Tip 2: Creating an Office Add-in project with the Yeoman Generator

Now that we’ve done some prototyping in Script Lab and know the basics of Office scripting, we can start to create an actual add-in using Yeoman. Yeoman is an open-source scaffolding tool that makes new projects relatively easy. For Office Add-ins, there’s a pre-made template by Microsoft you can use, often referred to as “Yo Office”. 

The process is covered here: Office Add-in Yeoman Generator.

After following the setup instructions, copy the code from Script Lab to your newly created repository. There’s more to configure, but you can get started right away by executing 'npm run start’. This will launch Word and automatically sideload your add-in. You can use any IDE for developing, though the generated template works best with Microsoft’s own code editors VS Code or Visual Studio. For a better coding and debugging experience we recommend using Visual Studio.

Tip 3: Implementing the DeepL API

Our implementation of DeepL is straightforward—a JavaScript fetch script calls the text translation endpoint. For our simple prototype, that was sufficient. If you want to enable glossaries in your add-in, you’ll need to put in a bit more work.

We didn’t use DeepL’s official Node.js client library for the project because the library isn’t meant for client-side JavaScript code. The reason here is security—you'd expose your API key when calling client-side code. You can look at the GIST file we shared above to see our approach in more detail (starting on line 102).

Tip 4: Debugging for Mac users 

In recent years, Microsoft has made significant investments to support Mac users. While Mac support is quite good for .NET Core development, it’s still not good enough for core Windows development—including Microsoft Office apps. Unfortunately, the Microsoft app versions for Mac users aren’t configured for easy debugging. Tim is a Microsoft loyalist (and MVP!), so he didn’t have any issues, but Mac user Marvin needed to download Parallels to debug properly.  Running Microsoft Office and Visual Studio code in Parallels will let you debug apps and work on the add-in properly. It's not a 100% seamless solution, but it gets the job done!

Tip 5: Sharing your add-in with users

Office Add-ins are loaded into the web view that runs in Office apps and are displayed using iFrames, so you’ll need to host it on a web server you have access to. You can read more about how to deploy and publish Office Add-ins in the Microsoft documentation. 

Once you have the add-in up and running, any Office admin can deploy it to users and groups in their organization via the Microsoft 365 admin center. Add-ins deployed via admin center are available to use right away.

Bonus: Extending your add-in to other Microsoft apps 

It’s easy to extend your add-in to other apps. Office Add-ins share a lot of components, and an add-in for one application should work in all supported applications (Outlook, Word, Excel, PowerPoint, Visio, and OneNote).

However, all the apps have different events. In our Word example, we’ve been using OnTextSelected, whereas in Excel you would probably use something like OnColumnSelected or Row. To make your add-in work in other apps, add the corresponding events or actions you want your add-in to react to—it’s that simple. Most of your code can be re-used across applications.  

It’s generally recommended to turn your specific code into a function that you can re-use and call again with the application specifics you need. We suggest reading through the articles available here.

Also, there’s a nice MS Learn module that can help.

Wrapping up

We hope you found this overview helpful! If you have any questions, feel free to create an issue in the GitHub repository with the Script Lab snippet and let us know.  

We wish you all the best on your DeepL API-Microsoft Office journey.