Поддержка интеграций с SDK v0

Разберитесь, как работают вспомогательные методы LingoDotDevEngine, и сохраните при миграции их входные и выходные данные, пакетную обработку и поведение при отмене.

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

Этот справочник описывает lingo.dev 0.138.10, где точка входа lingo.dev/sdk реэкспортирует @lingo.dev/_sdk 0.17.3. Пока проверяете места вызова в приложении, сохраняйте версию, указанную в его Lockfile. Для нового серверного рабочего процесса используйте руководство по JavaScript API.

Существующие вызовы перевода объектов #

Прежний вариант вызова на сервере:

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

const apiKey = process.env.LINGO_API_KEY;
const engineId = process.env.LINGO_ENGINE_ID;
if (!apiKey || !engineId) throw new Error("Configure a key and localization engine ID");

const client = new LingoDotDevEngine({ apiKey, engineId });
const translated = await client.localizeObject(
  { greeting: "Welcome back" },
  { sourceLocale: "en", targetLocale: "es" },
);

Вспомогательный метод напрямую возвращает переведённую запись. Храните учётные данные на сервере. У задания на обработку документа отдельный жизненный цикл: создание, запуск и скачивание. Ответ на запрос создания задания — не та переведённая запись, которую возвращает этот метод.

Конструктор и параметры пакетной обработки #

ПараметрПрежнее поведение
apiKeyОбязательная строка, которую проверяет конструктор.
apiUrlПереопределяет базовый URL API.
engineIdНеобязательный выбор движка локализации, который передаётся с запросом на перевод.
batchSizeПо умолчанию — 25, максимум — 250.
idealBatchItemSizeПо умолчанию — 250, максимум — 2500.
maxRetriesПо умолчанию — 3.
retryDelayMsПо умолчанию — 500 мс.

Параметры пакетной обработки определяют, как клиент формирует блоки, а не сколько запросов приложение выполняет одновременно. Вспомогательный метод повторяет запросы при сетевых ошибках и ответах 5xx с экспоненциально растущей задержкой и случайным разбросом. Намеренно отменённые запросы и запросы с обычными ответами 4xx этот метод не повторяет. Другие операции, например распознавание и получение данных учётной записи, используют собственные механизмы запросов. Не стоит рассчитывать, что одна политика повторных попыток действует для всех методов.

Входные данные и возвращаемые значения вспомогательных методов #

Вспомогательный методКонтракт
localizeObject(object, params, progressCallback?, signal?)Принимает запись и возвращает переведённую запись.
localizeText(text, params, progressCallback?, signal?)Помещает текст в поле и возвращает переведённую строку.
batchLocalizeText(text, { sourceLocale, targetLocales, fast? }, signal?)Отправляет запрос на перевод текста для каждой локали и возвращает строки в порядке запрошенных локалей.
localizeStringArray(strings, params)Использует временные ключи и восстанавливает массив строк. Публичного параметра сигнала нет.
localizeChat(messages, params, progressCallback?, signal?)Переводит text в сообщениях { name, text } и сохраняет их имена.
localizeHtml(html, params, progressCallback?, signal?)Разбирает HTML с помощью jsdom, переводит выбранное содержимое и сериализует результат.
recognizeLocale(text, signal?)Возвращает значение локали, полученное при распознавании.
estimate(items, signal?)Принимает элементы { targetLocale, sourceChars } и возвращает приблизительные итоговые значения и стоимость для каждой локали.
whoami(signal?)Возвращает { email, id } или null при обычных неуспешных ответах на запрос данных учётной записи. Ошибки сервера могут приводить к исключениям.

Общие параметры перевода: sourceLocale (допускает null для определения языка), targetLocale, необязательный fast, справочные данные по локалям, массивы подсказок для каждого ключа, filePath и triggerType (cli или ci). Перед использованием локали нормализуются. При сопоставлении с новой схемой запроса сохраняйте смысл каждого входного параметра.

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

Сохранение поведения при обработке HTML #

Вспомогательный метод для HTML переводит текстовые узлы за пределами script и style, а также meta.content, img.alt, input.placeholder и a.title. Он устанавливает целевой язык для документа и сериализует DOM. Метод не переводит все атрибуты и не сохраняет исходные байты.

Проверьте этот метод в той серверной среде, где он будет работать, включая разрешение его динамического импорта jsdom. Прежде чем заменить вызов обработки HTML другим преобразованием, сравните ссылки, структурную разметку, выбранные атрибуты и сериализованный результат. Сам по себе структурированный JSON-запрос не выполняет эти шаги обработки HTML.

ReplexicaEngine и LingoEngine расширяют LingoDotDevEngine как псевдонимы для совместимости и выводят предупреждения об устаревании. Если предупреждение о псевдониме исчезло, это означает лишь смену имени, а не завершение миграции с сохранением поведения.

Как перевести приложение на задания обработки документов #

Для новой интеграции используйте жизненный цикл задания API. Поместите содержимое объекта во встроенный JSON-документ, запустите задание и скачайте каждый готовый целевой документ. Храните ИД задания вместе с версией исходного содержимого, пока приложение не примет результат.

Сохраните всё поведение приложения, которое сейчас зависит от помещения текста в поле, порядка элементов массива, разбора HTML, пакетной обработки или обратных вызовов для отслеживания прогресса. Для перевода файлов вы можете использовать соответствующий формат документа. Смена способа передачи данных не воссоздаёт автоматически клиентские преобразования или повторные попытки.

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