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.

Erros e limites da API

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.

Toda resposta usa o mesmo envelope, então um cliente ramifica no campo code em vez de apenas no status HTTP.

Envelope de resposta

Toda resposta, de sucesso ou erro, usa o mesmo envelope JSON:

{
  "success": false,
  "data": null,
  "message": "Invalid source URL format.",
  "code": "TRANSLATION_INVALID_SOURCE_URL"
}

Em caso de erro, success é false e data é null. Ramifique com base no campo code em vez da message legível por humanos, que pode mudar.

Códigos de erro

Código	HTTP	Significado
`CHAVE_DA_API_AUSENTE`	401	Nenhum cabeçalho `X-API-Key` foi fornecido.
`CHAVE_DA_API_FORMATO_INVÁLIDO`	401	A chave não tem um formato reconhecido.
`CHAVE_DA_API_MAL_FORMADA`	401	A chave não pôde ser analisada.
`CHAVE_DA_API_INVÁLIDA`	401	A chave está bem formatada, mas não é reconhecida.
`CHAVE_DA_API_PROJETO_INCOMPLETO`	500	O site associado a esta chave está mal configurado. Entre em contato com o suporte.
`PROJETO_NÃO_ENCONTRADO`	404	Nenhum site corresponde a esta chave.
`PROJETO_FOI_EXCLUÍDO`	404	O site foi excluído e não está mais acessível.
`URL_DE_ORIGEM_DE_TRADUÇÃO_INVÁLIDA`	400	`sourceUrl` não é uma URL válida.
`URL_DE_ORIGEM_DE_TRADUÇÃO_DOMÍNIO_INCOMPATÍVEL`	403	`sourceUrl` não corresponde ao domínio do seu site.
`IDIOMA_DE_ORIGEM_DE_TRADUÇÃO_IGUAL`	400	O idioma de destino é igual ao idioma de origem.
`IDIOMA_DE_DESTINO_DE_TRADUÇÃO_NÃO_PERMITIDO`	403	O idioma de destino não está configurado para o seu site, ou você enviou um código de região onde um código de variante é necessário.
`NENHUM_IDIOMA_DE_TRADUÇÃO_CONFIGURADO`	400	Nenhum idioma de destino está configurado para o site.
`SERVIÇO_DE_TRADUÇÃO_INDISPONÍVEL`	503	O serviço de tradução está temporariamente indisponível. Tente novamente com backoff.
`FALHA_NO_SERVIÇO_DE_TRADUÇÃO`	500	O serviço de tradução falhou ao processar a solicitação.
`NENHUM_CONTEÚDO_TRADUZÍVEL`	400	Nenhum conteúdo traduzível foi encontrado no HTML.
`ERRO_DE_VALIDAÇÃO`	400	O corpo da solicitação falhou na validação do esquema.
`JSON_INVÁLIDO`	400	O corpo da solicitação não é um JSON válido.
`ERRO_DE_DESCOMPACTAÇÃO`	400	Um corpo gzip não pôde ser descompactado.
`REQUISIÇÃO_MUITO_GRANDE`	413	O corpo da solicitação excede 5 MB.
`NÃO_ENCONTRADO`	404	Rota desconhecida.
`ERRO_SERVIDOR_INTERNO`	500	Erro inesperado do servidor. É seguro tentar novamente com backoff.

Limites de solicitação

Limite	Valor
Corpo máximo da solicitação	5 MB
Máximo de strings por solicitação	500 (endpoint de strings)
Métodos permitidos	`GET`, `POST`, `OPTIONS`

O limite de 5 MB se aplica aos bytes que você envia, então um corpo compactado com gzipt é medido compactado. Se for excedido, você recebe REQUEST_TOO_LARGE (413). Para páginas grandes ou conjuntos de strings grandes, compacte o corpo ou divida o trabalho em várias solicitações.

Corpos de solicitação compactados

O Translator aceita corpos de solicitação compactados com gzip. Defina o cabeçalho Content-Encoding como gzip e envie o JSON compactado; o corpo é descompactado antes da análise. Como o limite de tamanho conta os bytes que você envia, a compactação é o que permite que um documento várias vezes maior que 5 MB seja processado.

Content-Type: application/json
Content-Encoding: gzip

Se a descompactação falhar, a resposta será DECOMPRESSION_ERROR (400).

Solicitações cross-origin

O Translator retorna cabeçalhos CORS permissivos, permitindo solicitações de qualquer origem com os cabeçalhos Content-Type, X-API-Key e Content-Encoding. Mesmo assim, as solicitações carregam sua chave de API e devem ser enviadas do lado do servidor. Veja Autenticação.

Uso do plano e traduções parciais

A tradução consome o total de palavras do seu plano, compartilhado entre os endpoints HTML e de strings.

Exceder o limite não é um erro. Não há código de status para isso: um espaço de trabalho que excedeu o limite ainda recebe um 200, com a falta reportada nos metadados. O limite é verificado uma vez, quando a solicitação chega, então uma solicitação que começa abaixo do limite termina tudo o que precisa, mesmo que isso a leve além do total.

Campo	Significado
`limiteAtingido`	`true` quando o espaço de trabalho já estava no total de palavras ou acima dele quando a solicitação chegou.
`stringsIgnoradas`	O número de strings deixadas sem tradução por causa disso.

Quando limitReached é true, trate a resposta como parcial. Tudo o que já foi traduzido ainda é retornado do armazenamento; tudo o que teria precisado de uma nova tradução não é. No endpoint HTML, esse texto permanece no idioma original no documento retornado. No endpoint de strings, essas chaves estão ausentes do mapa translations, então use seu próprio texto de origem como fallback para qualquer chave que você não receba de volta. Veja Traduzir strings.

Aumente o total com um complemento de palavras ou um plano maior. Veja Limites de uso.

Retentativas

Para erros transitórios (TRANSLATION_SERVICE_UNAVAILABLE em 503, ou qualquer 5xx), retente com backoff exponencial. As traduções são armazenadas em cache, portanto, as solicitações retentadas que tiveram sucesso parcial anteriormente reutilizam o trabalho existente e traduzem apenas o que ainda está faltando. Não retente erros 4xx; eles indicam um problema com a solicitação que não se resolverá sozinho.

Isso foi útil?