Mantener las integraciones con el SDK v0

Conoce las funciones auxiliares de LingoDotDevEngine y conserva su comportamiento de entrada, salida, procesamiento por lotes y cancelación durante la migración.

Una aplicación que utiliza LingoDotDevEngine puede depender de algo más que la traducción de objetos: puede dividir las solicitudes en bloques, reconstruir arrays o analizar HTML. Al migrar, debes asegurarte de conservar esos comportamientos. Cambiar solo la importación no los sustituye.

Esta referencia abarca lingo.dev 0.138.10, cuyo punto de entrada lingo.dev/sdk reexporta @lingo.dev/_sdk 0.17.3. Mantén la versión registrada en el Lockfile de la aplicación mientras revisas los puntos donde se invoca. Para un nuevo flujo de trabajo en el servidor, utiliza la guía de la API de JavaScript.

Llamadas existentes para traducir objetos #

La estructura utilizada hasta ahora en el servidor es:

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" },
);

La función auxiliar devuelve directamente el registro traducido. Mantén las credenciales en el servidor. Un trabajo de documento sigue un ciclo de vida independiente de creación, inicio y descarga; la respuesta a su creación no es el registro traducido que devuelve esta función auxiliar.

Constructor y controles de procesamiento por lotes #

OpciónComportamiento anterior
apiKeyCadena obligatoria que valida el constructor.
apiUrlSustitución de la URL base de la API.
engineIdSelección opcional del motor de localización, enviada con la traducción.
batchSizeValor predeterminado: 25; máximo: 250.
idealBatchItemSizeValor predeterminado: 250; máximo: 2500.
maxRetriesValor predeterminado: 3.
retryDelayMsValor predeterminado: 500 milisegundos.

Las opciones de procesamiento por lotes controlan cómo construye los bloques el cliente, no la concurrencia de toda la aplicación. Su función auxiliar de reintentos vuelve a intentar las solicitudes ante fallos de red y errores 5xx, con un retardo exponencial y una variación aleatoria. Esa función no reintenta las cancelaciones intencionadas ni las respuestas 4xx habituales. Otras operaciones, como el reconocimiento y la consulta de cuentas, utilizan sus propias rutas de solicitud; no des por hecho que una única política de reintentos se aplica a todos los métodos.

Entradas y valores de retorno de las funciones auxiliares #

Función auxiliarContrato
localizeObject(object, params, progressCallback?, signal?)Recibe un registro y devuelve un registro traducido.
localizeText(text, params, progressCallback?, signal?)Incluye el texto en un campo y devuelve la cadena traducida.
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?)Ejecuta una solicitud de texto por cada idioma y devuelve las cadenas en el orden de los idiomas solicitados.
localizeStringArray(strings, params)Utiliza claves temporales y reconstruye un array de cadenas; no ofrece un parámetro público de señal.
localizeChat(messages, params, progressCallback?, signal?)Traduce text en los mensajes { name, text } y conserva sus nombres.
localizeHtml(html, params, progressCallback?, signal?)Analiza HTML con jsdom, traduce el contenido seleccionado y serializa el resultado.
recognizeLocale(text, signal?)Devuelve el valor del idioma obtenido mediante el reconocimiento.
estimate(items, signal?)Acepta elementos { targetLocale, sourceChars } y devuelve totales aproximados y costes por idioma.
whoami(signal?)Devuelve { email, id } o null ante las respuestas fallidas habituales de la consulta de cuentas; los errores del servidor pueden generar excepciones.

Los parámetros comunes de traducción son sourceLocale (admite un valor nulo para la detección), targetLocale, fast opcional, datos de referencia por idioma, arrays de indicaciones por clave, filePath y triggerType (cli o ci). Los idiomas se normalizan antes de usarlos. Conserva el significado de cada entrada al adaptarla a un esquema de solicitud más reciente.

Las funciones de notificación del progreso informan de los bloques completados por el cliente, incluidos el porcentaje completado y los bloques de origen y procesados. No son notificaciones persistentes de trabajos en segundo plano. Un AbortSignal detiene el trabajo del cliente, pero no puede deshacer el procesamiento que el servidor ya ha aceptado.

Conservar explícitamente el comportamiento de HTML #

La función auxiliar de HTML traduce los nodos de texto situados fuera de script y style, además de meta.content, img.alt, input.placeholder y a.title. Establece el idioma de destino como idioma del documento y serializa el DOM. No traduce todos los atributos ni conserva los bytes originales.

Prueba esta función auxiliar en el entorno de ejecución real del servidor, incluida la resolución de su importación dinámica de jsdom. Compara los enlaces, el marcado estructural, los atributos seleccionados y la salida serializada antes de sustituir una llamada de HTML por una transformación distinta. Una solicitud JSON estructurada, por sí sola, no realiza esos pasos de procesamiento de HTML.

ReplexicaEngine y LingoEngine extienden LingoDotDevEngine como alias de compatibilidad y emiten advertencias de obsolescencia. Eliminar la advertencia de un alias supone un cambio de nombre; no completa la migración del comportamiento.

Migrar una aplicación a trabajos de documentos #

Para una nueva integración, utiliza el ciclo de vida de los trabajos de la API. Incluye el contenido del objeto en un documento JSON en línea, inicia el trabajo y descarga cada resultado de destino completado. Conserva el ID del trabajo junto con la revisión de origen hasta que la aplicación acepte el resultado.

Conserva cualquier comportamiento de la aplicación que dependa actualmente de la inclusión de texto en campos, el orden de los arrays, el análisis de HTML, el procesamiento por lotes o las funciones de notificación del progreso. Para traducir archivos, puedes utilizar el formato de documento correspondiente. Cambiar el transporte no reproduce automáticamente las transformaciones ni los reintentos del cliente.

Compara los datos resultantes y la gestión de errores antes de pasar el almacenamiento de la aplicación al nuevo flujo. La guía del flujo de trabajo aborda los resultados parciales y la finalización fuera de orden.