Tworzenie dodatku DeepL API dla Microsoft Office (w jeden dzień!)

Każdego miesiąca pracownicy DeepL biorą udział w wydarzeniu pod nazwą „Hack Friday”, w ramach którego pracują nad projektami własnego pomysłu. Jest to idealna okazja do eksperymentowania z naszym interfejsem API. Czasami wyniki tych prac przynoszą korzyści również użytkownikom końcowym. Przykładem jest nasz skrypt DeepL dla Google Sheets, który stanowi rezultat działań w ramach Hack Friday.

We wrześniu 2022 r. pracownicy naszej firmy, Marvin Becker i Tim Cadenbach, stworzyli prototyp dodatku DeepL API dla Microsoft Word, który umożliwia użytkownikom tłumaczenie za pomocą DeepL bezpośrednio w dokumencie Word.

Tutaj możesz sprawdzić jego działanie:

Dlaczego postanowiliśmy opracować tę integrację?

Użytkownicy nierzadko wykorzystują DeepL do komunikacji biznesowej. Nasze tłumaczenia pozwalają im na współpracę globalną ponad barierami językowymi z zachowaniem maksymalnego bezpieczeństwa danych firmowych. Klienci często informują nas, że chcieliby zbudować swój własny dodatek do pakietu Office, aby móc tłumaczyć za pomocą interfejsu API DeepL. W tym celu szukają zasobów, które mogłyby im w tym pomóc. Ponieważ zależało nam na tym, aby poznać wymagania odnośnie integracji i tym samym jeszcze lepiej odpowiadać na ewentualne pytania naszych klientów, zabraliśmy się do pracy. 

W tym wpisie chcielibyśmy poinformować Cię o wszystkim, czego się dowiedzieliśmy. Postanowiliśmy także udostępnić kod open source, aby umożliwić Ci jeszcze szybszą realizację projektu.

Nie możesz się już doczekać? Zatem do dzieła! 

Wskazówka nr 0 (opcjonalna): czas na pracę domową!  

Jeżeli dopiero teraz rozpoczynasz przygodę z interfejsem API Office, sugerujemy zapoznanie się z artykułem Understanding the Office JavaScript API w dokumentacji firmy Microsoft. W skrócie: dla wszystkich produktów Office istnieją ogólne interfejsy API i interfejsy API specyficzne dla danego produktu.

Zanim przejdziesz do wskazówki nr 1, możesz również przeczytać ten poradnik. 

Wskazówka nr 1: tworzenie prototypu za pomocą Script Lab (lub korzystanie z naszego) 

Script Lab to projekt open source prowadzony przez firmę Microsoft. Umożliwia on eksperymentowanie z interfejsem API Office JavaScript bez konieczności opuszczania programów Excel, Outlook, Word lub PowerPoint. Repozytorium GitHub dla Script Lab zawiera samouczek, który pomoże Ci rozpocząć pracę.

My również wykorzystaliśmy Script Lab do stworzenia wstępnego prototypu naszego dodatku. Powód jest prosty: jest to idealne narzędzie do szybkiego pisania kodu i sprawdzania jego działania. W rezultacie powstał prototyp składający się z jednego pliku JavaScript, HTML i CSS.

Chociaż prototyp nie jest jeszcze rzeczywistym dodatkiem, który można udostępnić swojemu zespołowi, pokazuje on możliwości interfejsu API DeepL i daje wyobrażenie o komforcie użytkowania, jaki może zapewnić wspomniany dodatek.

Na początku tego wpisu obiecaliśmy Ci dostęp do kodu open source. Script Lab umożliwia importowanie fragmentów kodu udostępnionych przez innych, dlatego też opublikowaliśmy fragment kodu DeepL dla Worda, aby każdy mógł go wypróbować. Możesz go znaleźć na stronie GitHub.

Jeżeli chcesz przetestować fragment kodu, będziesz potrzebować klucza uwierzytelniającego do API DeepL. Jeżeli nie masz jeszcze u nas konta, możesz je założyć za darmo tutaj.

Skopiuj i wklej Gist YAML zgodnie z instrukcjami, a następnie wstaw klucz uwierzytelniający DeepL API w miejsce symbolu zastępczego w linii 32. Na koniec uruchom fragment kodu.

Z pewnością ucieszy Cię fakt, że fragment kodu ze Script Lab może być ponownie wykorzystany przy tworzeniu szablonu dla Twojego dodatku. Oznacza to, że wszystko, co zrobisz teraz w Script Lab, przyda się później.

Wskazówka nr 2: tworzenie projektu dodatku do Office’a za pomocą generatora Yeoman

Po wykonaniu prototypów w Script Lab i zapoznaniu się z podstawowymi informacjami na temat skryptów Office możesz zacząć tworzyć rzeczywisty dodatek przy użyciu Yeomana. Yeoman jest narzędziem typu open source, które ułatwia tworzenie nowych projektów. W przypadku dodatków do Office'a istnieje szablon udostępniany przez Microsoft, z którego można skorzystać. Jest on często określany jako „Yo Office”. 

