Mantén las integraciones del SDK v0
Conoce las funciones auxiliares de LingoDotDevEngine y conserva su comportamiento de entrada, salida, procesamiento por lotes y cancelación al migrar.
Una aplicación que usa LingoDotDevEngine puede depender de algo más que la traducción de objetos: puede dividir solicitudes en bloques, reconstruir arreglos o analizar HTML. Al migrar, debes conservar esos comportamientos de manera explícita. Cambiar solo la importación no los reemplaza.
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 realizan las llamadas. Para un nuevo flujo de trabajo en el servidor, usa la guía de la API de JavaScript.
Llamadas existentes para traducir objetos #
La estructura que se usaba del lado del servidor es:
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 de creación no equivale al registro traducido que devuelve esta función auxiliar.
Constructor y controles de procesamiento por lotes #
| Opción | Comportamiento anterior |
|---|---|
apiKey | Cadena obligatoria que valida el constructor. |
apiUrl | Permite reemplazar la URL base de la API. |
engineId | Selección opcional del motor de localización que se envía con la traducción. |
batchSize | Valor predeterminado: 25; máximo: 250. |
idealBatchItemSize | Valor predeterminado: 250; máximo: 2500. |
maxRetries | Valor predeterminado: 3. |
retryDelayMs | Valor predeterminado: 500 milisegundos. |
Las opciones de procesamiento por lotes controlan cómo el cliente construye los bloques, no la concurrencia de toda la aplicación. Su función auxiliar de reintentos vuelve a intentar las solicitudes que fallan por problemas de red o errores 5xx, con tiempos de espera exponenciales y variación aleatoria. Esa función no reintenta las cancelaciones intencionales ni las respuestas 4xx habituales. Otras operaciones, como el reconocimiento y la consulta de cuentas, usan sus propias rutas de solicitud; no supongas que una sola política de reintentos se aplica a todos los métodos.
Entradas y valores de retorno de las funciones auxiliares #
| Función auxiliar | Contrato |
|---|---|
localizeObject(object, params, progressCallback?, signal?) | Recibe un registro y devuelve un registro traducido. |
localizeText(text, params, progressCallback?, signal?) | Coloca 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) | Usa claves temporales y reconstruye un arreglo de cadenas; no expone un parámetro 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 costos por idioma. |
whoami(signal?) | Devuelve { email, id } o null ante respuestas de cuenta fallidas habituales; los errores del servidor pueden lanzar 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, arreglos 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 devolución de llamada de progreso informan sobre los bloques que el cliente ha completado, incluido 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 aceptó.
Conserva explícitamente el comportamiento del HTML #
La función auxiliar de HTML traduce los nodos de texto fuera de script y style, además de meta.content, img.alt, input.placeholder y a.title. Configura el idioma del documento con el idioma de destino 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 migrar una llamada de HTML a 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 una advertencia de alias solo supone un cambio de nombre; no completa la migración del comportamiento.
Migra una aplicación a trabajos de documentos #
Para una nueva integración, usa el ciclo de vida de los trabajos de la API. Coloca el contenido del objeto en un documento JSON dentro de la solicitud, inicia el trabajo y descarga cada documento de destino completado. Conserva el ID del trabajo junto con la revisión de origen hasta que la aplicación acepte el resultado.
Conserva todos los comportamientos de la aplicación que actualmente dependan de colocar texto en campos, del orden de los arreglos, del análisis de HTML, del procesamiento por lotes o de las funciones de devolución de llamada de progreso. La traducción de archivos puede usar el formato de documento correspondiente. Cambiar el transporte no recrea automáticamente las transformaciones ni los reintentos del lado del cliente.
Compara los datos resultantes y el manejo de errores antes de pasar el almacenamiento de la aplicación al nuevo flujo. La guía de flujos de trabajo explica los resultados parciales y la finalización fuera de orden.