Você está montando um engine de localização. E o engine que traduz bem não é o vazio — é o que traz a voz da sua marca, seu glossário e suas instruções, para que cada tradução soe como o seu produto e nunca distorça um termo que você já padronizou.
Esse conhecimento normalmente já existe antes do engine. Ele está em uma página de diretrizes da marca, em um guia de estilo, em uma planilha de terminologia, em alguns parágrafos de regras que um tradutor recebeu um dia. Montar o engine manualmente significa ler tudo isso e cadastrar cada item como registros de voz da marca, glossário e instrução, um por um — um trabalho tedioso, fácil de começar e fácil de deixar pela metade.
A API de provisionamento assíncrono resolve essa lacuna: aponte para o que você já tem. Você faz um POST com links e texto bruto em uma única solicitação, recebe um ID de engine na hora, e um agente de IA rastreia as fontes, extrai vozes da marca, itens de glossário e instruções, e aplica cada um ao novo engine à medida que encontra. O engine já pode ser usado assim que você recebe o ID — a configuração vai sendo preenchida enquanto o job é executado.
Nesta página
O problema#
Um engine de localização só é tão bom quanto sua configuração. Escolher o modelo entrega uma tradução; vozes da marca, itens de glossário e instruções são o que fazem essa tradução refletir a forma como seu produto já se comunica — o nível de formalidade que você escolheu, os nomes de produto que nunca são traduzidos, o formato de data que você sempre usa. São os mesmos elementos que, de outra forma, você criaria manualmente: vozes da marca, itens de glossário e instruções em um engine.
O ponto é que tudo isso já existe em algum lugar. Uma equipe que já lançou um produto em um idioma tem uma página de diretrizes da marca, um guia de estilo, um glossário de termos que os agentes de suporte foram orientados a nunca traduzir. Para configurar o engine manualmente, você lê esses documentos e os transforma em registros — decisão por decisão, idioma por idioma. É um processo lento, e a parte mais demorada é a menos interessante: copiar para outro formato um conhecimento que já está documentado.
O provisionamento elimina essa etapa. Você entrega à plataforma os próprios documentos — como URLs para rastrear ou como texto bruto — e um agente de IA faz a leitura e a transcrição. Ele cria para você os registros de voz da marca, glossário e instrução, em um engine real, aplicando cada um deles à medida que são identificados. Depois, você faz a revisão e os ajustes no dashboard, da mesma forma que faria com qualquer coisa criada manualmente. O ponto de partida é um engine configurado, não um engine em branco.
O provisionamento configura um engine; não faz traduções.
Esta API cria e configura o engine. Para traduzir com o engine depois que ele existir, use a API de localização assíncrona para vários idiomas de uma vez, ou o endpoint síncrono Localize para um único par de idiomas. O provisionamento é a etapa de configuração que faz essas chamadas já levarem a voz da sua marca e o seu glossário desde a primeira tradução.
Como funciona#
São três etapas, e só a primeira acontece dentro da sua solicitação. As outras duas rodam na plataforma, no tempo dela — por isso a chamada retorna na hora e o engine já pode ser usado antes de o trabalho terminar.
Envie suas fontes
Envie via POST um nome para o novo engine e um array de fontes — URLs para rastrear, texto bruto para analisar, ou ambos — para /jobs/provisioning. A API cria o engine imediatamente e retorna 202 com o ID do engine (eng_) e o ID do job (pjb_). Sua aplicação pode seguir em frente; nada na resposta espera a extração terminar. Consulte Create a provisioning job para ver o formato completo de solicitação e resposta, e Source types para entender o que vale a pena enviar como fonte.
O agente de IA rastreia e extrai
Fontes de link são rastreadas em paralelo e convertidas em texto; conteúdo bruto é lido diretamente. Depois, um agente de IA analisa tudo e extrai três tipos de configuração — vozes da marca, itens de glossário e instruções — aplicando cada um ao engine à medida que são identificados. Uma fonte que falha no rastreamento, ou um item isolado que não pode ser criado, não interrompe o restante. What the AI extracts mostra os três componentes e como eles são mapeados para idiomas.
O engine está pronto
Quando a extração termina, o engine está totalmente configurado e pronto para traduzir pela Localization API. A plataforma informa a conclusão — com um resumo de tudo o que foi criado — para sua webhook URL, ou em tempo real pelo job's WebSocket se você quiser exibir o progresso enquanto ele roda.
O ID do engine pode ser usado imediatamente.
O ID eng_ em 202 já é um engine real no instante em que você o recebe. Você pode armazená-lo, referenciá-lo e traduzir com ele imediatamente — a configuração é aplicada enquanto o job roda, então uma tradução feita no início vê menos registros extraídos do que outra feita depois que o job termina. Você nunca precisa esperar o provisionamento para começar a usar o engine.
Autenticação
Toda solicitação — REST e WebSocket — é autenticada com seu cabeçalho X-API-Key. As chaves têm escopo de organização e dão acesso a todos os engines da org. Consulte Authentication para os detalhes e API Keys para criar uma.
O que você recebe de volta#
Um leitor cético já está fazendo as duas perguntas que determinam se isso é seguro para usar em produção: e se uma fonte for ruim, e isso é uma caixa-preta que eu não consigo corrigir?
Nenhuma dessas respostas fica escondida. O provisionamento não retorna um blob proprietário — ele cria registros comuns de voz da marca, glossário e instrução em um engine real, exatamente os mesmos objetos que você criaria manualmente, todos editáveis depois no dashboard. Quando o job termina, ele devolve um resumo com cada registro criado e cada falha encontrada, para que você possa confirmar a configuração em vez de simplesmente confiar nela. What the AI extracts mostra esse resumo e como um item com falha é isolado em uma lista errors, enquanto o restante do engine continua sendo configurado.
As fontes também são opcionais. Envie um nome sem sources e você recebe um engine limpo, com a configuração padrão, para ajustar por conta própria — Create a provisioning job cobre esse caminho junto com o formato da resposta 202. O provisionamento é a forma de pular a configuração manual, não um pré-requisito para ter um engine.
Páginas genéricas geram configurações genéricas.
A configuração só é tão boa quanto o que você envia — diretrizes da marca e listas de terminologia dão ao agente algo concreto para extrair; uma homepage de marketing rende quase nada. Source types explica para onde apontar.
Essa é a troca que o provisionamento oferece: você investe uma solicitação e uma espera curta e, em troca, deixa de transcrever um conhecimento que já documentou — aponte para o que você já tem e comece com um engine configurado. As páginas abaixo detalham cada parte dessa proposta.
