Tem uma string, ou um pequeno objeto de strings, que precisa de estar noutro idioma agora mesmo — uma etiqueta de formulário, uma notificação, um pequeno bloco de texto de UI que o utilizador está à espera de ver. Não quer configurar um endpoint de webhook nem fazer polling a um job para um único round-trip. Quer enviar o texto e receber a tradução de volta.
É para isso que serve o endpoint síncrono Localize: um pedido, dados traduzidos de volta com a mesma estrutura. Envia conteúdo de chave-valor por POST com um idioma de origem e um idioma de destino, a chamada fica bloqueada enquanto o seu motor traduz, e a resposta devolve o mesmo objeto com os valores traduzidos e a estrutura intacta. Não há nenhum job para acompanhar nem uma segunda chamada para fazer.
A tradução não é uma chamada genérica a um modelo. Passa pelo motor de localização que configurou — o seu glossário, a voz da marca, as instruções e a seleção de modelo por idioma — o mesmo motor que a API assíncrona usa. A diferença está apenas no formato: a async distribui um pedido por vários idiomas e entrega os resultados à medida que ficam prontos; esta chamada trata apenas de um par de idiomas e devolve o resultado inline.
Precisa apenas de um idioma e uma chamada bloqueante serve? Está na página certa.
Use este endpoint quando precisar de um único par de idiomas e puder esperar por um round-trip. Se tiver muitos idiomas de destino, conteúdo longo, ou quiser falhas isoladas por idioma, a API de Localização assíncrona recebe um pedido, devolve um 202 imediatamente e executa cada idioma como um workflow durável e independente em segundo plano. Há ainda outra diferença além da latência: o pipeline de localização — pré-edição, revisão humana, retrotradução e as restantes etapas opcionais — só corre em jobs assíncronos. Esta chamada síncrona ignora a configuração do pipeline.
Nesta página
Pedido#
POST /process/localizeAutentique-se com o cabeçalho X-API-Key. As chaves têm âmbito de organização e dão acesso a todos os motores da sua organização — consulte Autenticação para saber onde gerar uma, e Erros e códigos de estado para ver o modelo de erros completo.
| Parâmetro | Tipo | Descrição |
|---|---|---|
engineId | string (opcional) | O ID do motor de localização (eng_...). Usa o motor predefinido da sua organização se for omitido. |
sourceLocale | string | Idioma de origem BCP-47 (por exemplo, en). |
targetLocale | string | Idioma de destino BCP-47 (por exemplo, de). |
data | object | Conteúdo de chave-valor a traduzir. Objetos aninhados e arrays são suportados; a resposta reflete exatamente a estrutura que enviar. |
context | string (opcional) | Contexto geral para esta carga de tradução, como a área do produto, o público ou o objetivo. Aplica-se ao pedido inteiro. |
hints | object (opcional) | Pistas contextuais por chave. As chaves correspondem às chaves de data; os valores são arrays de strings breadcrumb (por exemplo, { "nav.home": ["Navbar", "Home link"] }) que dizem ao motor onde vive uma string, para desambiguar texto curto ou com múltiplos significados. |
{
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hello, world!",
"cta": "Get started"
},
"hints": {
"cta": ["Landing page", "Primary button"]
}
}Resposta#
A resposta devolve o conteúdo traduzido com a mesma estrutura que enviou, além do modelo que o produziu e do custo por pedido. As mesmas chaves regressam, com o mesmo nível de aninhamento — o seu código pode ler a tradução diretamente da estrutura que já conhece.
| Campo | Tipo | Descrição |
|---|---|---|
sourceLocale | string | Idioma de origem BCP-47, replicado do pedido. |
targetLocale | string | Idioma de destino BCP-47, replicado do pedido. |
data | object | Conteúdo de chave-valor traduzido, correspondente à estrutura de entrada. |
model | string (opcional) | Modelo LLM que produziu esta tradução, no formato provider/model (por exemplo, anthropic/claude-sonnet-4.5). Consulte-o para saber qual foi efetivamente o modelo executado na sua cadeia de fallback. Este campo não aparece quando não foi feita nenhuma chamada a um LLM — veja o callout abaixo. |
usage | object (opcional) | Contagem de tokens e custo por pedido em USD. Não aparece quando não foi feita nenhuma chamada a um LLM. |
O objeto usage discrimina o custo da chamada, para que possa atribuir a despesa sem precisar de uma consulta de faturação à parte:
| Campo | Tipo | Descrição |
|---|---|---|
inputTokens | number | Total de tokens de entrada consumidos em todos os chunks. |
outputTokens | number | Total de tokens de saída gerados em todos os chunks. |
cacheReadTokens | number | Tokens de entrada servidos a partir da cache de prompts do fornecedor, quando o modelo os reporta. |
cacheWriteTokens | number | Tokens de entrada escritos na cache de prompts do fornecedor, quando o modelo os reporta. |
llmCost | number | Custo do fornecedor LLM upstream em USD. 0 quando não tiver sido reportado qualquer custo. |
localizationCost | number | Custo por token da Lingo.dev em USD, calculado a partir de outputTokens. |
cost | number | Custo total do pedido em USD (llmCost + localizationCost). |
{
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hallo, Welt!",
"cta": "Jetzt starten"
},
"model": "anthropic/claude-sonnet-4.5",
"usage": {
"inputTokens": 2789,
"outputTokens": 861,
"cacheReadTokens": 0,
"cacheWriteTokens": 0,
"llmCost": 0.02129,
"localizationCost": 0.001722,
"cost": 0.023012
}
}Quando `model` e `usage` não aparecem
Se data estiver vazio — sem chaves para traduzir — o endpoint faz short-circuit sem chamar um LLM, e a resposta omite model e usage. Este é o único caso em que os campos de custo não aparecem, e a razão é simples: não houve custo. Nada foi traduzido, logo nada foi gasto. Todos os pedidos que acionam uma tradução incluem ambos os campos. Trate-os como opcionais no seu parser e o caso de entrada vazia não o apanhará de surpresa.
Exemplos#
A mesma chamada em cinco idiomas. Cada exemplo envia um objeto plano para maior clareza; data também aceita objetos aninhados e arrays, e a resposta volta na estrutura que enviar.
const response = await fetch(
"https://api.lingo.dev/process/localize",
{
method: "POST",
headers: {
"X-API-Key": "your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
engineId: "eng_abc123",
sourceLocale: "en",
targetLocale: "de",
data: {
greeting: "Hello, world!",
cta: "Get started",
},
}),
}
);
const { data } = await response.json();
// { greeting: "Hallo, Welt!", cta: "Jetzt starten" }O que acontece durante a localização#
Um único POST esconde uma sequência de etapas, e vale a pena saber quais são — porque são elas que garantem que o resultado fica consistente com o resto do seu conteúdo localizado, em vez de parecer um palpite isolado do modelo. Quando um pedido chega ao endpoint, o motor aplica toda a sua configuração pela ordem definida:
Seleção de modelo — Seleciona o modelo LLM com maior prioridade para o par de idiomas em causa. Os modelos específicos por idioma têm precedência sobre os modelos wildcard (
*). Se o modelo principal falhar, o motor passa automaticamente para o modelo seguinte na hierarquia.Voz da marca — Carrega a voz da marca para o idioma de destino, recorrendo à voz da marca wildcard se não existir uma específica para esse idioma.
Instruções — Carrega todas as instrução que correspondem ao idioma de destino, incluindo instruções wildcard.
Pesquisa no glossário — Divide os valores de entrada em chunks pesquisáveis, gera embeddings e executa uma pesquisa de similaridade vetorial no glossário do motor. Os termos encontrados impõem traduções exatas ou assinalam termos como não traduzíveis, para que passem inalterados.
Geração — Envia o prompt composto para o modelo selecionado e, em seguida, analisa e valida a resposta JSON.
Este é o mesmo pipeline de etapas do motor que a API assíncrona executa por job. Chamar sync em vez de async altera a forma de entrega, não a forma como a tradução é produzida — por isso, uma string traduzida aqui e a mesma string traduzida num job assíncrono chegam aos mesmos termos do glossário e à mesma voz.
O fallback de modelo é automático, e a resposta diz-lhe qual correu
Se o modelo principal falhar, o motor tenta o modelo seguinte por ordem de prioridade. Isto acontece de forma transparente — a estrutura da resposta é idêntica, independentemente do modelo que produziu a tradução. O único sinal de fallback é o campo model na resposta: consulte-o quando precisar de saber exatamente qual o modelo da sua cadeia que tratou um determinado pedido.
