Manter integrações do SDK v0

Compreenda as funções auxiliares do LingoDotDevEngine e preserve o seu comportamento de entrada, saída, processamento em lotes e cancelamento durante a migração.

Uma aplicação que utiliza LingoDotDevEngine pode fazer mais do que traduzir objetos: pode dividir pedidos em blocos, reconstruir vetores ou analisar HTML. A migração tem de preservar esses comportamentos de forma deliberada. Alterar apenas a importação não os substitui.

Esta referência abrange o lingo.dev 0.138.10, cuja entrada lingo.dev/sdk reexporta o @lingo.dev/_sdk 0.17.3. Mantenha a versão registada no Lockfile da aplicação enquanto verifica os pontos de chamada. Para um novo workflow no servidor, consulte o guia da API JavaScript.

Chamadas existentes de tradução de objetos #

O formato usado anteriormente no servidor é o seguinte:

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 devolve diretamente o registo traduzido. Mantenha as credenciais no servidor. Uma tarefa de documento segue um ciclo de vida próprio, com etapas de criação, início e transferência; a resposta à criação da tarefa não corresponde ao registo traduzido devolvido por esta função auxiliar.

Construtor e controlos de processamento em lotes #

OpçãoComportamento anterior
apiKeyCadeia de carateres obrigatória, validada pelo construtor.
apiUrlSubstitui o URL base da API.
engineIdSeleção opcional do motor de localização, enviada com o pedido de tradução.
batchSizeValor predefinido: 25; máximo: 250.
idealBatchItemSizeValor predefinido: 250; máximo: 2500.
maxRetriesValor predefinido: 3.
retryDelayMsValor predefinido: 500 milissegundos.

As opções de processamento em lotes controlam a forma como o cliente constrói os blocos, não a concorrência global da aplicação. A função auxiliar de repetição volta a tentar os pedidos após falhas de rede e erros 5xx, com intervalos que aumentam exponencialmente e incluem uma variação aleatória. Esta função auxiliar não repete pedidos em caso de cancelamento intencional ou de respostas 4xx habituais. Outras operações, como o reconhecimento e a consulta de contas, seguem os seus próprios percursos de pedido; não pressuponha que uma única política de repetição abrange todos os métodos.

Entradas e valores devolvidos pelas funções auxiliares #

Função auxiliarContrato
localizeObject(object, params, progressCallback?, signal?)Recebe um registo e devolve um registo traduzido.
localizeText(text, params, progressCallback?, signal?)Coloca o texto num campo e devolve a cadeia de carateres traduzida.
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?)Executa um pedido de texto para cada idioma e devolve as cadeias de carateres pela ordem dos idiomas solicitados.
localizeStringArray(strings, params)Utiliza chaves temporárias e reconstrói um vetor de cadeias de carateres; não disponibiliza um parâmetro público de sinal.
localizeChat(messages, params, progressCallback?, signal?)Traduz text nas mensagens { name, text } e mantém os respetivos nomes.
localizeHtml(html, params, progressCallback?, signal?)Analisa HTML com jsdom, traduz o conteúdo selecionado e serializa o resultado.
recognizeLocale(text, signal?)Devolve o valor do idioma obtido no reconhecimento.
estimate(items, signal?)Aceita itens { targetLocale, sourceChars } e devolve totais aproximados e custos por idioma.
whoami(signal?)Devolve { email, id } ou null nas respostas habituais de insucesso relativas à conta; os erros do servidor podem gerar exceções.

Os parâmetros comuns de tradução são sourceLocale (aceita um valor nulo para deteção), targetLocale, fast opcional, dados de referência por idioma, vetores de indicações por chave, filePath e triggerType (cli ou ci). Os idiomas são normalizados antes de serem utilizados. Preserve o significado de cada entrada ao fazer a correspondência com um esquema de pedido mais recente.

As funções de retorno de progresso comunicam a conclusão dos blocos do cliente, incluindo a percentagem concluída e os blocos de origem/processados. Não são notificações persistentes de tarefas em segundo plano. Um AbortSignal interrompe o trabalho do cliente, mas não pode anular o processamento que o servidor já aceitou.

Preservar explicitamente o comportamento do HTML #

A função auxiliar de HTML traduz os nós de texto fora de script e style, bem como meta.content, img.alt, input.placeholder e a.title. 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 esta função auxiliar no ambiente de execução real do servidor, incluindo a resolução da importação dinâmica de jsdom. Compare as ligações, a marcação estrutural, os atributos selecionados e o resultado serializado antes de migrar uma chamada HTML para uma transformação diferente. Um pedido JSON estruturado, por si só, não executa essas etapas de processamento de HTML.

ReplexicaEngine e LingoEngine estendem LingoDotDevEngine como nomes alternativos de compatibilidade e emitem avisos de descontinuação. Eliminar um aviso relativo a um nome alternativo é apenas uma alteração de nomenclatura; não conclui a migração do comportamento.

Migrar uma aplicação para tarefas de documentos #

Para uma nova integração, utilize o ciclo de vida das tarefas da API. Coloque o conteúdo do objeto num documento JSON incorporado, inicie a tarefa e transfira cada resultado de destino concluído. Guarde o ID da tarefa juntamente com a revisão de origem até a aplicação aceitar o respetivo resultado.

Preserve todos os comportamentos da aplicação que dependam atualmente da colocação de texto em campos, da ordem dos vetores, da análise de HTML, do processamento em lotes ou das funções de retorno de progresso. A tradução de ficheiros pode utilizar 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 os resultados parciais e a conclusão fora de ordem.