SDK de JavaScript

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

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

const lingoDotDev = new LingoDotDevEngine({
  apiKey: "your-api-key-here",
});

Traducción de texto

Traducir texto simple:

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

Traducir a múltiples idiomas:

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

Traducción de objetos

Traducir datos estructurados:

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

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

Este método maneja objetos anidados y preserva la estructura original mientras traduce los valores de texto.

Traducción de chat

Traducir arrays de conversación:

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",
});
// Devuelve la conversación traducida con la misma estructura

El método de chat preserva metadatos como nombres de usuario mientras traduce solo el contenido textual.

Traducción HTML

Traduce HTML preservando el marcado:

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

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

La traducción HTML mantiene todas las etiquetas, atributos y estructura mientras traduce solo el contenido textual.

Detección de idioma

Detecta automáticamente el idioma de origen:

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

Uso con detección automática:

const result = await lingoDotDev.localizeText("Bonjour le monde", {
  sourceLocale: null, // Auto-detect
  targetLocale: "en",
});
// Returns: "Hello world"

La detección de idioma añade tiempo de procesamiento, por lo que debe utilizarse solo cuando se desconoce el idioma de origen.

Opciones de configuración

Configura el comportamiento del SDK:

const lingoDotDev = new LingoDotDevEngine({
  apiKey: "your-api-key-here",
  batchSize: 100, // Max items per API request (default: 50, max: 250)
  idealBatchItemSize: 1000, // Target word count per batch (default: 500, max: 2500)
});

Batch size controla cuántos elementos se envían en cada solicitud API. Valores más altos reducen las llamadas API pero aumentan el tamaño de la solicitud.

Ideal batch item size controla el recuento de palabras objetivo para una eficiencia de procesamiento óptima.

Parámetros de traducción

Control de velocidad vs calidad:

const result = await lingoDotDev.localizeText("Hello world", {
  sourceLocale: "en",
  targetLocale: "es",
  fast: true, // Prioritize speed over quality
});

El parámetro fast permite traducciones más rápidas con una posible reducción de calidad para aplicaciones sensibles al tiempo.

Seguimiento de progreso

Monitoriza trabajos de traducción grandes:

await lingoDotDev.localizeObject(
  largeObject,
  { sourceLocale: "en", targetLocale: "es" },
  (progress) => {
    console.log(`Translation progress: ${progress}%`);
    // Update UI progress bar
  },
);

Los callbacks de progreso proporcionan retroalimentación en tiempo real para operaciones de traducción grandes, útiles para actualizaciones de interfaz de usuario.

Manejo de errores

Implementa un manejo de errores adecuado:

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

El SDK incluye reintentos automáticos para problemas de red, pero el manejo de errores a nivel de aplicación sigue siendo importante.