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. Les Hack Fridays constituent une excellente occasion d'expérimenter avec notre API, et parfois, les résultats sont mis à la disposition des utilisateurs. En réalité, notre script Google Sheets-DeepL récemment publié est le résultat d'un projet Hack Friday. Lors d'un Hack Friday en septembre 2022, Marvin Becker, développeur logiciel chez DeepL, et Tim Cadenbach, évangéliste développeur, ont créé un prototype de complément API DeepL pour Microsoft Word, permettant aux utilisateurs de traduire directement dans un document Word avec DeepL.

En voici un petit aperçu :

Pourquoi travailler sur un tel projet ?

La communication professionnelle est un cas d'utilisation courant de DeepL : les traductions DeepL permettent à une main-d'œuvre multilingue et internationale de collaborer efficacement tout en garantissant la sécurité des données sensibles de l'entreprise. Nous recevons fréquemment des demandes de clients qui souhaitent créer leur propre complément Office à l'aide de l'API de DeepL et recherchent des ressources pour se lancer. 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. 

Dans cet article, nous partagerons ce que nous avons appris. Nous vous fournirons également un code open source pour vous aider à démarrer votre projet plus rapidement. Êtes-vous prêt pour l' ? C’est parti ! 

Conseil 0 (facultatif) : Veuillez effectuer quelques recherches.  

Si vous débutez avec les API Office, nous vous recommandons de lire Comprendre l'API JavaScript Office dans la documentation Microsoft. En résumé, tous les produits Office fournissent une API commune avec des API spécifiques aux produits supérieures. Il pourrait également être utile de parcourir ce tutoriel avant de passer à l'astuce n° 1. 

Conseil n° 1 : Création d'un prototype avec Script Lab (ou utilisation du nôtre) 

Script Lab est un projet open source géré par Microsoft. Cet outil permet de faire des expériences avec l’API JavaScript de la suite Office directement dans Excel, Outlook, Word et PowerPoint. Le Script Lab Le référentiel GitHub comprend un tutoriel pour vous aider à démarrer.

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 ? Script Lab offre la possibilité d'importer les « snippets » créés par d'autres utilisateurs. Nous avons donc mis à disposition en open source le snippet DeepL-Word que nous avons développé afin que chacun puisse l'essayer. Vous pouvez le trouver sur GitHub ici.

Veuillez noter que vous aurez besoin d’une clé d’authentification API pour y accéder. Vous pouvez s’abonner à un compte ici.

Veuillez simplement copier et coller le fichier YAML Gist comme indiqué dans les instructions, insérer votre clé API de DeepL dans l'espace réservé à la ligne 32, et vous pourrez exécuter notre extrait de code en quelques clics seulement.

Le meilleur dans tout cela ? L'extrait Script Lab peut être réutilisé lors de la configuration du modèle de complément, de sorte que tout le travail effectué dans Script Lab vous sera utile ultérieurement.

Conseil n° 2 : Création d'un projet Office Complément à l'aide du générateur Yeoman

Maintenant que nous avons réalisé quelques prototypes dans Script Lab et que nous maîtrisons les bases du script Office, nous pouvons commencer à créer un complément réel à l'aide de Yeoman. Yeoman est un outil open source qui facilite considérablement la création 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. 

Le processus est décrit ici : Complément Office Yeoman Générateur.

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 y a d'autres paramètres à configurer, mais vous pouvez commencer immédiatement en exécutant « npm run start ». Cela lancera Word et chargera automatiquement votre complément. Vous pouvez utiliser n'importe quel IDE pour le développement, bien que le modèle généré fonctionne mieux avec les éditeurs de code propres à Microsoft, VS Code ou Visual Studio. Nous vous conseillons d’utiliser Visual Studio, qui est plus pratique pour coder et débugger.

Conseil n° 3 : Mise en œuvre de l'API de DeepL

Notre implémentation de DeepL est simple : un script JavaScript fetch appelle l'endpoint de traduction de texte. Pour notre prototype simple, cela était suffisant. Si vous souhaitez activer les Glossaires dans votre complément, vous devrez effectuer quelques manipulations supplémentaires.

Nous n'avons pas utilisé la bibliothèque cliente Node.js officielle de DeepL. pour ce projet, car la bibliothèque cliente n'est pas conçue pour le code JavaScript côté client. pour ce projet, car elle n'est pas conçue pour le code JavaScript côté client. La raison est la sécurité : vous exposeriez votre clé API en appelant le code côté client. Vous pouvez consulter le fichier GIST que nous avons partagé ci-dessus pour voir notre approche plus en détail (à partir de la ligne 102).

Conseil n° 4 : Débogage pour les utilisateurs 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.  Exécution de Microsoft Office et du code Visual Studio dans Parallels vous permettra de déboguer les applications et de travailler correctement sur le complément. Ce n’est pas la panacée, mais c’est déjà ça.

Conseil n° 5 : Partager votre complément avec les 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. Pour en savoir plus sur la manière de déployer et de publier des compléments Office dans la documentation Microsoft. 

Une fois le complément installé et opérationnel, tout administrateur Office peut le déployer auprès des utilisateurs et des groupes de son organisation via le centre d'administration Microsoft 365. Les compléments mis en ligne à l’aide de ce centre sont immédiatement utilisables.

Bonus : Étendre votre complément à d'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. Dans notre exemple Word, nous avons utilisé OnTextSelected, alors que dans Excel, vous ajouteriez probablement quelque chose comme OnColumnSelected ou Row. Pour que votre complément fonctionne dans d'autres applications, ajoutez les événements ou actions correspondants auxquels vous souhaitez que votre complément réagisse. 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. Nous vous recommandons de consulter les articles disponibles ici.

De plus, il existe un excellent module MS apprendre qui peut vous aider.

Conclusion

Nous espérons que cet article vous aura été utile ! Si vous avez des questions, n'hésitez pas à créer un ticket dans le référentiel GitHub avec l'extrait de code Script Lab et à nous en faire part.  

Bon codage !