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.
Envie o HTML de uma página e receba o mesmo HTML de volta com o texto traduzido. Este é o endpoint que o plugin WordPress usa, e o que deve ser usado para qualquer plataforma que possa renderizar uma página no lado do servidor.
Endpoint
POST https://translator.universally.com/v1/translate/html
X-API-Key: your_api_key_here
Content-Type: application/json
Solicitação
{
"html": "<html>...</html>",
"targetLanguage": "es",
"sourceUrl": "https://example.com/pricing/",
"parserMode": "auto"
}
| Campo | Obrigatório | Notas |
|---|---|---|
html |
sim | O documento completo, ou um fragmento. Não pode estar vazio. |
targetLanguage |
sim | Um dos códigos de variante configurados do projeto, como es, es-419 ou pt-br. Um código de região como es-mx é rejeitado |
sourceUrl |
sim | Deve ser uma URL válida, e seu domínio deve corresponder ao domínio do projeto |
parserMode |
não | auto ou classic. O padrão é auto. |
sourceUrl não é uma decoração. Ele identifica qual página está sendo traduzida para que o resultado possa ser armazenado e reutilizado, e é verificado em relação ao domínio do seu projeto. Uma incompatibilidade retorna TRANSLATION_SOURCE_URL_DOMAIN_MISMATCH.
Resposta
{
"success": true,
"data": {
"translatedHtml": "<html>...</html>",
"metadata": {
"siteId": "site_123",
"siteDomain": "example.com",
"sourceLanguage": "en",
"targetLanguage": "es",
"sourceUrl": "https://example.com/pricing/",
"stringsExtracted": 142,
"stringsTranslated": 142,
"limitReached": false,
"skippedStrings": 0
}
},
"code": "DATA_FETCHED"
}
Sirva translatedHtml para o visitante. Os metadados são para seu próprio registro e valem a pena registrar:
limitReached é true quando o projeto já estava no limite ou acima do total de palavras quando a solicitação chegou. Você ainda recebe HTML válido e um código 200, com texto no idioma original onde uma nova tradução teria sido necessária. Veja Limites de uso.
skippedStrings conta o que foi deixado sem tradução. É o único sinal de omissão: é definido para o limite de palavras e nada mais. Regras de exclusão não aparecem aqui, pois o conteúdo excluído é removido antes que qualquer coisa seja extraída. Uma página inteiramente excluída retorna com todos os contadores em zero.
stringsExtracted contra stringsTranslated rotineiramente diferem, e uma lacuna por si só não significa que algo estava errado. Texto aparecendo em mais de um lugar (um <title> que também é um og:title e um headline JSON-LD), strings que são omitidas como intraduzíveis (uma URL simples, um endereço de e-mail, um número, um único caractere) e qualquer coisa que o limite de palavras omitiu explicam isso.
targetLanguage ecoa a variante que você enviou, normalizada para minúsculas. Ela é comparada exatamente com as variantes configuradas do projeto em vez de ser resolvida a partir de uma região, que é o motivo pelo qual es-mx retorna TRANSLATION_TARGET_LANGUAGE_NOT_ALLOWED enquanto es-419 funciona. Veja Variantes de idioma e segmentação regional.
Solicitações compactadas
Defina Content-Encoding: gzip e envie o corpo compactado. O limite de tamanho conta os bytes que você envia, então compactar é o que permite que um documento grande passe.
Limites
O corpo da solicitação não pode exceder 5 MB como enviado, que é o tamanho compactado quando você usa gzip. Acima disso, retorna REQUEST_TOO_LARGE com status 413. Veja Erros e limites da API.
Cache do seu lado
A resposta é armazenada do nosso lado, então uma solicitação repetida para a mesma página e idioma é rápida e não gasta palavras novamente. Ainda é uma viagem de ida e volta pela rede.
Armazene em cache o HTML traduzido em sua própria camada, como faz o plugin do WordPress. Essa é a diferença entre uma página rápida e uma página razoavelmente rápida. Veja Desempenho e velocidade da página.
Quando uma página é excluída
Se o caminho corresponder a uma regra de Páginas Excluídas, o endpoint retornará com sucesso o HTML original em vez de um erro. Verifique os metadados se precisar distinguir os dois. Veja Excluir páginas.