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 Fridays son una gran oportunidad para experimentar con nuestro API y, a veces, los resultados llegan a los usuarios. De hecho, nuestro script Hojas de cálculo de Google-DeepL, lanzado recientemente, fue el resultado de un proyecto Hack Friday. En un Hack Friday celebrado en septiembre de 2022, el desarrollador de software de DeepL Marvin Becker y el evangelista de desarrolladores 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?

La comunicación empresarial es un caso de uso muy popular de DeepL: las traducciones de DeepL permiten a una plantilla internacional y multilingüe colaborar de forma eficiente y mantener a la vez la seguridad de los datos confidenciales de la empresa. A menudo recibimos solicitudes de clientes que desean crear su propio complemento de Office con la API de DeepL y buscan recursos para empezar. 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. También proporcionaremos código abierto para ayudarte a poner en marcha tu proyecto más rápidamente. ¿Estás listo para ? ¡Construyamos! 

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

Si eres nuevo en las API de Office, te recomendamos leer Comprender la API de JavaScript de Office en la documentación de Microsoft. En resumen, todos los productos de Office proporcionan una API común con API específicas de cada producto adicionales. También podría resultarte útil echar un vistazo a este tutorial antes de pasar al Consejo 1. 

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

Script Lab es un proyecto de código abierto mantenido por Microsoft. Esta herramienta te permite experimentar con la API de JavaScript para Office directamente en Excel, Outlook, Word y PowerPoint. El laboratorio de guiones El repositorio GitHub incluye un tutorial para ayudarte a empezar.

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. Puedes crear una cuenta aquí.

Simplemente copia y pega el Gist YAML tal y como se indica en las instrucciones, inserta tu clave de API de DeepL en el marcador de posición de la línea 32 y podrás ejecutar nuestro fragmento de código haciendo clic en solo unos.

Pero, ¡aún hay más! El fragmento de Script Lab se puede reutilizar al configurar la plantilla del complemento, por lo que todo el trabajo que realices en Script Lab te resultará útil más adelante.

Paso 2: Crear un complemento para Office con Yeoman Generator

Ahora que hemos creado algunos prototipos en Script Lab y conocemos los fundamentos de la programación de Office, podemos empezar a crear un complemento real con Yeoman. Yeoman es una herramienta de andamiaje de código abierto que facilita relativamente la creación de nuevos proyectos. Microsoft ha creado una plantilla denominada «Yo Office» destinada específicamente a proyectos de desarrollo de complementos de Office. 

El proceso se describe aquí: Complemento de Office Yeoman Generator.

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. Hay más cosas que configurar, pero puedes empezar de inmediato ejecutando «npm run start». Esto iniciará Word y cargará automáticamente tu complemento. Puedes utilizar cualquier IDE para desarrollar, aunque la plantilla generada funciona mejor con los editores de código propios de Microsoft, VS Code o 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. Si deseas habilitar glosarios en tu complemento, tendrás que trabajar un poco más.

No utilizamos la biblioteca cliente oficial de DeepL para el proyecto para el proyecto porque la biblioteca no está pensada para código JavaScript del lado del cliente. El motivo es la seguridad: al llamar al código del lado del cliente, se expondría la clave de API. Puedes consultar el archivo GIST que hemos compartido anteriormente para ver nuestro enfoque con más detalle (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.  Ejecutar Microsoft Office y Visual Studio Code en Parallels te permitirá depurar aplicaciones y trabajar correctamente en el complemento. 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. Puedes obtener más información sobre cómo implementar y publicar complementos de Office en la documentación de Microsoft. 

Una vez que tengas el complemento instalado y en funcionamiento, cualquier administrador de Office podrá implementarlo para los usuarios y grupos de su organización a través del 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. En nuestro ejemplo de Word, hemos utilizado OnTextSelected, mientras que en Excel probablemente utilizarías algo como OnColumnSelected o Row. Para que tu complemento funcione en otras aplicaciones, añade los eventos o acciones correspondientes a los que deseas que reaccione tu complemento, así de simple. 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. Te recomendamos que leas los artículos disponibles aquí.

Además, hay un interesante módulo de MS Más información que puede resultar útil.

En resumen

¡Esperamos que esta guía te haya resultado útil! Si tienes alguna pregunta, no dudes en crear una incidencia en el repositorio de GitHub con el fragmento de Script Lab y háznoslo saber.  

¡Mucha suerte!