JavaScript SDK

Lingo.dev JavaScript SDK adds real-time AI-powered translation to web applications, Node.js servers, and frontend frameworks. The SDK handles dynamic content like chat messages, user comments, and live data that needs instant translation.

Unlike static file localization with Lingo.dev CLI, the SDK processes content on-demand, making it ideal for chat applications, email clients, and social media tools where content changes constantly.

Installation

npm install lingo.dev

Basic Setup

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

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

Text Translation

Translate simple text:

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

Translate to multiple languages:

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

Object Translation

Translate structured data:

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

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

This method handles nested objects and preserves the original structure while translating text values.

Chat Translation

Translate conversation arrays:

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",
});
// Returns translated conversation with same structure

The chat method preserves metadata like usernames while translating only the text content.

HTML Translation

Translate HTML while preserving markup:

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>"

HTML translation maintains all tags, attributes, and structure while translating only the text content.

Language Detection

Automatically detect source language:

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

Use with automatic detection:

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

Language detection adds processing time, so use it only when the source language is unknown.

Configuration Options

Configure SDK behavior:

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 controls how many items are sent in each API request. Higher values reduce API calls but increase request size.

Ideal batch item size controls the target word count for optimal processing efficiency.

Translation Parameters

Speed vs quality control:

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

The fast parameter enables quicker translations with potentially reduced quality for time-sensitive applications.

Progress Tracking

Monitor large translation jobs:

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

Progress callbacks provide real-time feedback for large translation operations, useful for user interface updates.

Error Handling

Implement proper error handling:

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

The SDK includes automatic retries for network issues, but application-level error handling remains important.