Плагин для Payload CMS

Откройте доступ к схеме локализации Payload и уведомляйте Lingo.dev об изменениях исходного контента, не меняя то, как редактор сохраняет данные.

Lingo.dev нужно знать, какие поля Payload содержат текст для локализации и когда меняется исходный контент. @lingo.dev/payloadcms решает обе задачи: предоставляет эндпоинт схемы с аутентификацией и позволяет отправлять уведомления об изменениях исходного контента. Выбор контента для перевода и обратная запись настраиваются через интеграцию с Payload.

Зарегистрируйте плагин #

В существующем приложении на Payload 3 установите:

sh
npm install @lingo.dev/payloadcms@0.1.5

Добавьте lingo в существующий список плагинов приложения, сохранив настройки локализации:

ts
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";

export default buildConfig({
  localization: {
    locales: ["en", "fr"],
    defaultLocale: "en",
  },
  plugins: [lingo()],
});

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

Пакет экспортирует lingo и LingoPluginOptions. lingo() возвращает плагин Payload с единственным параметром — webhookUrl?: string. Если зарегистрировать плагин без этого URL, эндпоинт схемы всё равно будет доступен. Так вы сможете настроить получение схемы до подключения автоматических уведомлений.

Просмотрите схему с аутентификацией Payload #

Плагин добавляет эндпоинт GET /lingo/schema относительно базового пути API Payload, обычно /api/lingo/schema, сохраняя существующие эндпоинты. Запросите известную коллекцию или глобальный объект:

text
GET /api/lingo/schema?collection=articles
GET /api/lingo/schema?global=homepage

Используйте слаги из своего приложения. Обработчик требует аутентификации пользователя Payload. Запрос без аутентификации возвращает 401, а без указания сущности или с неизвестной сущностью — 404. Интеграция читает этот эндпоинт с настроенными для неё правами Payload.

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

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

Уведомляйте интеграцию об изменениях исходного контента #

После подключения Payload в Lingo.dev сохраните выданный URL с правом отправки уведомлений в конфигурации сервера и передайте его плагину:

ts
const webhookUrl = process.env.LINGO_PAYLOAD_WEBHOOK_URL;
if (!webhookUrl) throw new Error("Set LINGO_PAYLOAD_WEBHOOK_URL for automatic notifications");

const plugin = lingo({ webhookUrl });

В существующем массиве plugins используйте plugin вместо lingo(). Имя переменной окружения вы выбираете сами. Сам URL даёт право отправлять уведомления. Не допускайте его попадания в браузерные сборки, исходный код в коммитах и логи.

Если настроены и URL, и localization.defaultLocale, плагин добавляет хуки afterChange к коллекциям и глобальным объектам, сохраняя существующие хуки. Уведомление о коллекции содержит её слаг, ИД документа и, при наличии, статус документа. Уведомление о глобальном объекте содержит его слаг. Данные уведомления — это указатель, а не полный документ: интеграция повторно читает контент с настроенными для неё учётными данными.

Изменения с явно указанной другой локалью пропускаются. Так обратная запись в целевую локаль не запускает перевод исходного контента снова и снова. Изменение без явно указанной локали может вызвать уведомление. Время ожидания запроса — 5 секунд. Ошибки передачи данных подавляются, чтобы сохранение в редакторе могло завершиться. Ответ HTTP с кодом ошибки тоже не приводит к сбою сохранения.

Проверьте результат подключения #

Сначала убедитесь, что интеграция может прочитать нужную схему со своими учётными данными Payload. Затем с нужными правами измените исходный контент через рабочий процесс интеграции и проверьте результат в целевой локали. Если исходный контент сохраняется, но перевод не появляется, проверьте, принято ли уведомление и как прошёл запуск перевода. Успешное сохранение в редакторе само по себе не подтверждает доставку уведомления.

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