Vytvoření doplňku DeepL API pro Microsoft Office (za jediný den)

Jednou za měsíc se zaměstnanci DeepL účastní celofiremního Hack Friday, kde se věnují projektům mimo rámec své každodenní práce. Hack Fridays jsou skvělou příležitostí k experimentování s naším API a někdy se výsledky dostanou až k uživatelům. Náš nedávno vydaný skript Google Sheets-DeepL byl ve skutečnosti výsledkem projektu Hack Friday! Během Hack Friday v září 2022 vytvořili vývojář softwaru DeepL Marvin Becker a vývojářský evangelista Tim Cadenbach prototyp doplňku DeepL API pro Microsoft Word, který uživatelům umožňuje překládat pomocí DeepL přímo v dokumentu Word.

Zde si můžete prohlédnout, jak to funguje:

Proč nás tato integrace zajímala?

Obchodní komunikace je oblíbeným příkladem použití DeepL – překlady DeepL umožňují globální, vícejazyčnému pracovnímu týmu efektivně spolupracovat a zároveň zajistit bezpečnost citlivých firemních dat. Často slýcháme požadavky od zákazníků, kteří si chtějí vytvořit vlastní doplněk Office pomocí DeepL API a hledají zdroje, které jim pomohou začít. Chtěli jsme se z první ruky zjistit, co integrace vyžaduje, abychom mohli lépe odpovídat na dotazy našich zákazníků. 

V tomto příspěvku se podělíme o to, co jsme zjistili. Poskytneme vám také open-source kód, který vám pomůže rychleji rozběhnout váš projekt. Připraveni? Pojďme stavět! 

Tip 0 (volitelný): Udělejte si malý domácí úkol  

Pokud jste s rozhraním Office API nováčkem, doporučujeme přečíst si Porozumění rozhraní Office JavaScript API v dokumentaci společnosti Microsoft. Stručně řečeno, všechny produkty Office poskytují společné API s produktově specifickými API . Může být také užitečné prolistovat si tento tutoriál , než přejdete k tipu 1. 

Tip 1: Vytvoření prototypu pomocí Script Lab (nebo použijte náš) 

Script Lab je open-source projekt spravovaný společností Microsoft. Script Lab umožňuje experimentovat s API Office JavaScript, aniž byste museli opustit aplikace Excel, Outlook, Word nebo PowerPoint. Skriptovací laboratoř Repozitář GitHub obsahuje návod, který vám pomůže začít.

K vytvoření počátečního prototypu našeho doplňku jsme použili Script Lab, protože je to ideální způsob, jak rychle napsat kód a vidět ho v akci – a skládá se pouze z jediného souboru JavaScript, HTML a CSS.

Ačkoli tento první krok ještě není doplňkem, který můžete sdílet s členy týmu, dá vám představu o tom, co je možné s DeepL API a jaký uživatelská přívětivost budete moci s vaším doplňkem poskytnout.

Na začátku příspěvku jsme vám slíbili open-source kód! Script Lab nabízí nabídku importovat „úryvky“ jiných uživatelů, proto jsme zveřejnili zdrojový kód úryvku DeepL-Word, který jsme vytvořili, aby si ho mohl vyzkoušet kdokoli. Najdete jej na GitHubu zde.

Pokud chcete tento krok provést, budete také potřebovat API klíč DeepL. Můžete vytvořit účet zde.

Stačí kopírovat a vložit Gist YAML podle pokynů, vložit svůj API klíč DeepL do zástupného symbolu v řádku 32 a náš úryvek budete moci spustit několika kliknutími.

A to nejlepší? Úryvek ze Script Labu lze nastavit jako doplněk, takže veškerá práce, kterou ve Script Labu odvedete, se vám později bude hodit.

Tip 2: Vytvoření projektu doplněk Office pomocí generátoru Yeoman

Nyní, když jsme vytvořili několik prototypů v Script Lab a známe základy skriptování v Office, můžeme začít vytvářet skutečný doplněk pomocí Yeoman. Yeoman je open-source nástroj pro vytváření základů, který relativně usnadňuje vytváření nových projektů. Pro doplňky Office existuje předem připravená šablona od společnosti Microsoft, kterou můžete použít a která se často označuje jako „Yo Office“. 

