JavaScript SDK - Lingo.dev SDK

Введение

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

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

Установка

npm install lingo.dev

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

Для работы SDK требуется API-ключ от Lingo.dev.

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

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

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

Переводите простые текстовые строки на целевой язык.

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

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

Переводите вложенные объекты с сохранением структуры. SDK рекурсивно обрабатывает все строковые значения.

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

Пакетный перевод на несколько языков

Переводите контент на несколько целевых языков за один вызов. Возвращает массив с результатом для каждого языка.

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!']

Перевод чата

Переводите сообщения чата с сохранением имён собеседников. В каждом сообщении должны быть поля "name" и "text".

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!

Перевод HTML

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

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

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

Следите за ходом перевода с помощью callback-функции. Полезно для обновления интерфейса при больших операциях перевода.

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%

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

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

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, // Prioritize speed over quality
});
console.log(result);
// Output: "Hola mundo"

Конфигурация

Управляйте пакетной обработкой. SDK разбивает большие данные на части по количеству элементов и слов.

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

const lingoDotDev = new LingoDotDevEngine({
  apiKey: process.env.LINGODOTDEV_API_KEY,
  batchSize: 100, // Max items per API request (default: 50, max: 250)
  idealBatchItemSize: 1000, // Target word count per batch (default: 500, max: 2500)
});

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

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

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

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'

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

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, // Auto-detect
  targetLocale: "en",
});
console.log(result);
// Output: "Hello world"

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

SDK автоматически повторяет попытки при сетевых ошибках. Для других сбоев реализуйте обработку ошибок на уровне приложения.

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);
  // Handle error appropriately
}