DeepL Logo

Créez un complément Office en une journée avec l’API de DeepL

Une fois par mois, les employés de DeepL se consacrent à des projets personnels lors d’un Hack Friday organisé dans toute l’entreprise. Cette journée est l’occasion idéale pour nous de faire des expériences avec notre API ; et les résultats, lorsqu’ils sont concluants, donnent parfois lieu à de nouvelles fonctionnalités. Notre script pour Google Sheets est d’ailleurs le fruit de l’un de ces Hack Friday.

En septembre 2022, Marvin Becker (développeur) et Tim Cadenbach (developer evangelist ou « paradéveloppeur ») ont conçu un prototype de complément permettant d’utiliser l’API de DeepL pour traduire des textes directement dans un fichier Microsoft Word.

En voici un petit aperçu :

Pourquoi travailler sur un tel projet ?

DeepL est très utilisé dans le cadre professionnel, puisqu’il permet à des équipes internationales et multilingues de collaborer efficacement tout en garantissant la protection des données sensibles de leur entreprise. Des clients nous demandent souvent des conseils pour mettre au point leur propre complément afin d’utiliser notre API dans la suite Office. Nous voulions donc en créer un nous‑mêmes pour mieux comprendre tout ce que cela impliquait, et être ainsi en mesure de répondre aux questions éventuelles. 

Nous présentons ici nos conclusions. Veuillez noter qu’un code en source ouverte est également à votre disposition pour vous faciliter la tâche.

Prêts à coder ? C’est parti ! 

Étape n° 0 : revoir les bases (facultatif)  

Si vous n’avez pas l’habitude de travailler avec les API Office, nous vous conseillons de lire l’article Compréhension de l’API JavaScript pour Office dans la documentation de Microsoft. En résumé, tous les produits Office partagent une API commune en plus de leur propre API.

Lisez aussi éventuellement ce tutoriel avant de passer à l’étape n° 1. 

Étape n° 1 : concevoir un prototype avec Script Lab (ou utiliser le nôtre) 

Script Lab est un projet de Microsoft en source ouverte. Cet outil permet de faire des expériences avec l’API JavaScript de la suite Office directement dans Excel, Outlook, Word et PowerPoint. Notez que le référentiel GitHub de Script Lab contient un tutoriel d’introduction.

Idéal pour écrire un code et le voir rapidement en action, Script Lab nous a permis de créer le premier prototype de notre complément, qui ne comporte qu’un seul fichier JavaScript, HTML et CSS.

Ce prototype n’est pas celui que vous pourrez partager avec votre équipe, mais il vous donne au moins un aperçu de ce dont l’API de DeepL est capable et du type d’expérience utilisateur possible avec ce genre de complément.

Cela dit, nous vous avions promis un code en source ouverte, n’est‑ce pas ? Eh bien, étant donné que Script Lab permet d’importer des « extraits » de codes créés par quelqu’un d’autre, nous avons publié notre code pour Word sur GitHub pour que vous puissiez l’essayer.

Veuillez noter que vous aurez besoin d’une clé d’authentification API pour y accéder. Si vous n’avez pas de clé, n’hésitez pas à vous abonner gratuitement.

Copiez et collez le Gist YAML selon nos consignes, puis insérez la clé d’authentification de l’API de DeepL dans l’espace prévu à cet effet à la ligne 32, vous pourrez ensuite exécuter notre extrait en quelques clics.

En plus, cet extrait peut être réutilisé lorsque vous configurez le modèle de votre complément ; tout ce que vous ferez dans Script Lab pourra donc vous être utile à l’avenir.

Étape n° 2 : créer un complément Office avec le générateur Yeoman

Maintenant que nous avons vu le prototype Script Lab et les bases du script Office, créons un complément en bonne et due forme à l’aide de Yeoman, un outil de génération de modèles qui facilite la mise en place de nouveaux projets. Microsoft a d’ailleurs créé un modèle, souvent surnommé « Yo Office », que vous pouvez utiliser pour vos propres compléments Office. 

Les consignes d’utilisation se trouvent sur le site de Microsoft, dans l’article Créer des projets de complément Office à l’aide du générateur Yeoman.

