Criando um suplemento da API do DeepL para o Microsoft Office (em apenas um dia)

Todos os meses, os funcionários do DeepL participam de um evento corporativo chamado "Hack Friday", no qual desenvolvem projetos fora do seu trabalho habitual. As sextas-feiras de hack são uma ótima oportunidade para você mexer na nossa API e, às vezes, os resultados chegam aos usuários. Na verdade, nosso script recém-lançado do Google Sheets-DeepL foi o resultado de um projeto da Hack Friday! Em uma Hack Friday em setembro de 2022, o desenvolvedor de software DeepL, Marvin Becker, e o evangelista de desenvolvedores Tim Cadenbach criaram um protótipo de suplemento da API do DeepL para o Microsoft Word, possibilitando que os usuários traduzam com o DeepL diretamente em um documento do Word.

Confira como funciona na prática esse projeto:

Por que isto é tão interessante para nós?

A comunicação empresarial é um caso de uso popular do DeepL - as traduções DeepL podem permitir que uma força de trabalho internacional e multilíngue colabore com eficiência e, ao mesmo tempo, manter a proteção de dados confidenciais da empresa. Frequentemente, recebemos solicitações de clientes que desejam criar seu próprio suplemento do Office com a API do DeepL e estão procurando recursos para começar. Por isso, nós mesmos decidimos criar nosso suplemento e, assim, entender melhor todas as questões envolvidas, bem como tentar esclarecer quaisquer dúvidas por parte dos clientes. 

Neste post, vamos compartilhar o que aprendemos com isso. Também forneceremos código-fonte aberto para ajudar você a iniciar seu projeto mais rapidamente. Ready? Então, mãos à obra! 

Dica 0 (opcional): faça uma pequena pesquisa antes de começar  

Se você não tem experiência com as APIs do Office, sugerimos que leia Entendendo a API JavaScript do Office na Documentação da Microsoft. Em resumo, todos os produtos do Office fornecem uma API comum com APIs específicas do produto específicas do produto. Também pode ser útil que você dê uma olhada neste tutorial. este tutorial antes de passar para a Dica 1. 

Dica 1: criar um protótipo com o Script Lab (ou utilizar o nosso) 

Script Lab é um projeto de código aberto mantido pela Microsoft. Com esta ferramenta, é possível realizar experimentos no Office JavaScript API sem ter que sair do Excel, Outlook, Word, ou PowerPoint. O laboratório de scripts repositório do GitHub inclui um tutorial para ajudar você a começar.

Utilizamos o Script Lab para criar um protótipo inicial do nosso suplemento, pois é um método ideal para escrever código rapidamente e para ver sua aplicação na prática, consistindo apenas em um único arquivo JavaScript, HTML e CSS.

Este passo inicial não consiste no suplemento em si que você poderá compartilhar com os membros da equipe, mas vai lhe dar uma ideia do que é possível alcançar com a API do DeepL e do tipo de experiência de usuário que você conseguirá proporcionar com o seu suplemento.

No início deste post, havíamos prometido um código aberto! O Script Lab oferece a possibilidade de importar snippets (fragmentos de código) criados por outra pessoa, por isso disponibilizamos o snippet que criamos para o Word para que qualquer um de nossos usuários possa experimentá-lo. Você pode encontrá-lo no GitHub, clicando aqui.

Para acessar a API do DeepL, você precisará de uma chave de autenticação. Você pode assinar uma conta aqui.

Basta copiar e colar o Gist YAML conforme descrito nas instruções, inserir sua chave de API do DeepL no espaço reservado na linha 32 e você poderá executar nosso snippet com apenas alguns cliques.

E o melhor de tudo: o snippet do Script Lab pode ser reutilizado quando você estiver configurando o modelo do suplemento. Assim, todo o trabalho que você fizer no Script Lab será útil mais tarde.

Dica 2: desenvolver um projeto de suplemento do Office com o Yeoman Generator

Agora que já fizemos alguns protótipos no Script Lab e conhecemos o básico da criação de scripts do Office, podemos começar a criar um suplemento real usando o Yeoman. O Yeoman é uma ferramenta de scaffolding em código aberto que permite criar novos projetos com mais facilidade. Para suplementos do Office, há um modelo pré-desenvolvido pela Microsoft que você pode usar, muitas vezes chamado de "Yo Office". 

