Microsoft Office için bir DeepL API eklentisi oluşturma

Ayda bir kez, DeepL çalışanları günlük işlerinin dışında projeler üstlenerek şirket çapında bir Hack Friday’e katılır. Hack Friday’ler API’mizi kurcalamak için harika bir fırsattır ve bazen sonuçlar kullanıcılara ulaşır. Aslında, yakın zamanda yayınlanan Google Sheets-DeepL betiğimiz bir Hack Friday projesinin sonucuydu!

Eylül 2022’deki bir Hack Friday’de, DeepL yazılım geliştiricisi Marvin Becker ve geliştirici evangelisti Tim Cadenbach, Microsoft Word için bir DeepL API eklentisi prototipi oluşturarak kullanıcıların DeepL ile doğrudan bir Word belgesinde çeviri yapmasını mümkün kıldı.

Eklentiyi burada çalışırken görebilirsiniz:

Bu entegrasyonla neden ilgilendik?

İş iletişimi popüler bir DeepL kullanım örneğidir -DeepL çevirileri, hassas şirket verilerini güvende tutarken küresel, çok dilli bir işgücünün verimli bir şekilde işbirliği yapmasını sağlayabilir. DeepL API ile kendi Office Eklentilerini oluşturmak isteyen ve başlamak için kaynak arayan müşterilerimizden sık sık talepler alıyoruz. Müşterilerimiz bize soru sorduğunda daha iyi yanıtlar verebilmek için bir entegrasyonun neleri gerektirdiğini ilk elden öğrenmek istedik.

Bu yazıda, öğrendiklerimizi paylaşacağız. Ayrıca projenizi daha hızlı bir şekilde hayata geçirmenize yardımcı olmak için açık kaynak kodu da sağlayacağız.

Hazır mısınız? Hadi inşa edelim!

İpucu 0 (isteğe bağlı): Küçük bir ev ödevi yapın

Office API’leri konusunda yeniyseniz, Microsoft’un belgelerindeki Office JavaScript API’sini Anlama bölümünü okumanızı öneririz. Kısacası, tüm Office ürünleri, üzerinde ürüne özel API’ler bulunan bir Ortak API sağlar.

İpucu 1’e geçmeden önce bu öğreticiye göz atmak da faydalı olabilir.

İpucu 1: Script Lab ile bir prototip oluşturma (veya bizimkini kullanın)
Script Lab, Microsoft tarafından sürdürülen açık kaynaklı bir projedir. Script Lab, Excel, Outlook, Word veya PowerPoint’ten ayrılmadan Office JavaScript API’si ile denemeler yapmayı mümkün kılar. Script Lab GitHub deposu, başlamanıza yardımcı olacak bir öğretici içerir.

Eklentimizin ilk prototipini oluşturmak için Script Lab’i kullandık çünkü hızlı bir şekilde kod yazmanın ve kodu çalışırken görmenin ideal bir yoludur ve yalnızca tek bir JavaScript, HTML ve CSS dosyasından oluşur.

Bu ilk adım henüz ekip üyeleriyle paylaşabileceğiniz bir eklenti olmasa da, DeepL API ile nelerin mümkün olabileceği ve eklentinizle ne tür bir kullanıcı deneyimi sağlayabileceğiniz konusunda size fikir verecektir.

Yazının başlarında size açık kaynaklı bir kod sözü vermiştik! Script Lab, başka birinin “snippet “ini içe aktarmanın bir yolunu sunuyor, bu nedenle herkesin deneyebilmesi için oluşturduğumuz DeepL-Word snippet’ini açık kaynaklı hale getirdik. GitHub’da buradan bulabilirsiniz.
Bu adımı takip etmek istiyorsanız bir DeepL API anahtarına da ihtiyacınız olacak. Buradan bir hesap için kaydolabilirsiniz.

Gist YAML’yi talimatlarda belirtildiği gibi kopyalayıp yapıştırın, DeepL API anahtarınızı 32. satırdaki yer tutucuya ekleyin ve sadece birkaç tıklamayla snippet’imizi çalıştırabileceksiniz.

En iyi kısmı mı? Script Lab parçacığı, eklenti şablonunu ayarlarken yeniden kullanılabilir, böylece Script Lab’da yaptığınız tüm çalışmalar daha sonra işinize yarayacaktır.

İpucu 2: Yeoman Generator ile bir Office Eklenti projesi oluşturma

Artık Script Lab’de biraz prototipleme yaptığımıza ve Office komut dosyası yazmanın temellerini bildiğimize göre, Yeoman’ı kullanarak gerçek bir eklenti oluşturmaya başlayabiliriz. Yeoman, yeni projeleri nispeten kolaylaştıran açık kaynaklı bir iskele aracıdır. Office Eklentileri için, Microsoft tarafından önceden hazırlanmış ve genellikle “Yo Office” olarak adlandırılan bir şablon vardır.

