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 Hack Fridays são excelentes oportunidades para realizar experiências com a nossa API. E, algumas vezes, o resultado desses trabalhos acaba se tornando um produto ou uma funcionalidade nova. Por exemplo, o nosso recém-lançado script do Google Sheets foi o resultado de um projeto realizado em uma Hack Friday.

Em outra Hack Friday de setembro de 2022, Marvin Becker (desenvolvedor de softwares) e Tim Cadenbach (evangelista de TI) criaram um protótipo de suplemento da API do DeepL para Microsoft Word, permitindo que os usuários traduzam com o DeepL diretamente em um documento Word.

Confira como funciona na prática esse projeto:

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

O DeepL é utilizado amplamente no mundo dos negócios, permitindo que equipes internacionais e multilíngues colaborem de forma eficiente e garantam a proteção de dados confidenciais da empresa. Recebemos frequentemente pedidos de clientes que desejam desenvolver o seu próprio suplemento do Office com a API do DeepL e buscam 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 vamos disponibilizar um código aberto para lhe ajudar a iniciar seu projeto mais rapidamente.

Tudo pronto? Então, mãos à obra! 

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

Se estiver usando as APIs do Office pela primeira vez, sugerimos que consulte o artigo Entendendo a API JavaScript do Office na Documentação de Suplementos do Office, disponibilizada no site da própria Microsoft. Em resumo, todos os produtos Office fornecem uma API comum que é complementada com APIs específicas para cada produto.

Talvez seja útil dar uma olhada neste tutorial antes de passar para a Dica n.º 1. 

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

O Script Lab é um projeto de código aberto da Microsoft. Com esta ferramenta, é possível realizar experimentos no Office JavaScript API sem ter que sair do Excel, Outlook, Word, ou PowerPoint. O repositório do GitHub do Script Lab inclui um tutorial para lhe ajudar nos primeiros passos.

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. Se você ainda não tem uma chave, crie uma conta DeepL API Free ou DeepL API Pro .

Basta copiar e colar o Gist YAML conforme descrito nas instruções, inserir sua chave API do DeepL no espaço reservado na linha 32, e você poderá executar nosso snippet em 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: Criar projetos de suplemento do Office usando o Gerador Yeoman.

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". Esta ação vai iniciar o Word e carregar seu suplemento em sideload automaticamente.

Você pode utilizar qualquer IDE para a programação. Contudo, o modelo gerado funciona melhor com os editores de código VS Code ou Visual Studio da Microsoft. 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 em seu suplemento, o processo pode ser um pouco mais demorado.

Neste projeto, não utilizamos a biblioteca de cliente Node.js oficial do DeepL, uma vez que essa biblioteca de código JavaScript não foi pensada para ser usada do lado do cliente. O motivo, neste caso, é por questões de segurança. Se fosse realizada uma chamada ao código do lado do cliente, sua chave da API estaria sendo exposta.

Você pode conferir o arquivo GIST que compartilhamos acima para visualizar nossa abordagem em mais detalhes (começando na 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. 

Por isso, aconselhamos que você execute códigos do Microsoft Office e Visual Studio no Parallels para que possa depurar aplicativos e trabalhar no suplemento corretamente. 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. Consulte a documentação da Microsoft se quiser saber mais sobre como implantar e publicar suplementos do Office.  

Quando seu suplemento estiver funcionando normalmente, qualquer administrador do Office poderá implementá-lo para os usuários e grupos da empresa, através 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. No nosso exemplo do Word, temos utilizado o evento "OnTextSelected". Já se você quiser trabalhar no Excel, provavelmente terá que utilizar algo como "OnColumnSelected" ou "Row".

Para fazer seu suplemento funcionar 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 a leitura dos artigos disponíveis neste link.

Este módulo do Microsoft Learn também é bastante útil e poderá ajudar.

Resumindo

Esperamos que este post seja útil para você! Caso tenha alguma dúvida, crie um pedido de suporte ("create an issue") no repositório do GitHub com o snippet do Script Lab e outras informações que achar relevantes.  

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