Você tem uma string, ou um pequeno objeto com strings, que precisa estar em outro idioma agora mesmo — um rótulo de formulário, uma notificação, um bloco curto de texto de UI que o usuário está esperando. Você não quer configurar um endpoint de webhook nem ficar consultando um job para uma única ida e volta. Você quer enviar o texto e receber a tradução de volta.
É exatamente para isso que existe o endpoint síncrono de Localize: uma solicitação, dados traduzidos de volta no mesmo formato. Você faz POST de conteúdo em chave-valor com um idioma de origem e um de destino, a chamada fica bloqueada enquanto seu engine traduz, e a resposta devolve o mesmo objeto com os valores traduzidos e a estrutura intacta. Não há job para acompanhar, nem uma segunda chamada para fazer.
A tradução não é uma chamada genérica de modelo. Ela passa pelo engine de localização que você configurou — com seu glossary, sua voz da marca, suas instruções e a seleção de modelo por idioma — o mesmo engine que a API assíncrona usa. A diferença está apenas no formato: a API assíncrona distribui uma solicitação para vários idiomas e entrega os resultados conforme ficam prontos; esta chamada faz um único par de idiomas e retorna tudo inline.
Um idioma e uma chamada bloqueante resolvem? Então você está na página certa.
Use este endpoint quando você precisar de um único par de idiomas e puder esperar uma ida e volta. Se você tiver muitos idiomas de destino, conteúdo longo ou quiser isolar falhas por idioma, a API de localização assíncrona recebe uma solicitação, retorna um 202 imediatamente e executa cada idioma como um workflow durável independente em segundo plano. Há mais uma diferença além da latência: o pipeline de localização — pré-edição, revisão humana, retrotradução e outras etapas opcionais — roda apenas em jobs assíncronos. Esta chamada síncrona ignora a configuração do pipeline.
Nesta página
Solicitação#
POST /process/localizeAutentique-se com o cabeçalho X-API-Key. As chaves têm escopo de organização e dão acesso a todos os engines da sua organização — veja Authentication para saber onde gerar uma e Errors and status codes para o modelo completo de erros.
| Parâmetro | Tipo | Descrição |
|---|---|---|
engineId | string (opcional) | O ID do engine de localização (eng_...). Usa o engine padrão da sua organização se for omitido. |
sourceLocale | string | idioma de origem em BCP-47 (por exemplo, en). |
targetLocale | string | idioma de destino em BCP-47 (por exemplo, de). |
data | object | Conteúdo em chave-valor para traduzir. Objetos aninhados e arrays são compatíveis; a resposta espelha exatamente o formato que você 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 à solicitação inteira. |
hints | object (opcional) | Dicas contextuais por chave. As chaves correspondem às chaves de data; os valores são arrays de strings de breadcrumb (por exemplo, { "nav.home": ["Navbar", "Home link"] }) que informam ao engine onde cada string aparece, para desambiguar textos curtos ou ambíguos. |
{
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocale": "de",
"data": {
"greeting": "Hello, world!",
"cta": "Get started"
},
"hints": {
"cta": ["Landing page", "Primary button"]
}
}Resposta#
A resposta traz o conteúdo traduzido no mesmo formato que você enviou, além do modelo que o produziu e do custo por solicitação. As mesmas chaves voltam, com o mesmo aninhamento — seu código pode ler a tradução a partir da estrutura que já conhece.
| Campo | Tipo | Descrição |
|---|---|---|
sourceLocale | string | idioma de origem em BCP-47, repetido a partir da solicitação. |
targetLocale | string | idioma de destino em BCP-47, repetido a partir da solicitação. |
data | object | Conteúdo em chave-valor traduzido, no mesmo formato da entrada. |
model | string (opcional) | Modelo de LLM que produziu esta tradução, no formato provider/model (por exemplo, anthropic/claude-sonnet-4.5). Consulte esse campo para saber qual modelo da sua cadeia de fallback foi realmente usado. Ele fica ausente quando não há chamada de LLM — veja o callout abaixo. |
usage | object (opcional) | Contagem de tokens e custo por solicitação em USD. Fica ausente quando não há chamada de LLM. |
O objeto usage detalha o custo da chamada, para que você consiga atribuir o gasto sem precisar consultar o faturamento separadamente:
| 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 atendidos pelo cache de prompts do provedor, quando o modelo informa esses dados. |
cacheWriteTokens | number | Tokens de entrada gravados no cache de prompts do provedor, quando o modelo informa esses dados. |
llmCost | number | Custo do provedor upstream de LLM em USD. 0 quando nenhum custo for informado. |
localizationCost | number | Custo por token do Lingo.dev em USD, calculado a partir de outputTokens. |
cost | number | Custo total da solicitação 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 encerra o fluxo antecipadamente, 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 o motivo é simples: não houve custo. Nada foi traduzido, então nada foi cobrado. Toda solicitação que dispara uma tradução inclui os dois campos. Trate-os como opcionais no seu parser e o caso de entrada vazia não vai pegar você de surpresa.
Exemplos#
A mesma chamada em cinco idiomas. Para facilitar a leitura, cada exemplo envia um objeto simples; data também aceita objetos aninhados e arrays, e a resposta volta no mesmo formato que você 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 entendê-las, porque é isso que faz a saída ficar consistente com o restante do seu conteúdo localizado, em vez de parecer um palpite isolado de modelo. Quando uma solicitação chega ao endpoint, o engine aplica toda a sua configuração nesta ordem:
Seleção de modelo — Seleciona o modelo de LLM de maior prioridade que corresponda ao par de idiomas. Modelos específicos por idioma têm precedência sobre modelos curinga (
*). Se o modelo principal falhar, o engine passa automaticamente para o próximo modelo na ordem de prioridade.Voz da marca — Carrega a voz da marca para o idioma de destino e recorre à voz da marca curinga se não houver uma versão específica para esse idioma.
Instruções — Carrega toda instrução compatível com o idioma de destino, incluindo instruções curinga.
Busca no glossary — Divide os valores de entrada em chunks pesquisáveis, gera embeddings e executa uma busca por similaridade vetorial no glossary do engine. Os termos encontrados impõem traduções exatas ou marcam termos como não traduzíveis para que passem intactos.
Geração — Envia o prompt composto ao modelo selecionado e, em seguida, faz o parsing e a validação da resposta JSON.
Este é o mesmo pipeline de etapas do engine que a API assíncrona executa em cada job. Chamar a versão síncrona em vez da assíncrona muda o formato de entrega, não a forma como a tradução é produzida — então uma string traduzida aqui e a mesma string traduzida em um job assíncrono chegam aos mesmos termos do glossary e à mesma voz.
O fallback de modelo é automático — e a resposta mostra qual modelo rodou
Se o modelo principal falhar, o engine tenta o próximo modelo na ordem de prioridade. Isso acontece de forma transparente — o formato da resposta é idêntico independentemente de qual modelo produziu a tradução. O único sinal de que houve fallback é o campo model na resposta: consulte-o quando precisar saber exatamente qual modelo da sua cadeia atendeu uma solicitação específica.
