Traduzir strings

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 uma matriz de strings, receba um mapa do texto original para a tradução. Use isso quando você tiver texto em vez de uma página: uma interface de aplicativo, uma carga útil de CMS sem cabeça, cópia de e-mail ou notificações push.

Endpoint

POST https://translator.universally.com/v1/translate/strings
X-API-Key: your_api_key_here
Content-Type: application/json

Solicitação

{
  "strings": ["Add to cart", "Out of stock", "Free shipping over $50"],
  "targetLanguage": "de",
  "fresh": false
}

Campo	Obrigatório	Notas
strings	sim	Entre 1 e 500 entradas. Cada uma deve ser não vazia.
targetLanguage	sim	Um código de idioma ativado no projeto
novo	não	true ignora as traduções armazenadas e traduz novamente. O padrão é false.

Observe que não há sourceUrl aqui, ao contrário de Traduzir HTML. As strings não estão vinculadas a uma página.

Resposta

{
  "success": true,
  "data": {
    "translations": {
      "Add to cart": "In den Warenkorb",
      "Out of stock": "Nicht auf Lager",
      "Free shipping over $50": "Kostenloser Versand ab 50 $"
    },
    "metadata": {
      "sourceLanguage": "en",
      "targetLanguage": "de",
      "stringsReceived": 3,
      "stringsTranslated": 3,
      "limitReached": false,
      "skippedStrings": 0
    }
  },
  "code": "DATA_FETCHED"
}

translations é indexado pela sua string original, para que você possa procurar cada uma sem rastrear a ordem da matriz.

Lidar com chaves ausentes

Uma string que não foi traduzida é omitida de translations inteiramente. Procure cada chave com um fallback para o seu próprio texto:

const out = strings.map((s) => data.translations[s] ?? s);

Três coisas causam a ausência de uma chave:

• Nada para traduzir. Um número simples, um URL, um endereço de e-mail, um único caractere.
• O limite de palavras foi atingido. O espaço de trabalho já estava no limite ou acima dele quando a solicitação chegou, o que a resposta relata como limitReached: true com uma contagem de skippedStrings.
• Uma falha transitória ao traduzir esse lote.

Leia metadata para a forma do que aconteceu: stringsTranslated abaixo de stringsReceived significa que alguns estão ausentes.

Há um caso especial que se comporta de maneira diferente: se nada na solicitação foi traduzível, toda a entrada é repetida sem alterações. Não se baseie nisso, pois não se aplica assim que uma string for traduzível.

Deduplicação

Strings repetidas em uma solicitação são traduzidas uma vez. Enviar o mesmo rótulo cinquenta vezes custa uma tradução, portanto, não há necessidade de deduplicar antes de chamar.

Limites

500 strings por solicitação. Acima disso, a validação falha. Divida conjuntos maiores entre solicitações. O limite de corpo de 5 MB também se aplica aqui. Veja Erros e limites da API.

Regras de glossário se aplicam

As regras de glossário são aplicadas às strings da mesma forma que às páginas, portanto, um termo que você sempre ou nunca traduz se comporta de forma consistente em ambos os endpoints. Veja Regras de glossário.

Quando usar fresh

Deixe como false. As traduções armazenadas são retornadas instantaneamente e não custam nada.

fresh: true traduz a string novamente e retorna o novo texto sem armazená-lo, sendo assim uma prévia em vez de uma forma de alterar o que é servido. A próxima solicitação comum para essa string ainda retorna a tradução armazenada anteriormente. Como nada é armazenado, uma chamada fresh também não conta em seu total de palavras.

Para alterar o que é servido, salve a nova redação na tela Traduções. Veja Editar traduções manualmente.

Relacionado

• Traduzir HTML
• Autentique-se com a API
• Erros e limites da API