Lingo.dev SDK (for JavaScript)

The Lingo.dev SDK is a powerful tool for developers who need to integrate real-time AI-powered localization into their applications. It's designed to be simple to use, yet flexible enough to handle complex localization scenarios.

When to Use Lingo.dev SDK

The SDK shines in scenarios where you need dynamic, context-aware translations:

1. Chat applications: Translate messages on-the-fly.
2. Email clients: Provide real-time translation of incoming emails.
3. Comment systems: Localize user-generated content in real-time.
4. Social media tools: Provide multilingual experiences for user posts and comments.

Getting Started

First, install the SDK:

npm install lingo.dev

Then, initialize it in your code:

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

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

Core Features

The SDK provides several specialized methods for different localization needs:

1. localizeText: For simple string translations

const localizedText = await lingoDotDev.localizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocale: "es",
});

2. batchLocalizeText: For translating text into multiple languages at once

const localizedTexts = await lingoDotDev.batchLocalizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  fast: true, // optional
});
// Returns an array of translations in the requested order:
// ['¡Hola Mundo!', 'Bonjour le monde!', 'Hallo Welt!']

3. localizeObject: For translating objects with string values

const localizedContent = await lingoDotDev.localizeObject(
  { greeting: "Hello", farewell: "Goodbye" },
  { sourceLocale: "en", targetLocale: "es" },
);

4. localizeChat: For chat conversations, preserving speaker names

const localizedChat = await lingoDotDev.localizeChat(
  [
    { name: "Alice", text: "Hello!" },
    { name: "Bob", text: "Hi there!" },
  ],
  { sourceLocale: "en", targetLocale: "es" },
);

5. localizeHtml: For HTML documents, preserving structure and formatting

const localizedHtml = await lingoDotDev.localizeHtml(
  "<div>Hello <strong>world</strong></div>",
  { sourceLocale: "en", targetLocale: "es" },
);

6. recognizeLocale: For detecting the language of text

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

Configuration Options

When initializing the SDK, you can customize several parameters:

1. apiKey (required): Your unique identifier for accessing the Lingo.dev API.
2. batchSize (optional): Maximum number of items per API request. Defaults to 50, max 250.
3. idealBatchItemSize (optional): Target word count per batch. Defaults to 500, max 2500.

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

Translation Parameters

All localization methods accept these parameters:

1. sourceLocale: The original content's language code (e.g., 'en')
2. targetLocale: The desired translation language code (e.g., 'es')
3. fast (optional): Enable faster but potentially less accurate translations

const quickTranslation = await lingoDotDev.localizeText("Hello world", {
  sourceLocale: "en",
  targetLocale: "es",
  fast: true,
});

Automatic language detection

Lingo.dev is able to automatically detect the language of supplied content. You can pass null as sourceLocale to any of the methods listed above.

const localizedText = await lingoDotDev.localizeText("Hello, world!", {
  sourceLocale: null,
  targetLocale: "es",
});

Localization requests with language detection will take longer compared to passing explicit sourceLocale. We advise to use automatic detection only if you do not know the language, e.g. if the content comes from an external source like user input.

Progress Tracking

For long-running translations, you can monitor progress using a callback:

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

Under the Hood

While you don't need to know this to use the SDK, understanding how it works can help you use it more effectively:

1. Content chunking: The SDK breaks your content into optimal chunks based on batchSize and idealBatchItemSize.

2. Progress tracking: The SDK keeps track of processed chunks, enabling accurate progress reporting.

3. Error handling: It manages API errors, retrying failed requests when appropriate.

4. Response aggregation: After all chunks are processed, the SDK reassembles them into a single response.

This approach allows the SDK to handle large volumes of content efficiently, while providing a simple interface for developers.

Best Practices

1. Reuse the Lingo.dev Engine instance: Creating a new instance for every request is inefficient.

2. Handle errors: While the SDK manages many error scenarios, your app should still have error handling in place.

3. Use the progress callback for long-running tasks: This helps provide feedback to users during large translation jobs.

4. Consider your content structure: The SDK works best with flat objects. If you have deeply nested content, consider flattening it before passing it to the SDK.

By leveraging the Lingo.dev SDK, you can add powerful, AI-driven localization capabilities to your application with minimal effort. Whether you're building a chat app, a content platform, or any other multilingual software, Lingo.dev SDK provides the tools you need to create seamless, real-time localization experiences.