Payload CMS · Lingo.dev

Подключите Payload CMS к движку локализации, выберите коллекции и глобальные объекты — и Lingo.dev переведёт локализованные поля в нужные локали и запишет результат обратно в Payload под каждой локалью.

Работает с проектами Payload 3, в которых включена локализация и используется редактор Lexical. Старый редактор Slate не поддерживается. Переводятся локализованные поля text, textarea и richText. Всё остальное в документе остаётся как есть.

Payload CMS доступен в рамках плана Enterprise. Если на странице подключения написано Payload CMS не входит в ваш план, свяжитесь с нами — разберёмся.

Перед началом#

Вам понадобятся три вещи:

Payload 3 с настроенной локализацией. Убедитесь, что исходная и целевая локали совпадают с локалями в конфигурации Payload.
Сервисный пользователь с API-ключом. Задайте useAPIKey: true для коллекции аутентификации (обычно users), создайте пользователя для Lingo.dev и сгенерируйте ему API-ключ в панели администрирования Payload. Пользователь должен иметь права на чтение и обновление всех нужных коллекций и глобальных объектов.
Движок локализации. Его глоссарий, тональность бренда и правила задают стиль переводов.

Коды локалей должны совпадать с конфигом Payload

Локали в Lingo.dev должны точно совпадать с кодами в localization.locales. Если в Payload заданы en и de, выбирайте English и German, а не English (United States): en-US и en — разные локали. В качестве исходной локали используйте defaultLocale из Payload — именно за ней плагин следит на предмет изменений.

Подключение инстанса Payload#

Откройте интеграцию

Перейдите в Studio → All integrations и нажмите Connect на карточке Payload CMS.

Введите данные экземпляра

Поле	Что вводить
Адрес	Корневой URL инстанса, например `https://cms.example.com`. Только HTTPS
Коллекция для аутентификации	Коллекция, к которой относится служебный API-ключ, обычно `users`
API-ключ	API-ключ сервисного пользователя
Пользовательские заголовки	Необязательно. Отправляется с каждым запросом к вашему инстансу. Нажмите Add header для каждого заголовка или вставьте строку `Name: value`, чтобы заполнить строку таблицы

Нажмите Verify instance. Lingo.dev проверит ключ на вашем инстансе, прежде чем продолжить.

Выберите, что переводить

Настройка	Что делает
Название	Как назвать это подключение — например, `Production` или `Staging`, чтобы различать инстансы
Коллекции и глобальные объекты	Выберите элементы для перевода. Если сервисный пользователь не имеет доступа на чтение и обновление, строка зачёркнута и недоступна для выбора, пока доступ не будет предоставлен
Движок	Движок локализации, глоссарий, правила и тональность бренда которого используются для этих переводов
Исходная локаль	Локаль, в которой работают редакторы. Используйте `defaultLocale` из Payload
Целевые локали	Локали для перевода
Режим	Publish переводит только опубликованные изменения и сразу публикует переводы. Draft переводит и черновые сохранения, записывая переводы как черновики. Подробнее — в разделе «Черновики и опубликованные» ниже

Нажмите Connect.

Установите плагин

На последнем шаге появится ваш Webhook URL. Скопируйте его сейчас — он показывается только один раз. Сохраните его как LINGO_WEBHOOK_URL в среде Payload, затем установите плагин и добавьте его в конфигурацию:

bash

pnpm add @lingo.dev/payloadcms

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

export default buildConfig({
  // ...your collections, globals, and localization config
  plugins: [
    lingo({
      webhookUrl: process.env.LINGO_WEBHOOK_URL,
    }),
  ],
});

Нажмите Done, затем повторно разверните Payload. После этого каждое опубликованное изменение в исходной локали будет отправляться в Lingo.dev для перевода.

Что делает плагин

Плагин добавляет эндпоинт GET /api/lingo/schema, который сообщает Lingo.dev, какие поля содержат локализованный текст, и хук, уведомляющий Lingo.dev при изменении документа или глобального объекта. Область охвата, локали и движок настраиваются в дашборде — без передеплоя. Уберите webhookUrl, чтобы отключить хук и запускать переводы вручную из дашборда.

Что переводится#

На странице подключения четыре вкладки: Collections, Globals, Workflow runs и Settings.

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

Строка с пометкой no read + update заблокирована: сервисный пользователь не может читать и обновлять её, поэтому перевод недоступен. Строка с пометкой not localized yet имеет отключённый Sync.

Локали, движок и режим можно изменить на вкладке Settings.

Внутри документа то, что переводится, определяется конфигурацией полей в Payload:

Поле	Переводится
Поля `text`, `textarea` и `richText`, помеченные как `localized: true`	Да
Те же типы полей внутри локализованных `group`, `array`, `blocks` или `tabs`	Да
Блоки и встроенные блоки внутри форматированного текста	Да, их текстовые поля по тем же правилам
`select`, `radio`, `checkbox`, `number`, `date`, `relationship`, `upload`, `json`, `code`, `email`, `point`	Нет
Поля без локализации и без локализованного родителя	Нет
`id`, `blockType`, `blockName`	Нет

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

Чтобы добавить поле в область охвата, пометьте его localized: true в Payload и передеплойте. Следующий запуск его подхватит.

Синхронизация и повторный перевод#

Автоматические запуски. Если в плагине задан параметр webhookUrl, каждое сохранение документа или глобального объекта в исходной локали уведомляет Lingo.dev. Сохранения в пределах короткого временного окна объединяются в один запуск. Сохранения в других локалях, черновые сохранения (если подключение не работает в режиме Draft) и контент вне области видимости игнорируются.

