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 é:

ts
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çãoComportamento histórico
apiKeyString obrigatória, validada pelo construtor.
apiUrlSubstitui a URL base da API.
engineIdSeleção opcional do engine de localização, enviada com a tradução.
batchSizePadrão: 25; máximo: 250.
idealBatchItemSizePadrão: 250; máximo: 2500.
maxRetriesPadrão: 3.
retryDelayMsPadrã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 auxiliarContrato
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.