A Universally tem duas APIs, e qual delas você precisa depende do que você está construindo. Uma traduz conteúdo, a outra gerencia sua conta. Ambas são documentadas com exemplos de requisições em tempo real em developer.universally.com.
As duas APIs
| API de Tradução | API de Plataforma | |
|---|---|---|
| Host | translator.universally.com |
api.universally.com |
| Referência | Abrir a especificação | Abrir a especificação |
| Para | transformar conteúdo em outro idioma | gerenciar projetos, idiomas, glossário e traduções armazenadas |
| Chave | a chave de API privada do projeto | uma chave de API do workspace |
| Usado por | o plugin do WordPress e sua própria integração | scripts e ferramentas em torno do painel |
Se você está substituindo o plugin do WordPress em outra plataforma, a API de Tradução é a que você deseja. A API de Plataforma serve para automatizar o painel, não para servir páginas.
Primeiro, crie um projeto
Um projeto é o que contém seu domínio, seu idioma de origem, seus idiomas de destino e suas chaves, portanto, ele vem antes de qualquer chamada de API. Duas maneiras de criar um.
No painel. Abra Novo Projeto. Selecione Sua Tecnologia atualmente oferece apenas WordPress: as outras opções exibem um selo Em Breve e não podem ser selecionadas. Isso não é problema para uma integração de API, pois a tecnologia apenas muda o que o painel mostra para você, não o que a API de Tradução aceita. Uma consequência a esperar: a tela Configurações de API do projeto continuará informando "Plugin Universally não detectado", pois para um projeto WordPress ele procura o plugin em seu domínio. Nada está errado e a tradução funciona independentemente.
Com a API de Plataforma. POST /sites cria um projeto com uma chave de workspace pak_ e recebe name, domain, sourceLanguage e tech. Use tech: "wordpress" para um site com um domínio, ou tech: "app" quando não houver domínio para fornecer. tech: "website" e o modo de subdomínio estão em beta fechado e são rejeitados no momento. Não envie um workspaceId: ele é obtido da chave.
curl -X POST https://api.universally.com/sites \
-H "X-API-Key: $UNIVERSALLY_PLATFORM_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Docs site","domain":"example.com","sourceLanguage":"en-us","tech":"wordpress"}'
Em seguida, adicione idiomas de destino, seja na tela Todos os Idiomas do projeto ou através da API de Plataforma, e copie a chave do projeto em Configurações de API.
A API de Tradução
Três endpoints, todos POST, todos autenticados com a chave privada do projeto em um cabeçalho X-API-Key:
| Endpoint | Envie-a |
|---|---|
/v1/translate/html |
uma página renderizada, quando você puder entregar o HTML completo |
/v1/translate/strings |
um array de strings, quando você mesmo detém o conteúdo |
/v1/translate |
ambos, e ele decide qual das opções acima se aplica |
O endpoint HTML é o mais próximo de como o plugin funciona: seu servidor envia a página que estava prestes a retornar e serve de volta o que recebe. Nada precisa saber com antecedência qual texto está na página. Veja a visão geral da API REST para as formas de requisição e resposta, e erros e limites da API para o que esperar quando um limite de palavras é atingido no meio de uma requisição.
curl -X POST https://translator.universally.com/v1/translate/html \
-H "X-API-Key: $UNIVERSALLY_KEY" \
-H "Content-Type: application/json" \
-d '{"html":"<html>...</html>","targetLanguage":"es","sourceUrl":"https://example.com/pricing/"}'
A API da Plataforma
Mesmo cabeçalho, chave diferente: uma chave de API de workspace, que começa com pak_. Ela alcança os mesmos endpoints que o painel usa, então pode adicionar idiomas, editar regras de glossário, ler traduções armazenadas e listar sites sem que ninguém clique na interface.
Crie um em Workspaces, depois API Keys. Veja Encontre sua chave de API.
O que você ainda precisa construir
O plugin faz mais do que chamar um endpoint, e nada disso é gratuito através da API:
- Servir URLs de idiomas. Algo precisa rotear
/es/pricing/para sua resposta em espanhol. Universally traduz o que você envia; ele não fica na frente do seu site. - Cache. Traduza uma vez e armazene o resultado. Reenviar a mesma página não gasta palavras novamente, já que uma string só é cobrada na primeira vez que é vista, mas cada requisição custa uma viagem de ida e volta e a latência que vem com ela.
- Detectar alterações. Reenvie uma página quando seu conteúdo mudar, caso contrário, os visitantes continuarão vendo a tradução antiga.
- O seletor de idiomas. O plugin envia um. Através da API, o markup é seu. Veja Crie um seletor de idiomas personalizado no WordPress para a forma dele.