Ручные запуски. Две кнопки — два разных действия:

Кнопка	Что делает	Когда использовать
Sync	Переводит только то, что изменилось с последнего запуска	Заполнение контента после подключения или повтор после сбоя
Retranslate	Переводит всё в области видимости заново, с нуля	После изменения глоссария, тональности бренда или правил движка

Обе кнопки находятся в заголовке страницы и охватывают всё, у чего включён Sync. Повторный перевод из заголовка запрашивает подтверждение. Чтобы запустить только отдельные коллекции или глобальные объекты, отметьте их строки: появятся Queue sync (N) и Queue retranslation (N), которые охватят только выбранные строки. Строку можно отметить только при включённом переключателе Sync.

При подключении ничего не переводится. Чтобы перевести уже имеющийся контент, нажмите Sync в заголовке страницы. Добавление целевой локали позже работает так же: следующий Sync заполнит её.

Одновременно выполняется только один запуск на подключение. Остальные запросы встают в очередь и запускаются по порядку.

Retranslate перезаписывает ручные правки

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

Наблюдение за запуском#

Вкладка Workflow runs показывает все запуски: время начала, что их инициировало (Webhook или Manual, затем Sync или Retranslate), какие локали были охвачены, сколько времени занял запуск и его статус. У запущенного или ожидающего запуска есть кнопка Stop. Откройте строку, чтобы увидеть результат по каждой локали.

Статус	Значение
В очереди	Ожидает завершения предыдущего запуска
Выполняется	В процессе
Завершён	Все переводы записаны
Актуален	В области охвата ничего не изменилось с последнего запуска. Это не ошибка
Ошибка	Запуск остановлен. Причина указана в строке запуска
Отменён	Остановлен кем-то из команды

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

Куда попадают переводы#

Каждый перевод записывается в тот же документ или глобальный объект в целевой локали — так работает стандартная модель локализации Payload. Записываются только переведённые поля, остальные не затрагиваются. Обратная запись выполняется от имени сервисного пользователя и не запускает новый запуск.

Существующие переводы сохраняются. При первой синхронизации документа то, что уже есть в целевой локали, остаётся на месте — переводятся только отсутствующие поля. Поле со значением по умолчанию Payload считается отсутствующим. Чтобы заменить существующие переводы, используйте Повторный перевод.

Черновики и опубликованные материалы#

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

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

Режим можно изменить позже на вкладке Settings.

Управление подключением#

Настройки#

Вкладка Settings показывает инстанс, с которым работает подключение, какие коллекции и глобальные объекты имеют включённый Sync, а также состояние подключения: Working или Cannot be reached. Здесь можно изменить название, исходную локаль, целевые локали, движок и режим. Webhook URL при этом сохраняется — повторное развёртывание не требуется.

Адрес и API-ключ задаются при создании подключения и в дальнейшем не могут быть изменены. Чтобы указать другой адрес или ключ, отключитесь и подключитесь заново.

Отключение#

Disconnect в нижней части вкладки Settings останавливает чтение и запись Lingo.dev в инстанс. Подключение удаляется вместе с историей запусков и записями о переведённом контенте. Уже выполненные переводы остаются в Payload. После этого удалите LINGO_WEBHOOK_URL или плагин из конфигурации.

При повторном подключении создаётся новый webhook URL

Новое подключение получает новый URL вебхука — обновите LINGO_WEBHOOK_URL и передеплойте, прежде чем автоматические запуски заработают снова. Первая синхронизация перечитает все документы в области охвата, сохранит переводы, которые уже есть в Payload, и заполнит пробелы.

Ограничения#

Ограничение	Детали
Версия Payload	Payload 3 с настроенной локализацией
Типы полей	`text`, `textarea` и `richText` (только Lexical), помеченные как `localized`
Область применения	Целые коллекции и глобальные объекты. Без выбора отдельных полей
Подключения	Несколько на организацию, один на экземпляр Payload
Параллельные циклы	Один на подключение
Адрес	Только HTTPS

Устранение неполадок#

Подключение завершается ошибкой «Payload rejected the API key». Проверьте ключ, слаг коллекции аутентификации и убедитесь, что useAPIKey включён для этой коллекции.

В коллекции или глобальном объекте отображается «no read + update». Предоставьте сервисному пользователю доступ на чтение и обновление в настройках доступа этой коллекции, затем перезагрузите страницу подключения. Переключатель Sync в строке разблокируется.

Первый запуск завершается ошибкой «The Lingo plugin isn't installed». Добавьте @lingo.dev/payloadcms в раздел plugins конфигурации Payload и передеплойте. Подключение работает без плагина, а синхронизация — нет.

Публикация в Payload не запускает процесс. Убедитесь, что LINGO_WEBHOOK_URL задан, localization настроен, коллекция или глобальный объект находятся в области видимости, сохранение выполнено в исходной локали и это была публикация, а не черновое сохранение, — если только подключение не работает в режиме Draft.

Поле не переводится. У него или у его родителя нет localized: true, либо это не поле типа text, textarea или richText.

Вкладка Settings показывает подключение как Cannot be reached. Убедитесь, что инстанс работает, ключ действителен и все заголовки шлюза по-прежнему корректны. Адрес и ключ нельзя изменить в существующем подключении — если один из них изменился, отключитесь, подключитесь заново и обновите LINGO_WEBHOOK_URL новым Webhook URL.

Следующие шаги#

Движки локализации

Настройте движок для перевода контента Payload

Глоссарии

Зафиксируйте названия продуктов и термины во всех коллекциях

Тональность бренда

Задайте тон, которого должен придерживаться контент на каждом языке