Para saber mais detalhes, consulte este link: Adicionar suplemento do Office Yeoman Generator.

Após seguir as instruções de configuração, copie o código do Script Lab para o seu repositório recentemente criado. Há mais configurações para fazer, mas você já pode começar de imediato, ao executar o comando "npm run start". Isso iniciará o Word e carregará automaticamente o suplemento do DeepL. Você pode usar qualquer IDE para o desenvolvimento, embora o modelo gerado funcione melhor com os próprios editores de código da Microsoft, o VS Code ou o Visual Studio. Para uma melhor experiência de programação e depuração recomendamos a utilização do Visual Studio.

Dica 3: implementar a API do DeepL

A implementação do DeepL é bem simples: um script de busca de dados (fetch) em JavaScript chama o endpoint da tradução do texto. Para fins do nosso protótipo simples, isto foi suficiente. Se você quiser habilitar Glossários no seu suplemento, você precisará trabalhar um pouco mais.

Não usamos a biblioteca de cliente oficial do DeepL biblioteca de clientes Node.js oficial do para o projeto porque a biblioteca não se destina a código JavaScript do lado do cliente. O motivo aqui é a segurança - você exporia sua chave de API ao chamar o código do lado do cliente. Você pode consultar o arquivo GIST que compartilhamos acima para ver nossa abordagem em mais detalhes (a partir da linha 102).

Dica 4: depuração para usuários de Mac 

Nos últimos anos, a Microsoft vem fazendo investimentos significativos para disponibilizar suporte aos usuários de Mac. Embora o suporte para Mac seja bastante positivo em programação .NET Core, ainda não é suficientemente desenvolvido na programação dos componentes essenciais do Windows, incluindo os aplicativos do Microsoft Office. Infelizmente, as versões do aplicativo da Microsoft para usuários de Mac não estão configuradas para facilitar a depuração. Tim é usuário fiel de Microsoft e realizou a operação sem a menor dificuldade. Já Marvin, usuário de Mac, precisou baixar o Parallels para conseguir fazer a depuração sem problemas.  Executando o código do Microsoft Office e do Visual Studio no Parallels permitirá que você depure aplicativos e trabalhe no suplemento adequadamente. Não é uma solução 100% perfeita, mas funciona!

Dica 5: compartilhar seu suplemento com os usuários

Os suplementos para Office são carregados na exibição web utilizada nos aplicativos do Office e são exibidos através do iFrames. Sendo assim, você terá que hospedar seu suplemento em um servidor web ao qual você tenha acesso. Você pode ler mais sobre como implementar e publicar suplementos do Office na Documentação da Microsoft. 

Depois que você tiver o suplemento instalado e em execução, qualquer administrador do Office poderá implementá-lo para usuários e grupos em sua organização por meio do centro de administração do Microsoft 365. Os suplementos implementados através do centro de administração estão disponíveis para utilização imediata.

Dica bônus: estender o uso do seu suplemento para outros aplicativos Microsoft 

É fácil estender seu suplemento para outros aplicativos. Os suplementos do Office têm muitos componentes em comum. Por isso, é possível que o suplemento para um aplicativo funcione em todos os outros aplicativos compatíveis (Outlook, Word, Excel, PowerPoint, Visio, e OneNote).

Entretanto, lembre-se de que eventualmente você terá que fazer ajustes nos eventos ao mudar de um aplicativo para outro. Em nosso exemplo do Word, usamos OnTextSelected, enquanto no Excel você provavelmente usaria algo como OnColumnSelected ou Row. Para que seu suplemento funcione em outros aplicativos, adicione os eventos ou ações correspondentes aos quais você deseja que seu suplemento reaja - é simples assim. A maior parte do seu código pode ser reaproveitada nos demais aplicativos.  

Geralmente recomenda-se converter seu código específico em uma função que você possa reutilizar e chamar novamente com as especificações do aplicativo desejado. Sugerimos que você leia os artigos artigos disponíveis aqui.

Além disso, há um bom módulo do módulo do MS Learn que pode ajudar você.

Resumindo

Esperamos que este post seja útil para você! Se você tiver alguma dúvida, fique à vontade para criar um problema no repositório do GitHub com o snippet do Script Lab e nos informe.  

Desejamos que você tenha uma ótima experiência na integração da API do DeepL ao Microsoft Office.