JavaScript SDK

Lingo.dev JavaScript SDK добавляет возможность перевода в реальном времени с использованием ИИ в веб-приложения, серверы Node.js и фронтенд-фреймворки. SDK обрабатывает динамический контент, такой как сообщения чата, комментарии пользователей и живые данные, которые требуют мгновенного перевода.

В отличие от статической локализации файлов с помощью Lingo.dev CLI, SDK обрабатывает контент по запросу, что делает его идеальным для чат-приложений, почтовых клиентов и инструментов социальных сетей, где контент постоянно меняется.

Установка

npm install lingo.dev

Базовая настройка

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

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

Перевод текста

Перевод простого текста:

const result = await lingoDotDev.localizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocale: "es",
});
// Возвращает: "¡Hola Mundo!"

Перевод на несколько языков:

const results = await lingoDotDev.batchLocalizeText("Hello, world!", {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
});
// Возвращает: ['¡Hola Mundo!', 'Bonjour le monde!', 'Hallo Welt!']

Перевод объектов

Перевод структурированных данных:

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

const translated = await lingoDotDev.localizeObject(content, {
  sourceLocale: "en",
  targetLocale: "es",
});
// Возвращает: { greeting: "Hola", farewell: "Adiós", message: "Bienvenido a nuestra plataforma" }

Этот метод обрабатывает вложенные объекты и сохраняет оригинальную структуру, переводя текстовые значения.

Перевод чатов

Перевод массивов с диалогами:

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",
});
// Возвращает переведённый диалог с сохранением структуры

Метод для чатов сохраняет метаданные, такие как имена пользователей, переводя только текстовое содержимое.

Перевод HTML

Переводите HTML, сохраняя разметку:

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

const translated = await lingoDotDev.localizeHtml(html, {
  sourceLocale: "en",
  targetLocale: "es",
});
// Возвращает: "<div>Hola <strong>mundo</strong></div>"

Перевод HTML сохраняет все теги, атрибуты и структуру, переводя только текстовое содержимое.

Определение языка

Автоматическое определение исходного языка:

const locale = await lingoDotDev.recognizeLocale("Bonjour le monde");
// Возвращает: 'fr'

Использование с автоматическим определением:

const result = await lingoDotDev.localizeText("Bonjour le monde", {
  sourceLocale: null, // Автоопределение
  targetLocale: "en",
});
// Возвращает: "Hello world"

Определение языка увеличивает время обработки, поэтому используйте его только в случае, если исходный язык неизвестен.

Настройки конфигурации

Настройка поведения SDK:

const lingoDotDev = new LingoDotDevEngine({
  apiKey: "your-api-key-here",
  batchSize: 100, // Максимальное количество элементов на один запрос API (по умолчанию: 50, максимум: 250)
  idealBatchItemSize: 1000, // Целевое количество слов на партию (по умолчанию: 500, максимум: 2500)
});

Размер партии определяет, сколько элементов отправляется в каждом запросе API. Более высокие значения уменьшают количество вызовов API, но увеличивают размер запроса.

Целевой размер партии определяет целевое количество слов для оптимальной эффективности обработки.

Параметры перевода

Контроль скорости и качества:

const result = await lingoDotDev.localizeText("Hello world", {
  sourceLocale: "en",
  targetLocale: "es",
  fast: true, // Приоритет скорости над качеством
});

Параметр fast позволяет ускорить перевод с возможным снижением качества для приложений, требующих быстрого выполнения.

Отслеживание прогресса

Мониторинг больших задач перевода:

await lingoDotDev.localizeObject(
  largeObject,
  { sourceLocale: "en", targetLocale: "es" },
  (progress) => {
    console.log(`Прогресс перевода: ${progress}%`);
    // Обновление индикатора прогресса в пользовательском интерфейсе
  },
);

Обратные вызовы прогресса предоставляют обратную связь в реальном времени для крупных операций перевода, что полезно для обновления пользовательского интерфейса.

Обработка ошибок

Реализуйте корректную обработку ошибок:

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

SDK включает автоматические повторные попытки в случае сетевых проблем, но обработка ошибок на уровне приложения остаётся важной.