Creare un componente aggiuntivo dell’API di DeepL per Microsoft Office in un solo giorno

Una volta al mese i dipendenti di DeepL passano un’intera giornata, che chiamiamo internamente “Hack Friday”, a lavorare sullo sviluppo di progetti personali. Gli Hack Fridays sono un'ottima occasione per sperimentare con la nostra API e, a volte, i risultati arrivano agli utenti. In effetti, il nostro script Google Sheets-DeepL, appena uscito, è nato da un progetto Hack Friday! Durante un Hack Friday a settembre 2022, Marvin Becker, sviluppatore software di DeepL, e Tim Cadenbach, sviluppatore evangelista, hanno creato un prototipo di componente aggiuntivo API di DeepL per Microsoft Word, che permette agli utenti di tradurre con DeepL direttamente in un documento Word.

Ecco una piccola anteprima:

Perché abbiamo deciso di lavorare su questo progetto?

La comunicazione aziendale è uno dei casi d'uso più comuni di DeepL: le traduzioni di DeepL permettono a una forza lavoro globale e multilingue di collaborare in modo efficiente e allo stesso tempo proteggere i dati aziendali sensibili. Spesso ci chiedono come creare il proprio componente aggiuntivo di Office con l'API di DeepL e cercano risorse per iniziare. abbiamo voluto crearne uno noi per capire meglio cosa avrebbe comportato, in modo da poter rispondere a qualsiasi loro domanda. 

In questo post condivideremo ciò che abbiamo imparato. Ti daremo anche del codice open source per aiutarti a far decollare il tuo progetto più velocemente. Pronto per l' ? Iniziamo! 

0. Fare un po’ di ricerca (opzionale)  

Se non hai mai usato le API di Office, ti consigliamo di dare un'occhiata a Comprendere l'API JavaScript di Office nella documentazione di Microsoft. In breve, tutti i prodotti Office offrono un' API comune con API specifiche per ciascun prodotto aggiuntive. Potrebbe anche essere utile dare un'occhiata a questo tutorial prima di passare al Suggerimento 1. 

Suggerimento 1: Creare un prototipo con Script Lab (o utilizzare il nostro) 

Script Lab è un progetto open source gestito da Microsoft. che consente di sperimentare con l’API JavaScript di Office senza dover uscire da Excel, Outlook, Word o PowerPoint. The Script Lab repository GitHub ha un tutorial per aiutarti a iniziare.

Abbiamo utilizzato Script Lab per creare un prototipo iniziale del nostro componente aggiuntivo, in quanto non solo rappresenta il metodo ideale per scrivere il codice e vederlo in azione rapidamente, ma è costituito anche da un solo file JavaScript, HTML e CSS.

Sebbene questa prima fase non generi ancora il componente aggiuntivo finale da condividere con il tuo team, serve comunque a darti un’idea di ciò che è possibile fare con l’API di DeepL e che tipo di esperienza utente si può offrire con il componente aggiuntivo.

Detto ciò, all’inizio del post abbiamo promesso di fornire un codice open source. Script Lab dà la possibilità di importare i frammenti di codice creati da qualcun altro, perciò abbiamo reso disponibile il frammento che abbiamo creato per Word, in modo che i nostri utenti possano provarlo. È disponibile su GitHub cliccando qui.

Per accedere all’API di DeepL è necessaria però una chiave di autenticazione, Puoi iscriversi a un account qui.

Basta copiare e incollare il Gist YAML come indicato nelle istruzioni, inserire la tua chiave API di DeepL nel segnaposto alla riga 32 e potrai eseguire il nostro snippet facendo clic.

Non è tutto! Lo snippet di Script Lab può essere riutilizzato mentre configuri il modello di componente aggiuntivo, quindi tutto quello che fai in Script Lab ti tornerà utile in seguito.

2. Creare un componente aggiuntivo per Office con il generatore Yeoman

Ora che abbiamo capito come creare un prototipo su Script Lab e abbiamo compreso le basi dello scripting di Office, possiamo iniziare a creare un vero e proprio componente aggiuntivo con Yeoman. Yeoman è uno strumento open source che facilita il processo di scaffolding. Per i componenti aggiuntivi di Office è possibile utilizzare un modello creato da Microsoft, spesso denominato “Yo Office”. 

Per ulteriori dettagli, consulta il seguente articolo: Componente aggiuntivo di Office Yeoman Generator.