Proces ten został opisany tutaj.

Po zakończeniu konfiguracji skopiuj kod ze Script Lab do swojego nowo utworzonego repozytorium. Jest jeszcze kilka innych rzeczy do skonfigurowania – możesz zacząć od razu za pomocą komendy „npm run start”. Uruchomi to program Word i automatycznie załaduje Twój dodatek.

Do kodowania można użyć dowolnego IDE (zintegrowanego środowiska programistycznego), ale pamiętaj, że w przypadku wygenerowanego szablonu najlepszym wyborem będą edytory kodu stworzone przez sam Microsoft, a mianowicie VS Code lub Visual Studio. Dla większej wygody podczas kodowania i debugowania polecamy Visual Studio.

Wskazówka nr 3: wprowadzenie do interfejsu API DeepL

Nasza implementacja DeepL jest prosta – skrypt JavaScript wywołuje punkt końcowy (tłumaczenie tekstu). Dla naszego prototypu jest to wystarczające. Jeśli chcesz wykorzystać w swoim dodatku funkcję Glosariusza, czeka Cię nieco więcej pracy.

W tym projekcie nie wykorzystaliśmy oficjalnej biblioteki klienckiej DeepL dla Node.js, ponieważ nie jest ona przeznaczona dla kodu JavaScript po stronie klienta. Powodem jest bezpieczeństwo: gdy wywołujesz kod po stronie klienta, automatycznie ujawniasz swój klucz uwierzytelniający API.

Zapoznaj się z plikiem GIST, który udostępniliśmy powyżej, aby uzyskać bardziej szczegółowy opis naszego sposobu postępowania (zacznij od linii 102).

Wskazówka nr 4: debugowanie dla użytkowników systemu Mac 

W ostatnich latach Microsoft poczynił znaczne inwestycje z myślą o użytkownikach systemu Mac. Mimo że system Mac jest dobrze przystosowany do .NET Core, to jednak używanie go do programowania dla Windowsa jest dość skomplikowane. W przypadku Microsoft Office niestety nie jest inaczej. W związku z tym nie jest możliwe łatwe usuwanie błędów w oprogramowaniu Microsoft dla Maca. Tim jest fanem Microsoftu, więc mógł bez problemu kontynuować pracę. Z kolei Marvin, który używa Maca, musiał debugować za pomocą aplikacji Parallels, którą pobrał specjalnie w tym celu. 

Uruchomienie kodu Microsoft Office i Visual Studio w Parallels umożliwi Ci debugowanie aplikacji i prawidłową pracę nad dodatkiem. Nie jest to rozwiązanie idealne, ale spełnia swoje zadanie!

Wskazówka nr 5: udostępnianie dodatku użytkownikom

Aplikacje Office posiadają widok sieciowy, w którym można załadować dodatki, a następnie wyświetlić je za pomocą iFrames. Oznacza to, że musisz przechowywać swoje dodatki na serwerze internetowym, do którego masz dostęp. Więcej informacji na temat ich wdrażania i publikowania znajdziesz w dokumentacji firmy Microsoft. 

Gdy dodatek będzie gotowy, administratorzy Office mogą udostępnić go użytkownikom i grupom w swojej organizacji za pomocą panelu administracyjnego Microsoft 365. Po opublikowaniu za pośrednictwem tego panelu będzie on gotowy do natychmiastowego użycia.

Bonus: dostosowywanie dodatku do innych aplikacji firmy Microsoft 

Możesz z łatwością rozbudować swój dodatek tak, aby umożliwić korzystanie z niego w innych aplikacjach. Dodatki Office mają wiele wspólnych komponentów, co oznacza, że jeżeli działają w jednej aplikacji, powinny również działać w innych (Outlook, Word, Excel, PowerPoint, Visio i OneNote).

Pamiętaj jednak, że zdarzenia w aplikacjach różnią się. W naszym przykładzie dla Worda użyliśmy zdarzenia „OnTextSelected”, ale w przypadku Excela prawdopodobnie bardziej odpowiednie byłoby np. „OnColumnSelected” lub „Row”.

Aby zapewnić prawidłowe działanie dodatku w innych aplikacjach, należy za każdym razem odpowiednio dostosować zdarzenia i akcje. Większość Twojego kodu może być ponownie wykorzystana w innych aplikacjach.  

Generalnie zaleca się, aby kod został przekształcony w konkretną funkcję, dzięki której będzie można użyć go ponownie. Zalecamy zapoznanie się z informacjami dostępnymi tutaj.

Microsoft stworzył również moduł edukacyjny, który może być dla Ciebie pomocny.

Podsumowanie

Mamy nadzieję, że nasz wpis Ci się przydał. Jeśli masz jakieś pytania, utwórz zgłoszenie w repozytorium GitHub z fragmentem kodu Script Lab.  

Życzymy owocnej pracy!