JavaScript SDK

Перевод с помощью ИИ на JavaScript и Lingo.dev

Введение

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);
// Вывод: "¡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);
// Вывод: { 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);
// Вывод: ['¡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}`);
}
// Результат:
// 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);
// Результат: "<div>Hola <strong>mundo</strong></div>"

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

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

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}%`);
  },
);
// Результат:
// Прогресс перевода: 25%
// Прогресс перевода: 50%
// Прогресс перевода: 75%
// Прогресс перевода: 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, // Приоритет скорости над качеством
});
console.log(result);
// Вывод: "Hola mundo"

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

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

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

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

const result = await lingoDotDev.localizeText("Configuration test", {
  sourceLocale: "en",
  targetLocale: "es",
});
console.log(result);
// Вывод: "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);
// Вывод: '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, // Автоопределение
  targetLocale: "en",
});
console.log(result);
// Вывод: "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("Перевод не удался:", error.message);
  // Обработайте ошибку соответствующим образом
}