Mantenha integrações com o SDK v0
Entenda as funções auxiliares do LingoDotDevEngine e preserve seu comportamento de entrada, saída, processamento em lotes e cancelamento ao migrar.
Uma aplicação que usa LingoDotDevEngine pode depender de mais do que a tradução de objetos: ela pode dividir solicitações em blocos, reconstruir arrays ou analisar HTML. Esses comportamentos precisam ser preservados de forma deliberada na migração. Alterar apenas a importação não os substitui.
Esta referência abrange o lingo.dev 0.138.10, cujo ponto de entrada lingo.dev/sdk reexporta o @lingo.dev/_sdk 0.17.3. Mantenha a versão registrada no Lockfile da aplicação enquanto verifica os pontos em que ela é chamada. Para um novo workflow no servidor, use o guia da API JavaScript.
Chamadas existentes de tradução de objetos #
O formato usado historicamente no servidor é:
import { LingoDotDevEngine } from "lingo.dev/sdk";
const apiKey = process.env.LINGO_API_KEY;
const engineId = process.env.LINGO_ENGINE_ID;
if (!apiKey || !engineId) throw new Error("Configure a key and localization engine ID");
const client = new LingoDotDevEngine({ apiKey, engineId });
const translated = await client.localizeObject(
{ greeting: "Welcome back" },
{ sourceLocale: "en", targetLocale: "es" },
);A função auxiliar retorna o registro traduzido diretamente. Mantenha as credenciais no servidor. Uma tarefa de documento tem um ciclo de vida próprio, com criação, início e download; a resposta à criação não é o registro traduzido retornado por essa função auxiliar.
Construtor e controles de processamento em lotes #
| Opção | Comportamento histórico |
|---|---|
apiKey | String obrigatória, validada pelo construtor. |
apiUrl | Substitui a URL base da API. |
engineId | Seleção opcional do engine de localização, enviada com a tradução. |
batchSize | Padrão: 25; máximo: 250. |
idealBatchItemSize | Padrão: 250; máximo: 2500. |
maxRetries | Padrão: 3. |
retryDelayMs | Padrão: 500 milissegundos. |
As opções de processamento em lotes controlam como o cliente monta os blocos, não a concorrência da aplicação como um todo. A função auxiliar de novas tentativas repete solicitações em caso de falhas de rede e erros 5xx, com espera exponencial e variação aleatória. Cancelamentos intencionais e respostas 4xx comuns não geram novas tentativas por meio dessa função. Outras operações, como reconhecimento e consulta de conta, usam seus próprios caminhos de solicitação; não presuma que uma única política de novas tentativas se aplica a todos os métodos.
Entradas e valores de retorno das funções auxiliares #
| Função auxiliar | Contrato |
|---|---|
localizeObject(object, params, progressCallback?, signal?) | Recebe um registro e retorna um registro traduzido. |
localizeText(text, params, progressCallback?, signal?) | Encapsula o texto em um campo e retorna a string traduzida. |
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?) | Faz uma solicitação de texto para cada idioma e retorna as strings na ordem dos idiomas solicitados. |
localizeStringArray(strings, params) | Usa chaves temporárias e reconstrói um array de strings; não há parâmetro público de sinal. |
localizeChat(messages, params, progressCallback?, signal?) | Traduz text em mensagens { name, text } e mantém seus nomes. |
localizeHtml(html, params, progressCallback?, signal?) | Analisa o HTML com jsdom, traduz o conteúdo selecionado e serializa o resultado. |
recognizeLocale(text, signal?) | Retorna o valor do idioma obtido no reconhecimento. |
estimate(items, signal?) | Aceita itens { targetLocale, sourceChars } e retorna totais aproximados e custos por idioma. |
whoami(signal?) | Retorna { email, id } ou null para respostas comuns de insucesso na consulta de conta; erros de servidor podem gerar exceções. |
Os parâmetros comuns de tradução são sourceLocale (aceita nulo para detecção), targetLocale, fast opcional, dados de referência por idioma, arrays de dicas por chave, filePath e triggerType (cli ou ci). Os idiomas são normalizados antes do uso. Preserve o significado de cada entrada ao mapeá-la para um esquema de solicitação mais recente.
As funções de retorno de chamada de progresso informam os blocos concluídos pelo cliente, incluindo a porcentagem concluída e os blocos de origem/processados. Elas não são notificações persistentes de tarefas em segundo plano. Um AbortSignal interrompe o trabalho do cliente, mas não desfaz o processamento que o servidor já aceitou.
Preserve explicitamente o comportamento do HTML #
A função auxiliar de HTML traduz nós de texto fora de script e style, além de meta.content, img.alt, input.placeholder e a.title. Ela define o idioma do documento como o idioma de destino e serializa o DOM. Não traduz todos os atributos nem preserva os bytes originais.
Teste essa função auxiliar no ambiente real de execução do servidor, incluindo a resolução da importação dinâmica de jsdom. Compare os links, a marcação estrutural, os atributos selecionados e a saída serializada antes de migrar uma chamada HTML para uma transformação diferente. Uma solicitação JSON estruturada, por si só, não executa essas etapas de HTML.
ReplexicaEngine e LingoEngine estendem LingoDotDevEngine como nomes alternativos de compatibilidade e emitem avisos de descontinuação. Eliminar o aviso de um nome alternativo é uma mudança de nomenclatura; isso não conclui a migração de comportamento.
Migre uma aplicação para tarefas de documento #
Para uma nova integração, use o ciclo de vida das tarefas da API. Insira o conteúdo do objeto em um documento JSON incorporado, inicie a tarefa e baixe cada resultado de destino concluído. Mantenha o ID da tarefa junto à revisão de origem até que a aplicação aceite o resultado.
Preserve todos os comportamentos da aplicação que dependam atualmente de encapsulamento de texto, ordem dos arrays, análise de HTML, processamento em lotes ou funções de retorno de chamada de progresso. A tradução de arquivos pode usar o formato de documento correspondente. Mudar o transporte não recria automaticamente as transformações nem as novas tentativas do lado do cliente.
Compare os dados resultantes e o tratamento de falhas antes de passar o armazenamento da aplicação para o novo fluxo. O guia de workflow aborda resultados parciais e conclusões fora de ordem.