Une fois que vous aurez suivi ces consignes, copiez votre code depuis Script Lab et collez‑le dans le référentiel que vous aurez tout juste créé. Il restera encore des choses à configurer, mais vous pourrez déjà au moins exécuter la commande 'npm run start', ce qui lancera Word et chargera automatiquement une version test de votre complément.

Vous pouvez coder dans n’importe quel IDE, mais le modèle généré fonctionne mieux avec les outils de codage propres à Microsoft, soit VS Code et Visual Studio. Nous vous conseillons d’utiliser Visual Studio, qui est plus pratique pour coder et débugger.

Étape n° 3 : implémenter l’API de DeepL

L’implémentation de DeepL est très directe, puisqu’un script de récupération JavaScript appelle le point de terminaison du traducteur de texte, ce qui est suffisant pour notre prototype. Vous pouvez également intégrer des glossaires dans votre complément, sachez seulement que c’est un peu plus compliqué à réaliser.

Vous noterez que nous n’avons pas utilisé notre bibliothèque Node.js pour ce projet, car elle n’est pas conçue pour des codes JavaScript côté client, et qu’en appelant un code de ce côté‑là avec elle, vous pourriez compromettre la sécurité de votre clé API.

Consultez notre fichier GIST (accessible ci‑dessus) pour mieux comprendre notre approche (voir à partir de la ligne 102).

Étape n° 4 : débugger correctement sur un Mac 

Microsoft a fait de gros progrès ces dernières années pour proposer ses produits aux fans d’Apple. Cela dit, si les systèmes Mac sont bien adaptés à .NET Core, il est encore assez compliqué de les utiliser pour coder dans un environnement Windows et dans les applications Microsoft Office. Les versions Mac des applications Microsoft ne sont en effet pas très bien configurées pour des opérations de débuggage. Tim ne jurant que par Microsoft, il en est d’ailleurs un « MVP », il n’a eu aucun problème. Marvin, en revanche, est un fidèle d’Apple et a dû télécharger Parallels pour débugger son code correctement. 

Nous vous conseillons donc d’exécuter les codes Office et Visual Studio dans Parallels pour bien débugger vos applications et travailler correctement sur votre complément. Ce n’est pas la panacée, mais c’est déjà ça.

Étape n° 5 : partager son complément avec d’autres utilisateurs

Les compléments Office sont chargés sur l’affichage web utilisé dans les applications Office, et sont affichés à l’aide d’iFrames. Vous devez donc héberger votre complément sur un serveur auquel vous avez accès. Consultez la documentation Microsoft pour comprendre comment déployer et publier des compléments Office

Dès que le complément est opérationnel, n’importe quel administrateur Office peut le mettre à disposition des utilisateurs de son entreprise, et ce via le Centre d’administration Microsoft 365. Les compléments mis en ligne à l’aide de ce centre sont immédiatement utilisables.

Bonus : adapter son complément aux autres applications Microsoft 

Adapter votre complément aux autres applications n’a rien de compliqué. Les compléments Office ont en effet de nombreux composants en commun, et peuvent généralement être utilisés dans toutes les applications de la suite, soit Outlook, Word, Excel, PowerPoint, Visio et OneNote.

Chacune d’entre elles a différents événements cependant. Par exemple, dans notre complément Word, nous avons utilisé OnTextSelected, tandis qu’avec Excel, vous utiliseriez probablement quelque chose comme OnColumnSelected ou Row.

Pour adapter votre complément aux autres applications, il vous suffit donc d’y ajouter les actions ou événements nécessaires, c’est aussi simple que cela. Notez que la majeure partie de votre code est réutilisable dans les autres applications.  

Il est généralement recommandé de faire de votre code une fonction spécifique que vous pouvez ensuite réutiliser et rappeler avec les caractéristiques de l’application voulue. Lisez ces articles de Microsoft pour en savoir plus.

Microsoft a également créé un module d’apprentissage qui pourrait vous aider.

Conclusion

Nous espérons que cet article vous aura été utile ! Si vous avez des questions, n’hésitez pas à nous en faire part en créant une issue dans notre référentiel GitHub avec l’extrait Script Lab.  

Bon codage !