Створення надбудови DeepL API для Microsoft Office (всього за один день)

Раз на місяць співробітники DeepL беруть участь у загальнокомпанійському Hack Friday, займаючись проектами, що не входять до їхніх повсякденних обов'язків. Hack Fridays — це чудова нагода попрацювати з нашим API, і іноді результати цієї роботи стають доступними для користувачів. Насправді, наш нещодавно випущений скрипт Google Sheets-DeepL був результатом проекту Hack Friday! Під час Hack Friday у вересні 2022 року розробник програмного забезпечення DeepL Марвін Бекер та розробник-євангеліст Тім Каденбах створили прототип надбудови DeepL API для Microsoft Word, що дозволило користувачам перекладати за допомогою DeepL безпосередньо в документі Word.

Ви можете побачити його в дії тут:

Чому нас зацікавила ця інтеграція?

Бізнес-комунікація є популярним випадком використання DeepL — переклади DeepL дозволяють міжнародному, багатомовному персоналу ефективно співпрацювати , зберігаючи конфіденційність важливих даних компанії. Ми часто отримуємо запити від клієнтів, які хочуть створити власну надбудову Office за допомогою DeepL API і шукають ресурси для початку роботи. Ми хотіли з перших рук дізнатися, що потрібно для інтеграції, щоб мати змогу надавати кращі відповіді на запитання наших клієнтів. 

У цій публікації ми поділимося тим, що ми дізналися. Ми також надамо відкритий код, щоб допомогти вам швидше розпочати свій проект. Готові? Давайте будувати! 

Порада 0 (опціонально): Зробіть невелике домашнє завдання  

Якщо ви тільки починаєте працювати з API Office, радимо прочитати «Розуміння Office JavaScript API» у Документації Microsoft. Коротко кажучи, всі продукти Office надають загальний API з специфічними для продукту API . Також може бути корисно переглянути цей підручник перед переходом до Поради 1. 

Порада 1: Створення прототипу за допомогою Script Lab (або використовуйте наш) 

Script Lab — це проект з відкритим кодом, який підтримується компанією Microsoft. Script Lab дає можливість експериментувати з Office JavaScript API, не виходячи з Excel, Outlook, Word або PowerPoint. Лабораторія сценаріїв Репозиторій GitHub містить підручник, який допоможе вам розпочати роботу.

Ми використовували Script Lab для створення початкового прототипу нашої надбудови, оскільки це ідеальний спосіб швидко написати код і побачити його в дії — і він складається лише з одного файлу JavaScript, HTML і CSS.

Хоча цей початковий крок ще не є надбудовою, яку ви можете поділитися з членами команди, він дає вам уявлення про те, що можна зробити за допомогою DeepL API і який користувацький досвід ви зможете забезпечити за допомогою своєї надбудови.

Раніше в цій публікації ми обіцяли вам відкритий код! Script Lab пропонує пропозицію імпортувати «фрагменти» інших користувачів, тому ми опублікували фрагмент DeepL-Word, який ми створили, у відкритому доступі, щоб кожен міг його випробувати. Ви можете знайти його в GitHub тут.

Вам також знадобиться ключ API DeepL, якщо ви хочете виконати цей крок. Ви можете зареєструватися тут.

Просто копіювати та вставляти Gist YAML, як зазначено в інструкціях, вставляти свій ключ API DeepL у місцезаповнювач у рядку 32, і ви зможете запустити наш фрагмент коду всього за кілька клацнувань.

А що найкраще? Фрагмент Script Lab можна перепрофілювати, встановлюючи шаблон надбудови, тому вся робота, яку ви виконуєте в Script Lab, стане в нагоді пізніше.

Порада 2: Створення проекту надбудови Office за допомогою генератора Yeoman

Тепер, коли ми створили кілька прототипів у Script Lab і ознайомилися з основами скриптів Office, можемо приступити до створення власне надбудови за допомогою Yeoman. Yeoman — це інструмент з відкритим кодом, який значно полегшує створення нових проектів. Для надбудов Office існує готовий шаблон від Microsoft, який ви можете використовувати, і який часто називають «Yo Office». 

