Membuat add-in DeepL API untuk Microsoft Office (hanya dalam satu hari)

Setiap bulan, karyawan DeepL berpartisipasi dalam Hack Friday yang diadakan secara perusahaan, mengerjakan proyek-proyek di luar tugas harian mereka. Hack Fridays adalah kesempatan yang bagus untuk bereksperimen dengan API kami, dan terkadang hasilnya sampai ke pengguna. Sebenarnya, skrip Google Sheets-DeepL yang baru saja kami rilis merupakan hasil dari proyek Hack Friday! Pada Hack Friday pada September 2022, pengembang perangkat lunak DeepL Marvin Becker dan pengembang evangelist Tim Cadenbach membangun prototipe add-in DeepL API untuk Microsoft Word, sehingga pengguna dapat menerjemahkan langsung dalam dokumen Word menggunakan DeepL.

Anda dapat melihatnya beraksi di sini:

Mengapa kami tertarik pada integrasi ini?

Komunikasi bisnis merupakan salah satu penggunaan DeepL yang paling populer—terjemahan DeepL dapat memfasilitasi kolaborasi yang efisien di antara tenaga kerja global dan multibahasa sambil menjaga data perusahaan yang sensitif tetap aman. Kami sering menerima permintaan dari pelanggan yang ingin mengembangkan add-in Office mereka sendiri menggunakan DeepL API dan mencari sumber daya untuk memulai. Kami ingin mempelajari secara langsung apa saja yang diperlukan dalam proses integrasi agar kami dapat memberikan jawaban yang lebih baik ketika pelanggan kami menanyakan hal tersebut. 

Dalam posting ini, kami akan berbagi apa yang telah kami pelajari. Kami juga akan menyediakan kode sumber terbuka untuk membantu Anda memulai proyek Anda dengan lebih cepat. Siap? Ayo kita bangun! 

Tip 0 (optional): Lakukan sedikit pekerjaan rumah.  

Jika Anda baru mengenal Office API, kami sarankan untuk membaca Memahami Office JavaScript API dalam dokumentasi Microsoft. Singkatnya, semua produk Office menyediakan Common API dengan antarmuka pemrograman aplikasi (API) yang spesifik untuk masing-masing produk di atasnya. Mungkin juga berguna untuk membaca sekilas tutorial ini sebelum beralih ke Tip 1. 

Tips 1: Membuat prototipe dengan Script Lab (atau gunakan milik kami) 

Script Lab adalah proyek sumber terbuka yang dikelola oleh Microsoft. Script Lab memungkinkan Anda untuk bereksperimen dengan Office JavaScript API tanpa perlu meninggalkan Excel, Outlook, Word, atau PowerPoint. Laboratorium Skrip Repositori GitHub menyediakan tutorial untuk membantu Anda memulai.

Kami menggunakan Script Lab untuk membuat prototipe awal add-in kami karena ini merupakan cara ideal untuk menulis kode dengan cepat dan melihat hasilnya secara langsung—dan hanya terdiri dari satu file JavaScript, HTML, dan CSS.

Meskipun langkah awal ini belum bisa dibagikan sebagai add-in kepada anggota tim, langkah ini memberikan gambaran tentang apa yang dapat dilakukan dengan DeepL API dan jenis pengalaman pengguna yang dapat Anda berikan melalui add-in Anda.

Di bagian awal posting ini, kami telah berjanji akan memberikan kode sumber terbuka! Script Lab menawarkan cara untuk mengimpor "snippet" milik orang lain, jadi kami telah membuka sumber kode snippet DeepL-Word yang kami buat agar siapa pun dapat mencobanya. Anda dapat menemukannya di GitHub di sini.

Anda juga memerlukan API key DeepL jika ingin mengikuti langkah ini. Anda dapat daftar untuk membuat akun di sini.

Cukup salin dan tempelkan file Gist YAML sesuai petunjuk yang diberikan, masukkan API key DeepL Anda di tempat penanda pada baris 32, dan Anda dapat menjalankan potongan kode kami hanya dengan beberapa klik.

Bagian terbaiknya? Snippet Script Lab dapat dimodifikasi saat Anda mengatur templat add-in, sehingga semua pekerjaan yang Anda lakukan di Script Lab akan berguna di kemudian hari.

Tips 2: Membuat proyek add-in Office menggunakan Yeoman Generator

Sekarang setelah kita telah melakukan prototyping di Script Lab dan memahami dasar-dasar pemrograman Office, kita dapat mulai membuat add-in yang sebenarnya menggunakan Yeoman. Yeoman adalah alat scaffolding sumber terbuka yang memudahkan pembuatan proyek baru. Untuk add-in Office, ada templat siap pakai dari Microsoft yang dapat Anda gunakan, yang sering disebut sebagai "Yo Office". 

Proses ini dijelaskan di sini: Add-in Kantor Yeoman Hasilkan.

