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. Hack Fridays to świetna okazja, aby poeksperymentować z naszym API, a czasami wyniki tych eksperymentów trafiają do użytkowników. W rzeczywistości nasz niedawno wydany skrypt Arkusze Google-DeepL był wynikiem projektu Hack Friday! Podczas Hack Friday we wrześniu 2022 r. programista DeepL Marvin Becker i ewangelista programistów Tim Cadenbach stworzyli prototypowy dodatek API DeepL dla programu Microsoft Word, umożliwiający 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ę?

Komunikacja biznesowa to popularny obszar zastosowań DeepL — tłumaczenia DeepL umożliwiają globalnej, wielojęzycznej kadrze pracowniczej wydajną współpracę , jednocześnie zapewniając bezpieczeństwo poufnych danych firmowych. Często otrzymujemy prośby od klientów, którzy chcą stworzyć własny dodatek do pakietu Office za pomocą API DeepL i szukają zasobów, które pomogą wam rozpocząć pracę. 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. Udostępnimy również kod open source, który pomoże ci szybciej rozpocząć realizację projektu. Gotowy na ? Zatem do dzieła! 

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

Jeśli nie masz jeszcze doświadczenia w korzystaniu z API pakietu Office, zalecamy przeczytanie artykułu Omówienie interfejsu API JavaScript pakietu Office w dokumentacji firmy Microsoft. Krótko mówiąc, wszystkie produkty pakietu Office zapewniają wspólny API z specyficznymi dla danego produktu API Pomocne może być również przejrzenie ten samouczek przed przejściem do wskazówki nr 1. 

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

Script Lab to projekt typu open source utrzymywany przez firmę Microsoft. Umożliwia on eksperymentowanie z interfejsem API Office JavaScript bez konieczności opuszczania programów Excel, Outlook, Word lub PowerPoint. Laboratorium scenariuszy Repozytorium GitHub 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. Możesz zarejestruj się w koncie tutaj.

Wystarczy kopiować i wkleić plik Gist YAML zgodnie z instrukcją, wstawić klucz API DeepL w miejscu oznaczonym symbolem zastępczym w wierszu 32, a następnie kliknąć kilka razy, aby uruchomić nasz 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 Dodatek do pakietu Office Yeoman Generator.

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”. Spowoduje to uruchomienie Worda i automatyczne załadowanie dodatku. Do tworzenia kodu możesz używać dowolnego środowiska IDE, chociaż wygenerowany szablon najlepiej działa z edytorami kodu firmy Microsoft, takimi jak 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 włączyć Glosariusze w swoim dodatku, musisz włożyć nieco więcej pracy.

Nie korzystaliśmy z oficjalnej biblioteki klienckiej DeepL dla biblioteka klienta Node.js , bo nie jest ona przeznaczona do kodu JavaScript po stronie klienta. Powodem jest bezpieczeństwo — podczas wywoływania kodu po stronie klienta ujawniłbyś swój klucz API. Możesz zapoznać się z plikiem GIST, który udostępniliśmy powyżej, aby bardziej szczegółowo zapoznać się z naszym podejściem (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.  Uruchamianie programu Microsoft Office i Visual Studio Code 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 uruchomić i publikacji dodatków do pakietu Office możesz przeczytać w dokumentacji firmy Microsoft. 

Po uruchomieniu dodatku każdy administrator pakietu Office może wdrożyć go dla użytkowników i grup w swojej organizacji za pośrednictwem centrum 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 dotyczącym programu Word używamy funkcji OnTextSelected, natomiast w programie Excel prawdopodobnie używalibyście funkcji OnColumnSelected lub Row. Aby dodatek działał w innych aplikacjach, dodaj odpowiednie zdarzenia lub działania, na które dodatek ma reagować — to takie prosty. 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. Zachęcamy do zapoznania się z artykuły dostępne tutaj.

Ponadto dostępny jest ciekawy moduł MS Learn , który może okazać się pomocny.

Podsumowanie

Mamy nadzieję, że nasz wpis Ci się przydał. Jeśli masz jakieś pytania, możesz utworzyć zgłoszenie w repozytorium GitHub wraz z fragmentem kodu Script Lab i poinformować nas o tym.  

Życzymy owocnej pracy!