Процес описаний тут: Nadбудова для Office Yeoman Generator.

Виконавши інструкції з налаштування, копіювати код із Script Lab до новоствореного репозиторію. Є ще що налаштувати, але ви можете одразу приступити до роботи, виконавши команду «npm run start». Це запустить Word і автоматично завантажить вашу надбудову. Ви можете використовувати будь-яку IDE для розробки, хоча генеруваний шаблон найкраще працює з власними редакторами коду Microsoft VS Code або Visual Studio. Для кращого кодування та налагодження ми рекомендуємо використовувати Visual Studio.

Порада 3: Впровадження DeepL API

Наша реалізація DeepL є простою — скрипт JavaScript fetch викликає кінцеву точку перекладу тексту. Для нашого простого прототипу цього було достатньо. Якщо ви хочете увімкнути глосарії у своїй надбудові, вам доведеться докласти трохи більше зусиль.

Ми не використовували офіційну DeepL клієнтська бібліотека Node.js для цього проекту, оскільки ця бібліотека не призначена для клієнтського JavaScript-коду. Причиною цього є безпека — ви б розкрили свій ключ API при виклику коду на стороні клієнта. Ви можете переглянути файл GIST, який ми поділилися вище, щоб детальніше ознайомитися з нашим підходом (починаючи з рядка 102).

Порада 4: Налагодження для користувачів Mac 

В останні роки компанія Microsoft зробила значні інвестиції, щоб підтримувати користувачів Mac. Хоча підтримувати Mac досить добре для розробки .NET Core, воно все ще недостатньо для розробки основних програм Windows, включаючи програми Microsoft Office. На жаль, версії програм Microsoft для користувачів Mac не налаштовані для простого налагодження. Тім є прихильником Microsoft (і MVP!), тому у нього не було жодних проблем, але користувач Mac Марвін повинен був завантажувати Parallels, щоб правильно налагодити роботу.  Виконання коду Microsoft Office та Visual Studio в Parallels дозволить вам налагоджувати програми та працювати з надбудовою належним чином. Це не 100% безпроблемне рішення, але воно виконує свою роботу!

Порада 5: Спільне використання надбудови з користувачами

Надбудови Office завантажуються у веб-перегляд, що працює в програмах Office, і відображаються за допомогою iFrames, тому вам потрібно розмістити їх на вебсервері, до якого ви маєте доступ. Ви можете дізнатися більше про розгортати та публікації надбудов Office у Документації Microsoft. 

Після запуску надбудови будь-який адміністратор Office може розгортати її для користувачів і груп у своїй організації через центр адміністрування Microsoft 365. Надбудови, розгортати через центр адміністрування, доступні для використання відразу ж.

Бонус: Розширення вашої надбудови до інших програм Microsoft 

Ваша надбудова легко додати до інших програм. Додатки Office мають багато спільних компонентів, і надбудова для однієї програми повинна працювати у всіх підтримуваних програмах (Outlook, Word, Excel, PowerPoint, Visio та OneNote).

Однак усі програми мають різні події. У нашому прикладі з Word ми використовували OnTextSelected, тоді як в Excel ви, ймовірно, використовували б щось на зразок OnColumnSelected або Row. Щоб ваша надбудова працювала в інших програмах, додайте відповідні події або дії, на які ви хочете, щоб ваша надбудова реагувала — все дуже просто. Більшість вашого коду можна повторно використовувати в різних програмах.  

Зазвичай рекомендується перетворити ваш конкретний код на функцію, яку ви можете повторно використовувати і викликати знову з урахуванням специфіки вашої програми. Рекомендуємо ознайомитися з статті, доступні тут.

Також є гарний модуль MS Дізнатися , який може допомогти.

Підсумовуючи

Сподіваємося, цей огляд був для вас корисним! Якщо у вас є питання, не соромтеся створити запит у репозиторії GitHub із фрагментом Script Lab і повідомте нас про це.  

Бажаємо вам успіхів у роботі з DeepL API-Microsoft Office.