Está a criar um motor de localização. E o motor que traduz bem não é o vazio — é o que já traz a sua voz da marca, o seu glossário e as suas instruções, para que cada tradução soe ao seu produto e nunca deturpe um termo sobre o qual já tomou uma decisão.
Esse conhecimento normalmente já existe antes de o motor existir. Está numa página de diretrizes da marca, num guia de estilo, numa folha de terminologia, em alguns parágrafos de regras que um tradutor recebeu em tempos. Criar o motor à mão significa ler tudo isso e voltar a introduzi-lo como registos de voz da marca, glossário e instrução, um de cada vez — trabalho moroso, fácil de começar e fácil de deixar a meio.
A API de provisionamento assíncrono elimina essa lacuna: aponte-a para o que já tem. Faz um POST com links e texto em bruto num único pedido, recebe de imediato um ID de motor, e um agente de IA percorre as fontes, extrai vozes da marca, itens de glossário e instruções, e aplica cada elemento ao novo motor à medida que o encontra. O motor pode ser usado desde o momento em que recebe o ID — a configuração vai sendo preenchida enquanto a tarefa decorre.
Nesta página
O problema#
Um motor de localização é tão bom quanto a sua configuração. A escolha do modelo dá-lhe uma tradução; vozes da marca, itens de glossário e instruções são o que faz com que essa tradução corresponda à forma como o seu produto já comunica — o grau de formalidade que escolheu, os nomes de produto que nunca traduz, o formato de data que usa sempre. Estes são os mesmos elementos base que, de outra forma, criaria manualmente: vozes da marca, itens de glossário e instruções num motor.
O problema é que tudo isso já existe algures. Uma equipa que lançou um produto numa língua tem uma página de diretrizes da marca, um guia de estilo, um glossário de termos que os agentes de suporte são instruídos a nunca traduzir. Para configurar o motor à mão, lê esses documentos e transpõe-os para registos — decisão a decisão, idioma a idioma. É lento, e a parte mais lenta é a menos interessante: copiar conhecimento que já está escrito para um formato diferente.
O provisionamento elimina essa etapa. Entrega à plataforma os próprios documentos — como URLs para rastrear ou como texto em bruto — e um agente de IA trata da leitura e da transcrição. Cria por si os registos de voz da marca, glossário e instrução, num motor real, aplicando cada um à medida que é identificado. Depois, revê e ajusta tudo no dashboard, da mesma forma que editaria qualquer coisa que tivesse criado por si. O ponto de partida é um motor configurado, não um motor vazio.
O provisionamento configura um motor; não traduz.
Esta API cria e configura o motor. Para traduzir com o motor depois de este existir, use a API de Localização assíncrona para muitos idiomas de uma só vez, ou o endpoint Localize síncrono para um único par de idiomas. O provisionamento é a etapa de configuração que faz com que essas chamadas reflitam a sua voz da marca e o seu glossário desde a primeira tradução.
Como funciona#
São três passos, e apenas o primeiro acontece dentro do seu pedido. Os outros dois decorrem na plataforma, ao seu próprio ritmo — por isso, a chamada devolve resposta de imediato e o motor pode ser usado antes de o trabalho estar concluído.
Submeta as suas fontes
Faça um POST com um nome para o novo motor e um array de fontes — URLs para rastrear, texto em bruto para analisar, ou ambos — para /jobs/provisioning. A API cria o motor de imediato e devolve 202 com o ID do motor (eng_) e o ID da tarefa (pjb_). A sua aplicação pode seguir em frente; nada na resposta fica à espera da extração. Consulte Criar uma tarefa de provisionamento para ver o formato completo do pedido e da resposta, e Tipos de fonte para saber o que faz com que uma fonte valha a pena ser submetida.
O agente de IA rastreia e extrai
As fontes com link são rastreadas em paralelo e convertidas em texto; o conteúdo em 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 motor à medida que é identificado. Uma fonte que falhe durante o rastreio, ou um único item que não possa ser criado, não impede o resto. O que a IA extrai explica os três componentes e a forma como são mapeados para os idiomas.
O motor está pronto
Quando a extração termina, o motor fica totalmente configurado e pronto para traduzir através da API de Localização. A plataforma comunica a conclusão — com um resumo de tudo o que foi criado — para o seu URL de webhook, ou em direto através do WebSocket da tarefa, se quiser mostrar o progresso enquanto esta decorre.
O ID do motor pode ser usado imediatamente.
O ID eng_ em 202 corresponde a um motor real no instante em que o recebe. Pode armazená-lo, referenciá-lo e traduzir com ele de imediato — a configuração é aplicada enquanto a tarefa decorre, por isso uma tradução feita cedo vê menos registos extraídos do que uma feita depois de a tarefa estar concluída. Nunca tem de esperar pelo provisionamento para começar a usar o motor.
Autenticação
Todos os pedidos — REST e WebSocket — são autenticados com o seu cabeçalho X-API-Key. As chaves têm âmbito de organização e dão acesso a todos os motores da org. Consulte Autenticação para os detalhes e Chaves de API para criar uma.
O que recebe de volta#
Um leitor cético já está a fazer as duas perguntas que determinam se é seguro depender disto: e se uma fonte for má, e será isto uma caixa negra que eu não consigo corrigir?
Nenhuma das respostas está escondida. O provisionamento não devolve um blob proprietário — cria registos normais de voz da marca, glossário e instrução num motor real, exatamente os mesmos objetos que criaria manualmente, todos editáveis depois no dashboard. Quando a tarefa termina, devolve um resumo que identifica cada registo que criou e cada falha que encontrou, para que possa confirmar a configuração em vez de simplesmente a assumir. O que a IA extrai explica esse resumo e como um item com falha é isolado numa lista errors, enquanto o resto do motor continua a ser configurado.
As fontes também são opcionais. Submeta um nome sem sources e obtém um motor limpo com as predefinições, para o configurar por si — Criar uma tarefa de provisionamento cobre esse caminho juntamente com o formato da resposta 202. O provisionamento é a forma de evitar a configuração manual, não um pré-requisito para ter um motor.
Páginas genéricas produzem configuração genérica.
A configuração é tão boa quanto aquilo que submete — diretrizes da marca e listas de terminologia dão ao agente algo concreto para extrair; uma homepage de marketing quase nada produz. Tipos de fonte explica para onde o deve apontar.
Esta é a troca que o provisionamento oferece: investe um pedido e uma curta espera e, em troca, evita transcrever conhecimento que já escreveu — aponte-a para o que já tem e comece com um motor configurado. As páginas abaixo desenvolvem essa ideia.
