Visão geral da API REST

Referência completa da API: developer.universally.com contém a especificação ativa para a API do Tradutor e a API da Plataforma, com todos os campos, códigos de status e exemplos de resposta. Esta página cobre o que vale a pena saber sobre isso.

Universally expõe uma API REST para traduzir conteúdo da web para mais de 110 idiomas. A API é agnóstica quanto à plataforma: qualquer sistema que possa fazer uma solicitação HTTPS pode enviar conteúdo e receber traduções de volta. O plugin oficial do WordPress é construído sobre esta mesma API, mas nada aqui é específico do WordPress.

Use a API quando quiser integrar a tradução diretamente em sua própria stack: um CMS personalizado, um frontend headless, um edge worker, um aplicativo móvel ou web, ou qualquer lugar onde o plugin não possa alcançar.

Mas como atualmente suportamos oficialmente apenas a integração com o WordPress, esta é mais uma visão geral da API que deve permitir a extensão do plugin.

Dois serviços

A API é dividida em dois hosts separados. Cada um possui um conjunto distinto de endpoints, então o host informa qual capacidade você está chamando.

Serviço de Tradução

https://translator.universally.com

É aqui que toda a tradução acontece. A maioria das integrações chama apenas este serviço.

Método	Endpoint	Descrição
POST	/v1/translate/html	Traduzir um documento HTML completo
POST	/v1/translate/strings	Traduzir um array de strings (URL não necessária)
POST	/v1/translate	Detecta automaticamente HTML ou strings do corpo da solicitação
GET	/health	Verificação de integridade (sem autenticação)

Serviço de API

https://api.universally.com

Este serviço é a API da Plataforma: ele gerencia projetos, idiomas e strings armazenadas de suas próprias ferramentas. Você não precisa dele para traduzir.

Autenticação em resumo

Cada solicitação é autenticada com uma chave de API enviada no cabeçalho X-API-Key, e existem dois tipos. O Tradutor usa a chave de 64 caracteres do seu projeto. A API da Plataforma usa uma chave de workspace que começa com pak_ e rejeita a chave do projeto. Como qualquer uma delas pode gastar suas palavras traduzidas, mantenha ambas no lado do servidor. Veja Autenticar com a API.

X-API-Key: your_api_key_here
Content-Type: application/json

Envelope de resposta

Cada endpoint retorna o mesmo envelope JSON, quer a solicitação seja bem-sucedida ou falhe:

{
  "success": true,
  "data": { },
  "message": "Human-readable message or null",
  "code": "MACHINE_READABLE_CODE"
}

• success é true para respostas 2xx e false para erros.
• data contém a carga útil em caso de sucesso e é null em caso de erro.
• code é um identificador estável e legível por máquina no qual você pode ramificar. Prefira-o em vez de analisar message.

HTML ou strings: qual endpoint devo usar?

O Translator oferece duas maneiras de traduzir, dependendo da forma do seu conteúdo.

Use /v1/translate/html quando tiver uma página renderizada. Você envia um documento HTML completo junto com sua URL canônica. Universally extrai todas as strings traduzíveis, incluindo texto do corpo, meta tags, dados Open Graph, dados estruturados, texto alternativo de imagem e atributos de formulário, traduz-os, localiza links e retorna o HTML reescrito. Esta é a escolha certa para páginas renderizadas no servidor e integrações de borda.

Use /v1/translate/strings quando tiver peças de texto discretas. Você envia um array de strings e recebe um mapa de texto original para traduzido. Nenhuma URL é necessária, então esta é a escolha certa para conteúdo que não está vinculado a uma página: conteúdo dinâmico carregado via AJAX, texto gerado pelo usuário, como comentários e avaliações, conteúdo de aplicativos, notificações push ou qualquer fragmento que seu pipeline de renderização produz dinamicamente.

Se você não tiver certeza, envie a solicitação para /v1/translate e o Universally a enviará para o manipulador correto com base no corpo que você fornecer.

Exemplos

Ambos os métodos de tradução residem no serviço Translator e se autenticam com sua chave de API no cabeçalho X-API-Key.

Traduzir HTML

Envie uma página renderizada e sua URL canônica; receba o documento traduzido de volta.

curl -X POST https://translator.universally.com/v1/translate/html \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<!DOCTYPE html><html><head><title>Welcome</title></head><body><h1>Hello world</h1></body></html>",
    "targetLanguage": "fr",
    "sourceUrl": "https://example.com/welcome"
  }'

Resposta:

{
  "success": true,
  "data": {
    "translatedHtml": "<!DOCTYPE html><html lang=\"fr\"><head><title>Bienvenue</title></head><body><h1>Bonjour le monde</h1></body></html>",
    "metadata": {
      "siteId": "site_123",
      "siteDomain": "example.com",
      "sourceLanguage": "en-us",
      "targetLanguage": "fr",
      "sourceUrl": "https://example.com/welcome/",
      "stringsExtracted": 2,
      "stringsTranslated": 2,
      "limitReached": false,
      "skippedStrings": 0
    }
  },
  "message": "Data retrieved successfully.",
  "code": "DATA_FETCHED"
}

Traduzir strings

Envie uma matriz de strings; receba um mapa do texto original para o traduzido. Nenhuma URL é necessária.

curl -X POST https://translator.universally.com/v1/translate/strings \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "strings": ["Welcome back", "Add to cart"],
    "targetLanguage": "fr"
  }'

Resposta:

{
  "success": true,
  "data": {
    "translations": {
      "Welcome back": "Bon retour",
      "Add to cart": "Ajouter au panier"
    },
    "metadata": {
      "sourceLanguage": "en-us",
      "targetLanguage": "fr",
      "stringsReceived": 2,
      "stringsTranslated": 2,
      "limitReached": false,
      "skippedStrings": 0
    }
  },
  "message": "Data retrieved successfully.",
  "code": "DATA_FETCHED"
}

Como o cache funciona

O Universally armazena em cache todas as traduções que produz, para que você nunca seja cobrado duas vezes pelo mesmo conteúdo.

• As traduções de HTML são armazenadas em cache por página e idioma. Solicitações repetidas para a mesma URL e idioma de destino retornam o resultado em cache instantaneamente, e apenas as strings alteradas recentemente são enviadas para tradução.
• As traduções de strings são armazenadas em cache por string individual. Uma vez que uma string é traduzida para um determinado idioma, ela é servida do cache em todas as solicitações futuras, não importa em qual página ou contexto ela apareça.

Você não precisa gerenciar isso. Envie seu conteúdo em cada solicitação e o Universally retornará as traduções em cache onde disponíveis e traduzirá apenas o que for novo.