Está a criar um motor de localização. O motor que traduz bem não é o que está vazio — é o que incorpora a sua voz da marca, o seu glossário e as suas regras, para que cada tradução soe ao seu produto e nunca deturpe um termo sobre o qual já decidiu.
Esse conhecimento costuma existir antes do próprio motor. Está numa página de diretrizes da marca, num guia de estilo, numa folha de terminologia, nalguns parágrafos de regras que um tradutor recebeu algures no passado. Construir o motor à mão implica ler tudo isso e voltar a introduzi-lo como registos de voz da marca, glossário e regras, um a um — um trabalho moroso, fácil de começar e fácil de deixar a meio.
A API de aprovisionamento assíncrono resolve essa lacuna: aponte-a para o que já tem. Num único pedido, faz um POST de links e texto simples, recebe de imediato um ID do motor e um agente de IA percorre as fontes, extrai vozes da marca, itens de glossário e regras, e aplica cada elemento ao novo motor à medida que o identifica. O motor fica utilizável a partir do 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 só é tão bom quanto a sua configuração. A seleção do modelo dá-lhe uma tradução; as vozes da marca, os itens de glossário e as regras são o que faz com que essa tradução corresponda à forma como o seu produto já comunica — o nível de formalidade que escolheu, os nomes de produtos que nunca traduz, o formato de data que usa sempre. São estes os mesmos elementos de base que, de outra forma, criaria à mão: vozes da marca, itens de glossário e regras 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 aprovisionamento elimina esse passo. Entrega à plataforma os próprios documentos — como URLs para rastrear ou como texto simples — e um agente de IA trata da leitura e da transcrição. Cria por si os registos de voz da marca, glossário e regras, num motor real, aplicando cada um à medida que é identificado. Depois, pode fazer a revisão e os ajustes no painel, tal como faria com qualquer elemento criado manualmente. 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 links 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 regras — aplicando cada elemento ao motor à medida que o identifica. Uma fonte cujo rastreio falhe, ou um único item que não possa ser criado, não impede o resto. O que a IA extrai explica estes três componentes e a forma como são mapeados para 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?
Nada fica escondido. O aprovisionamento não devolve um bloco proprietário — cria registos normais de voz da marca, glossário e regras num motor real, exatamente os mesmos objetos que criaria à mão, todos editáveis depois no painel. Quando a tarefa termina, devolve um resumo com o nome de cada registo criado e de cada falha encontrada, para que possa confirmar a configuração em vez de a dar por adquirida. 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.