Setelah mengikuti petunjuk pengaturan, salin kode dari Script Lab ke repositori baru yang Anda buat. Ada lebih banyak pengaturan yang perlu dilakukan, tetapi Anda dapat mulai segera dengan menjalankan perintah 'npm run start'. Ini akan membuka Word dan secara otomatis menginstal add-in Anda. Anda dapat menggunakan IDE apa pun untuk pengembangan, meskipun templat yang dihasilkan bekerja paling baik dengan editor kode Microsoft sendiri, VS Code atau Visual Studio. Untuk pengalaman pemrograman dan debugging yang lebih baik, kami merekomendasikan penggunaan Visual Studio.

Tips 3: Mengimplementasikan DeepL API

Implementasi DeepL kami sangat sederhana—skrip JavaScript fetch memanggil endpoint terjemahan teks. Untuk prototipe sederhana kami, itu sudah cukup. Jika Anda ingin mengaktifkan glosarium dalam add-in Anda, Anda perlu melakukan sedikit lebih banyak pekerjaan.

Kami tidak menggunakan perpustakaan klien Node.js resmi DeepL Node.js pustaka klien untuk proyek ini karena perpustakaan tersebut tidak dirancang untuk kode JavaScript sisi klien. Alasan di sini adalah keamanan—Anda akan mengekspos API key Anda saat memanggil kode klien. Anda dapat melihat berkas GIST yang kami bagikan di atas untuk melihat pendekatan kami secara lebih rinci (mulai dari baris 102).

Tips 4: Debugging untuk pengguna Mac 

Dalam beberapa tahun terakhir, Microsoft telah melakukan investasi yang signifikan untuk mendukung pengguna Mac. Meskipun dukungan Mac untuk pengembangan .NET Core cukup baik, dukungan tersebut masih belum memadai untuk pengembangan inti Windows—termasuk aplikasi Microsoft Office. Sayangnya, versi aplikasi Microsoft untuk pengguna Mac tidak dikonfigurasi untuk memudahkan proses debugging. Tim adalah penggemar setia Microsoft (dan MVP!), jadi dia tidak mengalami masalah apa pun, tetapi pengguna Mac Marvin perlu unduh Parallels untuk melakukan debugging dengan benar.  Menjalankan Microsoft Office dan Visual Studio Code di Parallels akan memungkinkan Anda untuk mendebug aplikasi dan bekerja pada add-in dengan benar. Ini bukan solusi yang 100% sempurna, tapi tetap bisa menyelesaikan tugasnya!

Tips 5: Membagikan add-in Anda kepada pengguna

Add-in Office dimuat ke dalam tampilan web yang berjalan di aplikasi Office dan ditampilkan menggunakan iFrames, jadi Anda perlu menghostingnya di server web yang dapat Anda akses. Anda dapat membaca lebih lanjut tentang cara menerapkan dan menerbitkan Office Add-in di dokumentasi Microsoft. 

Setelah add-in tersebut berjalan dengan baik, administrator Office dapat menerapkan add-in untuk pengguna dan grup di organisasi mereka melalui Pusat Admin Microsoft 365. Add-in yang diterapkan melalui Pusat Admin dapat digunakan segera.

Bonus: Memperluas add-in Anda ke aplikasi Microsoft lainnya 

Mudah untuk memperluas add-in Anda ke aplikasi lain. Add-in Office berbagi banyak komponen, dan add-in untuk satu aplikasi seharusnya berfungsi di semua aplikasi yang mendukung (Outlook, Word, Excel, PowerPoint, Visio, dan OneNote).

Namun, semua aplikasi memiliki acara yang berbeda. Dalam contoh Word kami, kami telah menggunakan OnTextSelected, sedangkan di Excel Anda mungkin akan menggunakan sesuatu seperti OnColumnSelected atau Row. Untuk membuat add-in Anda berfungsi di aplikasi lain, tambahkan peristiwa atau tindakan yang sesuai yang ingin Anda respons dengan add-in Anda—se sederhana itu. Sebagian besar kode Anda dapat digunakan kembali di berbagai aplikasi.  

Secara umum, disarankan untuk mengubah kode spesifik Anda menjadi fungsi yang dapat Anda gunakan kembali dan panggil kembali dengan spesifikasi aplikasi yang Anda butuhkan. Kami menyarankan untuk membaca artikel-artikel artikel yang tersedia di sini.

Selain itu, ada modul MS Learn yang bagus modul MS pelajari yang dapat membantu.

Menutup

Kami harap Anda menemukan ringkasan ini bermanfaat! Jika Anda memiliki pertanyaan, silakan buat tiket di repositori GitHub dengan potongan kode Script Lab dan beritahu kami.  

Kami mengucapkan selamat dan semoga sukses dalam perjalanan Anda menggunakan DeepL API dengan Microsoft Office.