Documentação Universally

Guias passo a passo, dicas de SEO multilíngue e melhores práticas para ajudar você a traduzir e escalar seu site WordPress.

Visão Geral da API REST

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 fornece dados de referência em nível de conta. Você não precisa dele para traduzir; ele suporta configuração e seleção de idioma.

Atualmente, isso é muito limitado para uso público.

Autenticação em resumo

Cada solicitação é autenticada com uma única chave de API enviada no cabeçalho X-API-Key. Sua chave é uma string de 64 caracteres emitida por site do seu painel Universally, e a mesma chave funciona em ambos os serviços. Como a chave pode gastar sua cota de tradução, mantenha-a no lado do servidor.

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.

Isso foi útil?