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 Friday offrono una grande opportunità per sperimentare con l’API di DeepL e alcune volte i risultati di questi progetti raggiungono anche i nostri utenti. Un esempio recente di un progetto dell’Hack Friday è lo script per Google Sheets, realizzato per tradurre il contenuto delle celle tramite DeepL.
Nell’Hack Friday dello scorso settembre due dei nostri sviluppatori, Marvin Becker e Tim Cadenbach, hanno creato un componente aggiuntivo che utilizza l’API di DeepL per tradurre testi direttamente in un file di Microsoft Word.
Ecco una piccola anteprima:
Perché abbiamo deciso di lavorare su questo progetto?
Il servizio di DeepL è utilizzato principalmente nel contesto professionale, poiché permette a team internazionali e multilingue di collaborare in maniera efficiente mantenendo al sicuro le informazioni confidenziali dell’azienda. Dato che i nostri clienti ci chiedono spesso consigli su come creare un componente aggiuntivo per Microsoft Office con l’API di DeepL, 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. Forniremo anche codici open source per aiutarti a far decollare il progetto più rapidamente.
Iniziamo!
0. Fare un po’ di ricerca (opzionale)
Se sei alle prime armi con l’API di Office, ti consigliamo di leggere l’articolo Understanding the Office JavaScript API nella documentazione di Microsoft, che spiega come tutti i prodotti Office forniscono sia un’API comune che API specifiche per ogni prodotto.
Ti consigliamo di dare un’occhiata anche a questo tutorial prima di passare al prossimo step.
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. Il repositorio GitHub di Script Lab include un tutorial che ti aiuterà con i primi passi.
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, che puoi ottenere abbonandoti a DeepL Pro.
Dopodiché, dovrai copiare e incollare il Gist YAML (come indicato nelle nostre istruzioni), inserire la chiave di autenticazione nello spazio indicato alla riga 32 ed eseguire il frammento di codice.
Questo frammento può essere riutilizzato anche quando si configura il modello del componente aggiuntivo, quindi tutto il lavoro fatto su Script Lab può essere utile in futuro.
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: Create Office Add-in projects using the 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 comando avvierà Microsoft Word e caricherà automaticamente il componente aggiuntivo.
È possibile utilizzare qualsiasi IDE per lo sviluppo, anche se il modello fornito da Microsoft funziona meglio con i propri editor di codice, come 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 invece si vogliono attivare i glossari nel componente aggiuntivo, è necessario aggiungere alcuni passaggi.
Per il progetto non abbiamo utilizzato la libreria client Node.js ufficiale di DeepL perché non è stata pensata per il codice JavaScript dal lato client. Il motivo principale è la sicurezza: quando si effettua una chiamata dal lato client si rischia di esporre la chiave di autenticazione API.
Puoi dare un’occhiata al file GIST condiviso in precedenza per vedere il nostro approccio più in dettaglio (partendo 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.
Ti consigliamo pertanto di eseguire i codici di Office e Visual Studio in Parallels per un corretto debug delle applicazioni e un utilizzo ottimale del 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. Per saperne di più, dai un’occhiata a questo articolo della documentazione di Microsoft su come distribuire e pubblicare i componenti aggiuntivi di Office.
Una volta che il componente aggiuntivo è operativo, qualsiasi amministratore di Office può distribuirlo agli utenti e ai team della propria azienda tramite l’interfaccia 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 con Word abbiamo utilizzato “OnTextSelected”, mentre per Excel si dovrebbero utilizzare ad esempio “OnColumnSelected” o “Row”.
Per fare in modo che il componente aggiuntivo funzioni anche in altre app, è necessario aggiungere gli eventi o le azioni a cui vuoi che risponda il componente aggiuntivo. 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 consigliamo di leggere gli articoli disponibili cliccando su questo link e di dare un’occhiata a questo modulo di formazione.
In conclusione
Ci auguriamo che questo articolo sia stato utile! Se hai ulteriori domande, non esitare a creare un problema sul nostro repositorio GitHub con il frammento di Script Lab.
Buon lavoro!