Dopo aver seguito le istruzioni di configurazione, è necessario copiare il codice da Script Lab e incollarlo sul repositorio appena creato. Ci saranno altri elementi da configurare, ma si può iniziare da subito a eseguire “npm run start”. Questo aprirà Word e caricherà in automatico il tuo componente aggiuntivo. Puoi usare qualsiasi IDE per lo sviluppo, anche se il modello generato funziona meglio con gli editor di codice di Microsoft VS Code o Visual Studio. Per una migliore esperienza di programmazione e debug si consiglia di utilizzare Visual Studio.

3. Implementare l’API di DeepL

L’implementazione di DeepL nel componente aggiuntivo è molto semplice: uno script JavaScript chiama l’endpoint di traduzione del testo. Ciò è stato sufficiente per il nostro semplice prototipo. Se vuoi attivare Glossari nel tuo componente aggiuntivo, dovrai fare un po' più di lavoro.

Non abbiamo usato la libreria client ufficiale di DeepL per il progetto per il progetto perché non è pensata per il codice JavaScript lato client. Il motivo è la sicurezza: se chiamassi il codice lato client, esporresti la tua chiave API. Puoi dare un'occhiata al file GIST che abbiamo condiviso sopra per vedere il nostro approccio in modo più dettagliato (a partire dalla riga 102).

4. Eseguire il debug per gli utenti Mac 

Negli ultimi anni Microsoft ha iniziato a offrire molte delle sue applicazioni anche agli utenti Mac. Nonostante il sistema Mac sia adatto allo sviluppo tramite .NET Core, non funziona ancora perfettamente quando si tratta di programmare in un ambiente Windows e nelle applicazioni di Microsoft Office. Purtroppo le versioni per Mac delle applicazioni di Microsoft non sono configurate per facilitare il debug. Tim è un utente fedele di Microsoft e pertanto non ha avuto problemi. Marvin, invece, utilizza principalmente Mac e ha quindi dovuto scaricare Parallels per eseguire correttamente il debug del suo codice.  Esecuzione di Microsoft Office e Visual Studio Code in Parallels ti permette di fare il debug delle app e lavorare bene sul componente aggiuntivo. Non è una soluzione perfetta, ma funziona!

5. Condividere il componente aggiuntivo con altri utenti

I componenti aggiuntivi di Office vengono caricati nella visualizzazione web che viene eseguita nelle applicazioni di Office e vengono visualizzati utilizzando iFrames, quindi è necessario ospitarli su un server web a cui si ha accesso. Puoi trovare altre info su come distribuire e pubblicare i componenti aggiuntivi di Office nella documentazione Microsoft. 

Una volta che il componente aggiuntivo è attivo e funzionante, qualsiasi amministratore di Office può distribuire agli utenti e ai gruppi della propria organizzazione tramite il centro di amministrazione di Microsoft 365. I componenti aggiuntivi distribuiti tramite l’interfaccia di amministrazione sono disponibili da subito.

Bonus: Estendere il componente aggiuntivo ad altre applicazioni Microsoft 

Estendere il tuo nuovo componente aggiuntivo ad altre applicazioni è molto semplice. I componenti aggiuntivi di Office hanno molti elementi in comune e possono essere utilizzati in genere in tutte le applicazioni della stessa gamma, ovvero Outlook, Word, Excel, PowerPoint, Visio e OneNote.

Tuttavia, ogni applicazione presenta eventi differenti. Nel nostro esempio di Word, abbiamo usato OnTextSelected, mentre in Excel probabilmente useresti qualcosa come OnColumnSelected o Row. Per far funzionare il tuo componente aggiuntivo in altre app, aggiungi gli eventi o le azioni a cui vuoi che reagisca: è semplice. La maggior parte del codice può essere riutilizzata in tutte le altre applicazioni.  

In genere si consiglia di trasformare il codice in una funzione specifica, da riutilizzare e richiamare con le caratteristiche dell’applicazione desiderata. Ti consiglio di dare un'occhiata agli articoli disponibili qui.

Inoltre, c'è un bel modulo MS Learn che può essere utile.

In conclusione

Ci auguriamo che questo articolo sia stato utile! Se hai qualche domanda, non esitare a creare un ticket nel repository GitHub con lo snippet di Script Lab e facci sapere.  

Buon lavoro!