Плагин для Payload CMS
Откройте доступ к схеме локализации Payload и уведомляйте Lingo.dev об изменениях исходного контента, не меняя то, как редактор сохраняет данные.
Lingo.dev нужно знать, какие поля Payload содержат текст для локализации и когда меняется исходный контент. @lingo.dev/payloadcms решает обе задачи: предоставляет эндпоинт схемы с аутентификацией и позволяет отправлять уведомления об изменениях исходного контента. Выбор контента для перевода и обратная запись настраиваются через интеграцию с Payload.
Зарегистрируйте плагин #
В существующем приложении на Payload 3 установите:
npm install @lingo.dev/payloadcms@0.1.5Добавьте lingo в существующий список плагинов приложения, сохранив настройки локализации:
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, сохраняя существующие эндпоинты. Запросите известную коллекцию или глобальный объект:
GET /api/lingo/schema?collection=articles
GET /api/lingo/schema?global=homepageИспользуйте слаги из своего приложения. Обработчик требует аутентификации пользователя Payload. Запрос без аутентификации возвращает 401, а без указания сущности или с неизвестной сущностью — 404. Интеграция читает этот эндпоинт с настроенными для неё правами Payload.
Ответ содержит имена и типы полей, флажки локализации, вложенную структуру и соответствующие вычисленные значения по умолчанию. В него входят поддерживаемые вложенные группы, массивы, блоки, вкладки и схемы блоков Lexical, необходимые для поиска текста. Вся конфигурация Payload не сериализуется: настройки администрирования и редактора, не относящиеся к задаче, в ответ не попадают.
Значения по умолчанию вычисляются для задействованных текстовых полей, с которыми работают авторы. В эту часть ответа не попадают скрытые значения и значения с ограниченным доступом, структурные поля, а также значения, которые не удаётся вычислить или сериализовать. Схема описывает, что может анализировать интеграция. Получение схемы не отправляет запрос на перевод.
Уведомляйте интеграцию об изменениях исходного контента #
После подключения Payload в Lingo.dev сохраните выданный URL с правом отправки уведомлений в конфигурации сервера и передайте его плагину:
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. Эти настройки не относятся к параметрам плагина, поэтому их можно менять, не меняя регистрацию плагина в приложении.