Cómo crear un complemento de la API de DeepL para Office en un día

Un viernes al mes, DeepL organiza lo que internamente conocemos como «Hack Friday»: un día en el que podemos dedicarnos a proyectos que no forman parte necesariamente de nuestro trabajo en el día a día. Los Hack Friday son la oportunidad perfecta para trastear con nuestra API y explorar nuevas posibilidades con ella. A veces los resultados de estos proyectos llegan a nuestros usuarios. De hecho, el script para Google Sheets que lanzamos hace poco —para traducir el contenido de las celdas con DeepL— fue fruto de un Hack Friday.

En el Hack Friday de septiembre de 2022, nuestro desarrollador de software Marvin Becker y nuestro desarrollador evangelista Tim Cadenbach, crearon un prototipo de complemento de la API de DeepL para Microsoft Word que permite a los usuarios traducir con DeepL directamente en un documento de Word.

Puedes echar un vistazo a cómo funciona el complemento aquí:

Pero, ¿qué es lo que realmente hace este proyecto interesante?

DeepL se emplea mucho en el contexto profesional, ya que optimiza la colaboración entre equipos internacionales y multilingües a la vez que garantiza la máxima seguridad de datos para toda la información. Nuestros clientes nos piden consejo a menudo sobre cómo desarrollar su propio complemento para utilizar nuestra API en el paquete Office. Por ello, quisimos investigar de primera mano qué haría falta para integrar DeepL en Office y así poder responder mejor a sus dudas. 

Aquí te presentamos todo lo que hemos aprendido al respecto. Además, te proporcionamos código abierto para ayudarte a poner en marcha tu proyecto más rápidamente.

¡Vamos a ello! 

Consejo para antes de empezar (opcional): haz los deberes  

Si esta es tu primera experiencia usando una API de Office, te aconsejamos que leas el artículo Información sobre la API de JavaScript para Office de la documentación de Microsoft. En resumen: todos los productos de Office ofrecen una API común que se complementa con API específicas para cada producto.

También puede resultar de ayuda consultar este tutorial antes de avanzar al paso 1. 

Paso 1: crear un prototipo con Script Lab (o usar el nuestro) 

Script Lab es un proyecto de código abierto gestionado por Microsoft. Esta herramienta te permite experimentar con la API de JavaScript para Office directamente en Excel, Outlook, Word y PowerPoint. El repositorio de GitHub de Script Lab cuenta con un tutorial para ayudarte con los primeros pasos.

Script Lab es la herramienta ideal para escribir código y verlo en acción rápidamente. Por ello, decidimos emplearla para crear el primer prototipo de nuestro complemento, que consta de un solo archivo JavaScript, HTML y CSS.

Aunque esta primera fase no da lugar todavía al complemento final que podrás compartir con tu equipo, al menos te da una idea de las posibilidades que te ofrece la API de DeepL y del tipo de experiencia de usuario que puedes crear con tu complemento.

Lo prometido es deuda: ahora te enseñamos cómo hacerte con el código abierto que te hemos comentado antes. Script Lab te ofrece la posibilidad de importar fragmentos de código creados por otros. Por ello, hemos publicado el fragmento de código para Word que hemos creado como código abierto para que cualquiera pueda utilizarlo. Te lo hemos dejado en GitHub.

Importante: para conseguirlo necesitarás la clave de autenticación de la API de DeepL. Si aún no tienes una cuenta de DeepL, puedes crear una aquí.

Tan solo tienes que copiar y pegar el Gist YAML (tal y como se indica en nuestras instrucciones) e introducir tu clave de autenticación de la API de DeepL en el espacio para ella de la línea 32 y estarás ejecutando nuestro código en apenas unos clics.

Por si esto fuera poco, el fragmento de Script Lab se puede reutilizar para configurar la plantilla del complemento, por lo que todo el trabajo que realices en esta herramienta te será útil más adelante.

Paso 2: crear un complemento para Office con el generador de Yeoman

Ahora que ya sabes cómo crear prototipos en Script Lab y conoces los fundamentos de los scripts para Office, podemos empezar a crear un complemento con Yeoman, una herramienta de generación de plantillas que facilita la configuración de nuevos proyectos. Microsoft ha creado una plantilla denominada «Yo Office» destinada específicamente a proyectos de desarrollo de complementos de Office. 