Tento proces je popsán zde: Doplněk Office Yeoman Generator.

Po provedení pokynů k nastavení kopírovat kód ze Script Lab do nově vytvořeného úložiště. Je třeba nakonfigurovat ještě další věci, ale můžete začít hned spuštěním příkazu „npm run start”. Tím se spustí Word a automaticky se načte váš doplněk. K vývoji můžete použít libovolné IDE, ale generovaná šablona funguje nejlépe s vlastními editory kódu společnosti Microsoft, VS Code nebo Visual Studio. Pro lepší zážitek z programování a ladění doporučujeme používat Visual Studio.

Tip 3: Implementace DeepL API

Naše implementace DeepL je jednoduchá – skript JavaScript fetch volá koncový bod překladu textu. Pro náš jednoduchý prototyp to bylo dostačující. Pokud chcete povolit Glosáře ve svém doplňku, budete muset vynaložit trochu více úsilí.

Nepoužili jsme oficiální službu DeepL klientskou knihovnu Node.js protože tato knihovna není určena pro klientský JavaScriptový kód. Důvodem je bezpečnost – při volání kódu na straně klienta byste odhalili svůj API klíč. Podrobnější informace o našem přístupu najdete v souboru GIST, který jsme sdíleli výše (od řádku 102).

Tip 4: Ladění pro uživatele Mac 

V posledních letech společnost Microsoft vynaložila značné investice, aby podpořila uživatele počítačů Mac. Ačkoli je možné Mac podporovat vývoj .NET Core, stále není dostatečný pro základní vývoj Windows, včetně aplikací Microsoft Office. Bohužel, verze aplikací Microsoft pro uživatele Mac nejsou nakonfigurovány pro snadné ladění. Tim je věrný fanoušek Microsoftu (a MVP!), takže neměl žádné problémy, ale uživatelka Macu Marvin si musela provést stažení Parallels, aby mohla správně ladit.  Spouštění kódu Microsoft Office a Visual Studio v Parallels vám umožní ladit aplikace a správně pracovat s doplňkem. Není to stoprocentně dokonalé řešení, ale splní svůj účel!

Tip 5: Sdílení doplňku s uživateli

Doplňky Office se přidávají do webového zobrazení, které běží v aplikacích Office, a zobrazují se pomocí iFrames, takže je budete muset hostovat na webovém serveru, ke kterému máte přístup. Více informací o nasazení a publikování doplňků Office najdete v Dokumentaci společnosti Microsoft. 

Jakmile máte doplněk nainstalovaný a spuštěný, může jej kterýkoli správce Office nasadit uživatelům a skupinám ve své organizaci prostřednictvím centra správy Microsoft 365. Doplňky nasazené prostřednictvím centra pro správu jsou ihned k dispozici.

Bonus: Rozšíření vašeho doplňku na další aplikace společnosti Microsoft 

Rozšíření doplňku na jiné aplikace je snadné. Doplňky Office sdílejí mnoho komponent a doplněk pro jednu aplikaci by měl fungovat ve všech podporovaných aplikacích (Outlook, Word, Excel, PowerPoint, Visio a OneNote).

Všechny aplikace však mají různé události. V našem příkladu pro Word jsme použili OnTextSelected, zatímco v Excelu byste pravděpodobně použili něco jako OnColumnSelected nebo Row. Aby váš doplněk fungoval v jiných aplikacích, přidejte odpovídající události nebo akce, na které má váš doplněk reagovat – je to tak jednoduché. Většinu vašeho kódu lze znovu použít v různých aplikacích.  

Obecně se doporučuje převést konkrétní kód na funkci, kterou lze znovu použít a vyvolat s konkrétními parametry Aplikace, které potřebujete. Doporučujeme přečíst si články, které jsou k dispozici zde.

K dispozici je také pěkný modul MS zjistit , který vám může pomoci.

Závěr

Doufáme, že vám tento přehled pomohl! Pokud máte nějaké dotazy, neváhejte vytvořit záznam v repozitáři GitHub s úryvkem Script Lab a dejte nám vědět.  

Přejeme vám vše nejlepší na vaší cestě s DeepL API a Microsoft Office.