SDK de JavaScript - Lingo.dev SDK

Introducción

El SDK de JavaScript de Lingo.dev añade traducción en tiempo real impulsada por IA a aplicaciones web, servidores Node.js y frameworks frontend. El SDK gestiona contenido dinámico como mensajes de chat, comentarios de usuarios y datos en vivo que necesitan traducción instantánea.

A diferencia de la localización de archivos estáticos con Lingo.dev CLI, el SDK procesa contenido bajo demanda, lo que lo hace ideal para aplicaciones de chat, clientes de correo electrónico y herramientas de redes sociales donde el contenido cambia constantemente.

Instalación

npm install lingo.dev

Configuración básica

El SDK requiere una clave API de Lingo.dev.

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

Traducción de texto

Traduce cadenas de texto simples a un idioma de destino.

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const result = await lingoDotDev.localizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(result);
// Output: "¡Hola Mundo!"

Traducción de objetos

Traduce objetos anidados preservando su estructura. El SDK procesa recursivamente todos los valores de tipo string.

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const content = {
  greeting: "Hello",
  farewell: "Goodbye",
  message: "Welcome to our platform",
};

const translated = await lingoDotDev.localizeObject(content, {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(translated);
// Output: { greeting: "Hola", farewell: "Adiós", message: "Bienvenido a nuestra plataforma" }

Traducción por lotes a múltiples idiomas

Traduce contenido a múltiples idiomas de destino en una sola llamada. Devuelve un array con un resultado por cada idioma de destino.

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const results = await lingoDotDev.batchLocalizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
});
console.log(results);
// Output: ['¡Hola Mundo!', 'Bonjour le monde!', 'Hallo Welt!']

Traducción de chat

Traduce mensajes de chat preservando los nombres de los interlocutores. Cada mensaje debe tener tanto campos "Nombre" como "Texto".

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const conversation = [
  { name: "Alice", text: "Hello!" },
  { name: "Bob", text: "How are you?" },
  { name: "Alice", text: "I'm doing well, thanks!" },
];

const translated = await lingoDotDev.localizeChat(conversation, {
  sourceLocale: "en",
  targetLocale: "es",
});

for (const message of translated) {
  console.log(`${message.name}: ${message.text}`);
}
// Output:
// Alice: ¡Hola!
// Bob: ¿Cómo estás?
// Alice: ¡Me va bien, gracias!

Traducción de HTML

Traduce HTML preservando el marcado. Mantiene todas las etiquetas, atributos y estructura mientras traduce solo el contenido textual.

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const html = "<div>Hello <strong>world</strong></div>";

const translated = await lingoDotDev.localizeHtml(html, {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(translated);
// Output: "<div>Hola <strong>mundo</strong></div>"

Seguimiento de progreso

Monitoriza el progreso de traducción con un callback. Útil para actualizar la interfaz de usuario durante operaciones de traducción extensas.

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const largeObject = {
  page1: "Welcome to our application",
  page2: "This is the second page",
  page3: "Here is more content",
  page4: "Final page of content",
};

await lingoDotDev.localizeObject(
  largeObject,
  { sourceLocale: "en", targetLocale: "es" },
  (progress) => {
    console.log(`Translation progress: ${progress}%`);
  },
);
// Output:
// Translation progress: 25%
// Translation progress: 50%
// Translation progress: 75%
// Translation progress: 100%

Parámetros de traducción

Velocidad vs control de calidad para aplicaciones sensibles al tiempo.

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const result = await lingoDotDev.localizeText("Hello world", {
  sourceLocale: "en",
  targetLocale: "es",
  fast: true, // Priorizar velocidad sobre calidad
});
console.log(result);
// Output: "Hola mundo"

Configuración

Controla el comportamiento de procesamiento por lotes. El SDK divide las cargas grandes basándose en restricciones de cantidad de elementos y recuento de palabras.

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
  batchSize: 100, // Máximo de elementos por solicitud API (predeterminado: 50, máximo: 250)
  idealBatchItemSize: 1000, // Recuento objetivo de palabras por lote (predeterminado: 500, máximo: 2500)
});

const result = await lingoDotDev.localizeText("Configuration test", {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(result);
// Output: "Prueba de configuración"

Detección de idioma

Detecta el idioma de una cadena de texto. Utilízalo solo cuando el idioma de origen es desconocido, ya que la detección añade tiempo de procesamiento.

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const locale = await lingoDotDev.recognizeLocale("Bonjour le monde");
console.log(locale);
// Output: 'fr'

Uso con detección automática:

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

const result = await lingoDotDev.localizeText("Bonjour le monde", {
  sourceLocale: null, // Detección automática
  targetLocale: "en",
});
console.log(result);
// Output: "Hello world"

Manejo de errores

El SDK incluye reintentos automáticos para problemas de red. Implementa manejo de errores a nivel de aplicación para otros fallos.

import { LingoDotDevEngine } from "lingo.dev/sdk";

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
});

try {
  const result = await lingoDotDev.localizeText("Hello", {
    sourceLocale: "en",
    targetLocale: "es",
  });
  console.log(result);
} catch (error) {
  console.error("Translation failed:", error.message);
  // Manejar el error apropiadamente
}