Payload CMS
Переводите локализуемые поля Payload 3, сохраняйте структуру ресурсов и выбирайте, как изменения оригинала отражаются в целевых локалях.
В Payload у каждого локализуемого поля уже есть место для языковых версий. Подключение Lingo.dev читает выбранные исходные поля, переводит их с помощью движка локализации и записывает результат в те же ресурсы для целевых локалей. Коллекции, глобальные объекты и публикация остаются в Payload.
В меню Studio 2.5 откройте Интеграции в разделе Studio 2.5, а не в разделе Настройки. Прежние ссылки для подключения и настройки продолжают работать.
Начните с одного ресурса и ручной синхронизации. Проверьте результат, затем настройте уведомления об изменениях оригинала, если перевод должен автоматически обновляться после редактирования.
Интеграция с Payload CMS доступна на плане Enterprise. Актуальные условия — на странице тарифов. Если у организации нет доступа на текущем плане, в подразделе Интеграции раздела Настройки рядом с Payload появится пометка Недоступно на вашем плане.
Подготовьте Payload и служебную учётную запись #
Используйте Payload 3 с настроенной локализацией. Перевод форматированного текста работает с редактором Lexical. Устаревший редактор Slate не поддерживается. Ваш экземпляр должен быть доступен Lingo.dev по HTTPS.
Создайте служебную учётную запись в коллекции аутентификации с useAPIKey: true — обычно это users. Предоставьте ей права на чтение и обновление всех коллекций и глобальных объектов, которые собираетесь переводить. Все изменения будут записываться от имени этой учётной записи. Если шлюзу нужны дополнительные заголовки, укажите их при подключении и храните их значения в секрете.
Исходная локаль подключения должна совпадать с localization.defaultLocale в Payload — плагин отслеживает изменения именно в ней. Коды исходной и целевых локалей должны точно совпадать с кодами в настройках Payload: en и en-US обозначают разные локали. Выберите доступный движок локализации в подключённой организации Lingo.dev. Если добавить подключение не удаётся, проверьте разрешения организации и право доступа к подключениям.
Подключите экземпляр и откройте доступ к его схеме #
Откройте подраздел Интеграции раздела Настройки и выберите Подключить для Payload CMS. Укажите имя подключения, корневой адрес экземпляра, коллекцию аутентификации, служебный ключ API и заголовки шлюза, если они нужны. Выберите Подключить, чтобы проверить доступ и сохранить подключение. Сохраните URL вебхука, который появится после этого: он понадобится для автоматических уведомлений.
Установите плагин в проект Payload:
pnpm add @lingo.dev/payloadcmsДобавьте lingo в существующий массив plugins. В этом фрагменте показаны настройки плагина. Не удаляйте коллекции, глобальные объекты, настройки локализации и другие плагины проекта:
import { buildConfig } from "payload";
import { lingo } from "@lingo.dev/payloadcms";
export default buildConfig({
plugins: [
lingo({ webhookUrl: process.env.LINGO_WEBHOOK_URL }),
],
});Плагин всегда регистрирует GET /api/lingo/schema. Lingo.dev использует этот эндпоинт, чтобы находить локализуемые поля. Вы можете создать подключение до установки плагина, но для перевода нужен эндпоинт схемы.
Для автоматических уведомлений скопируйте URL вебхука подключения в переменную окружения LINGO_WEBHOOK_URL в Payload. Храните его как секретный ключ доступа: любой, у кого есть этот URL, может отправлять запросы уведомлений. После изменения плагина или окружения повторно разверните Payload. Если нужен только ручной перевод, не задавайте webhookUrl — плагин всё равно откроет доступ к схеме.
В Studio выберите экземпляр в разделе Подключённые, затем — Настроить. Укажите движок локализации, исходную и целевые локали, а также режим записи перевода. Выберите Продолжить, затем укажите коллекции и глобальные объекты для перевода. Режимы публикации описаны ниже.
Переведите один ресурс #
Выберите одну коллекцию или глобальный объект с небольшим локализуемым текстовым полем и одну целевую локаль. Перед синхронизацией запишите текущие значения поля в исходной и целевой локалях в Payload.
Выберите режим в зависимости от того, как нужно публиковать результат:
| Режим | Источник и запись перевода |
|---|---|
| Черновик | Читает исходный контент из черновика и записывает переведённые поля в черновики для проверки в Payload. |
| Публикация | Обрабатывает опубликованные изменения и публикует переводы. |
В Payload у каждого документа один общий черновик, который публикуется целиком. Поэтому, если записать перевод в опубликованный документ с неопубликованными правками, эти правки тоже будут опубликованы. В таком случае режим публикации оставляет документ без изменений и сообщает, что перевести его не удалось. Опубликуйте правки или восстановите опубликованную версию в Payload, затем запустите синхронизацию ещё раз. Чтобы видеть эти правки, пользователь, которому принадлежит ключ API, должен иметь доступ readVersions ко всем версиям выбранных коллекций и глобальных объектов. Если этот доступ ограничен фильтрами, режим публикации оставляет их опубликованные документы без изменений. Если документ ещё ни разу не публиковался, эта проверка пропускается: режим публикации записывает в него перевод, а сам документ остаётся черновиком. Проверка выполняется прямо перед каждой записью, поэтому черновик, сохранённый между проверкой и записью, всё же может быть опубликован вместе с переводом. Не сохраняйте черновики документов, пока синхронизация записывает в них переводы, а после неё проверьте статус их публикации. Работа с черновиками также зависит от конфигурации Payload. При тестировании обновления проверьте текущую опубликованную версию.
Выберите Синхронизировать, откройте соответствующий запуск рабочего процесса и проверьте целевое поле непосредственно в Payload. Проверьте формулировки, ссылки, структуру форматированного текста, локаль и статус публикации. Затем прочитайте результат на сайте, который использует этот контент. Само по себе подключение не переводит каталог.
Первая синхронизация сохраняет уже заполненные переводы, не заменяя их. Она заполняет недостающие поля, в том числе те, где текущее значение лишь повторяет значение Payload по умолчанию. Если поле осталось без изменений, сравните его значение с состоянием до синхронизации, прежде чем запрашивать замену.
Выберите ресурсы и поля #
В таблицах Коллекции и Глобальные есть переключатели Синхронизировать, состояние которых сохраняется. Выбор коллекции охватывает её документы, а выбор глобального объекта — сам этот ресурс. Действия в заголовке обрабатывают ресурсы с включённой синхронизацией. Если доступны действия с выбранными строками, они ставят в очередь только выбранные ресурсы, не меняя сохранённый выбор подключения.
В этих ресурсах схема определяет локализуемые поля text, textarea и richText редактора Lexical. Она также находит текст внутри локализуемых групп, массивов, блоков и вкладок, включая вложенные и встроенные блоки форматированного текста.
Нелокализуемые поля и структурные значения, такие как id, blockType и blockName, не попадают в текст для перевода. Поля выбора, числа, связи, загрузки, код и произвольный JSON не становятся доступными для перевода только потому, что выбрана их коллекция. Чтобы включить ещё одно текстовое поле, настройте его локализацию в Payload и повторно разверните проект.
При обработке Lexical контекст предложений сохраняется даже при форматировании и ссылках внутри текста. Затем дерево восстанавливается вместе со ссылками, медиафайлами и блоками. Прежде чем расширять набор ресурсов для перевода, проверьте результат на типичном документе, особенно если в проекте есть собственные поля или расширения редактора.
Обновляйте переводы вслед за оригиналом #
Если настроены URL вебхука и локаль по умолчанию, плагин отправляет уведомления после изменений в исходной локали. Уведомление содержит указатель на ресурс, а не содержимое документа. Lingo.dev повторно читает контент с сохранёнными служебными учётными данными, учитывает выбранные ресурсы и режим подключения и объединяет близкие по времени уведомления перед обработкой.
Запись в целевые локали не запускает новый перевод. Сбой отправки уведомления также не мешает сохранить изменения в редакторе, поэтому успешное сохранение само по себе не подтверждает доставку. Если изменение было пропущено, проверьте историю запусков и выполните ручную синхронизацию, чтобы обновить контент. Сохранение черновиков учитывается в режиме «Черновик». Сохранение в целевой локали или в ресурсе за пределами выбранного набора не считается изменением оригинала для этого подключения.
Используйте Синхронизировать, чтобы обработать изменения оригинала и заполнить недостающий контент в целевых локалях. Синхронизация сравнивает контент с доступной базовой версией. Если артефакт предыдущей исходной версии недоступен, при восстановлении затронутый контент может быть создан заново. Поэтому проверьте различия: не стоит рассчитывать, что все ручные правки сохранятся. После добавления целевой локали запустите синхронизацию, чтобы заполнить её.
Используйте Перевести заново, если хотите заменить выбранные переводы, включая поля с ручными правками. Например, после значительных изменений в инструкциях движка локализации может понадобиться новый перевод, даже если оригинал не менялся. Запросы встают в очередь за текущим запуском подключения. Повторная отправка одного и того же действия не ускоряет его выполнение.
Восстановите изменённый или частично записанный документ #
На этапе записи перевода исходный контент читается повторно. Если после планирования его изменили в редакторе, документ пропускается: переведённые значения не применяются к другой версии или другому порядку элементов массива. Следующая синхронизация учтёт изменения оригинала.
Успешно записанные данные сохраняются даже при сбое или отмене запуска. В разделе Запуски рабочих процессов различайте завершённые, актуальные, пропущенные, неудавшиеся и отменённые задачи. Перед повторной попыткой проверьте затронутые ресурсы. Кнопка Остановить, если она доступна, отменяет текущие задачи, но не откатывает уже записанные поля. Результат «Актуально» означает, что среди выбранного контента не было изменений для обработки.
Если результат так и не появился, проверьте эндпоинт схемы, локализацию и тип поля, права служебной учётной записи на чтение и обновление, точность кода локали, выбор ресурсов для синхронизации, режим и настройки вебхука в окружении. Прежде чем запрашивать повторный перевод, восстановите доступ к экземпляру или решите проблему с отклонённым ключом.
Измените настройки или отключите интеграцию #
Меняйте выбранные ресурсы, локали, движок локализации и режим в Studio. Переименовать подключение или изменить его учётные данные вы можете в подразделе Интеграции раздела Настройки. При этих изменениях URL вебхука сохраняется.
Чтобы сменить ключ API, откройте подключение в подразделе Интеграции раздела Настройки и выберите Заменить ключ. Введите ключ из той же коллекции аутентификации и заново укажите все дополнительные заголовки, которые по-прежнему нужны экземпляру. Указанные заголовки заменят сохранённые.
Для изменения адреса экземпляра нужно новое подключение. Настройте ресурсы и поля для перевода и укажите новый URL вебхука в окружении Payload, прежде чем снова полагаться на автоматические уведомления.
Отключение удаляет локальную историю подключения и состояние синхронизации, а также прекращает дальнейшее чтение и запись. Уже переведённый контент остаётся в Payload. Удалите старое значение переменной окружения вебхука или обработчик и отдельно отзовите служебный ключ, если он больше не нужен.
Новое подключение создаёт новую базовую версию для сравнения. Первая синхронизация сохраняет существующие переводы, которые соответствуют условиям сохранения, и заполняет пробелы, но не восстанавливает локальную историю запусков предыдущего подключения. Проверьте первый запуск так же, как при любом новом подключении.