Süreç burada ele alınmıştır: Office Eklenti Yeoman Oluşturucu.

Kurulum talimatlarını izledikten sonra, kodu Script Lab’den yeni oluşturduğunuz depoya kopyalayın. Yapılandırılacak daha çok şey var, ancak ‘npm run start’ komutunu çalıştırarak hemen başlayabilirsiniz. Bu işlem Word’ü başlatacak ve eklentinizi otomatik olarak yan yükleyecektir.

Geliştirme için herhangi bir IDE kullanabilirsiniz, ancak oluşturulan şablon en iyi Microsoft’un kendi kod düzenleyicileri VS Code veya Visual Studio ile çalışır. Daha iyi bir kodlama ve hata ayıklama deneyimi için Visual Studio kullanmanızı öneririz.

İpucu 3: DeepL API’sinin Uygulanması

DeepL uygulamamız basittir – bir JavaScript getirme betiği metin çevirisi uç noktasını çağırır. Basit prototipimiz için bu yeterliydi. Eklentinizde sözlükleri etkinleştirmek istiyorsanız, biraz daha fazla çalışma yapmanız gerekecektir.

Proje için DeepL’un resmi Node.js istemci kütüphanesini kullanmadık çünkü bu kütüphane istemci tarafı JavaScript kodu için tasarlanmamıştır. Bunun nedeni güvenliktir – istemci tarafı kodunu çağırırken API anahtarınızı açığa çıkarırsınız.

Yaklaşımımızı daha ayrıntılı olarak görmek için yukarıda paylaştığımız GIST dosyasına bakabilirsiniz (102. satırdan itibaren).

İpucu 4: Mac kullanıcıları için hata ayıklama

Son yıllarda Microsoft, Mac kullanıcılarını desteklemek için önemli yatırımlar yaptı. Mac desteği .NET Core geliştirme için oldukça iyi olsa da, Microsoft Office uygulamaları da dahil olmak üzere temel Windows geliştirme için hala yeterince iyi değil. Ne yazık ki, Mac kullanıcıları için Microsoft uygulama sürümleri kolay hata ayıklama için yapılandırılmamıştır. Tim Microsoft’a sadık biri (ve MVP!), bu yüzden herhangi bir sorun yaşamadı, ancak Mac kullanıcısı Marvin’in düzgün bir şekilde hata ayıklamak için Parallels’i indirmesi gerekiyordu.

Microsoft Office ve Visual Studio kodunu Parallels’te çalıştırmak, uygulamalarda hata ayıklamanıza ve eklenti üzerinde düzgün çalışmanıza olanak tanır. Bu %100 sorunsuz bir çözüm değildir, ancak işinizi görür!

İpucu 5: Eklentinizi kullanıcılarla paylaşma

Office Eklentileri, Office uygulamalarında çalışan web görünümüne yüklenir ve iFrame’ler kullanılarak görüntülenir, bu nedenle erişiminiz olan bir web sunucusunda barındırmanız gerekir. Microsoft belgelerinde Office Eklentilerinin nasıl dağıtılacağı ve yayınlanacağı hakkında daha fazla bilgi edinebilirsiniz.

Eklentiyi hazırlayıp çalıştırdıktan sonra, herhangi bir Office yöneticisi Microsoft 365 yönetim merkezi aracılığıyla kuruluşundaki kullanıcılara ve gruplara dağıtabilir. Yönetim merkezi aracılığıyla dağıtılan eklentiler hemen kullanılabilir.

Bonus: Eklentinizi diğer Microsoft uygulamalarına genişletme
Eklentinizi diğer uygulamalara genişletmek kolaydır. Office Eklentileri birçok bileşeni paylaşır ve bir uygulamaya yönelik bir eklenti desteklenen tüm uygulamalarda (Outlook, Word, Excel, PowerPoint, Visio ve OneNote) çalışmalıdır.

Ancak, tüm uygulamaların farklı olayları vardır. Word örneğimizde OnTextSelected kullanırken, Excel’de muhtemelen OnColumnSelected veya Row gibi bir şey kullanırsınız.

Eklentinizin diğer uygulamalarda çalışmasını sağlamak için, eklentinizin tepki vermesini istediğiniz ilgili olayları veya eylemleri ekleyin; bu kadar basit. Kodunuzun çoğu uygulamalar arasında yeniden kullanılabilir.

Genellikle belirli kodunuzu yeniden kullanabileceğiniz ve ihtiyacınız olan uygulama özellikleriyle tekrar çağırabileceğiniz bir işleve dönüştürmeniz önerilir. Burada bulunan makaleleri okumanızı öneririz.
Ayrıca, yardımcı olabilecek güzel bir MS Learn modülü vardır.