Para obtener información más detallada al respecto, consulta el artículo Creación de proyectos de complementos de Office mediante el generador de Yeoman que encontrarás en la documentación de Microsoft.

Una vez hayas seguido las instrucciones de configuración, copia el código desde Script Lab y pégalo en el repositorio que acabas de crear. Aún quedan cosas por configurar, pero al menos puedes ejecutar el comando 'npm run start', que iniciará Word y cargará automáticamente una versión de prueba de tu complemento.

Puedes usar cualquier IDE para el desarrollo, pero la plantilla proporcionada por Microsoft funciona mejor con sus propios editores de código, como VS Code y Visual Studio. Para una mejor experiencia de codificación y depuración, recomendamos utilizar Visual Studio.

Paso 3: implementar la API de DeepL

Nuestra implementación de DeepL es de lo más sencilla: un script de obtención de JavaScript que llama al punto de conexión de traducción de texto. Para este prototipo en concreto, no hace falta más. También es posible activar los glosarios en tu complemento, pero esto lleva algo más de tiempo, ya que es más complicado.

No utilizamos la biblioteca de cliente para Node.js de DeepL para este proyecto porque no está pensada para código JavaScript del lado del cliente. Esto es por razones de seguridad, ya que revelarías tu clave de autenticación de la API de DeepL al llamar a código del lado del cliente.

Echa un vistazo a nuestro archivo GIST para obtener información más detallada al respecto (a partir de la línea 102).

Paso 4: depuración para usuarios de Mac 

En los últimos años, Microsoft ha invertido significativamente en mejorar su compatibilidad con MacOS. A pesar de que los sistemas Mac se adaptan bien a .NET Core, sigue siendo bastante complicado utilizarlos para codificar en un entorno Windows y en aplicaciones de Microsoft Office. Por tanto, las versiones para Mac de las aplicaciones de Microsoft no están configuradas para facilitar la depuración. Tim es un fan devoto de Microsoft (que fue incluso nombrado MVP), por lo que no tuvo ningún problema. Sin embargo, Marvin, fiel defensor de Apple, tuvo que descargar Parallels para poder depurar su código correctamente. 

Te aconsejamos que ejecutes los códigos de Microsoft Office y Visual Studio a través de Parallels para depurar las aplicaciones y poder trabajar en tu complemento como es debido. No será la solución perfecta, pero al menos funciona... ¡algo es algo!

Paso 5: compartir el complemento con otros usuarios

Los complementos de Office se cargan en la vista web de las aplicaciones de Office y se muestran mediante iFrames, por lo que tendrás que alojarlos en un servidor web al que tengas acceso. Para más información al respecto, consulta el artículo Implementar y publicar complementos de Office de la documentación de Microsoft. 

Una vez que el complemento esté operativo, cualquier administrador de Office podrá implementarlo para los miembros de su equipo o los usuarios de su empresa mediante el Centro de administración de Microsoft 365. Los complementos que se publiquen a través de este centro pueden usarse de inmediato.

Paso extra: expandir el complemento a otras aplicaciones de Microsoft 

Adaptar tu complemento a otras aplicaciones es de lo más sencillo. Los complementos de Office tienen muchos componentes en común y normalmente pueden utilizarse en todas las aplicaciones del paquete, es decir, Outlook, Word, Excel, PowerPoint, Visio y OneNote.

Sin embargo, cada aplicación tiene eventos diferentes. Por ejemplo, en nuestro complemento de Word utilizamos OnTextSelected, mientras que con Excel probablemente utilizarías algo como OnColumnSelected o Row.

Adaptar tu complemento a otras aplicaciones es tan fácil como añadir las acciones o eventos a los que quieres que el complemento reaccione. Ten en cuenta que podrás reutilizar la mayoría de tu código de una aplicación a otra.  

Por lo general, te recomendamos convertir el código en una función específica que luego se pueda reutilizar y llamar de nuevo con las características de la aplicación deseada. Consulta estos artículos para más información.

Además, Microsoft ha creado un módulo de aprendizaje que seguramente te será de ayuda.

En resumen

¡Esperamos que esta guía te haya resultado útil! Ante cualquier duda, crea una propuesta o issue en nuestro repositorio de GitHub con el fragmento de Script Lab y cuéntanosla.  

¡Mucha suerte!