Payload 콘텐츠 관리 시스템 플러그인
편집기의 저장 동작은 그대로 유지하면서 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()],
});이 예시는 관련 필드만 보여 주며, 단독으로 사용할 수 있는 전체 콘텐츠 관리 시스템 설정은 아닙니다. 기존 컬렉션, 글로벌, 데이터베이스 어댑터, 편집기와 기타 필수 설정은 유지하세요.
이 패키지는 lingo과 LingoPluginOptions를 내보냅니다. lingo()은 Payload 플러그인을 반환하며, 유일한 옵션은 webhookUrl?: string입니다. 해당 주소 없이 등록해도 스키마 엔드포인트가 제공되므로, 자동 알림을 설정하기 전에 스키마 탐색부터 구성할 수 있습니다.
Payload 인증으로 스키마 확인 #
플러그인은 기존 엔드포인트를 유지하면서 Payload의 API 기본 경로 아래에 GET /lingo/schema을 추가합니다. 기본 경로는 일반적으로 /api/lingo/schema입니다. 애플리케이션에 있는 컬렉션이나 글로벌을 요청하세요.
GET /api/lingo/schema?collection=articles
GET /api/lingo/schema?global=homepage애플리케이션에서 사용하는 슬러그를 입력하세요. 핸들러를 사용하려면 인증된 Payload 사용자여야 합니다. 인증되지 않은 요청에는 401을, 엔터티가 지정되지 않았거나 존재하지 않으면 404를 반환합니다. 연동 기능은 설정된 Payload 인증 권한으로 이 엔드포인트를 읽습니다.
응답에는 필드 이름, 유형, 로컬라이제이션 플래그, 중첩 구조와 해석된 관련 기본값이 담깁니다. 텍스트를 찾는 데 필요한 중첩 그룹, 배열, 블록, 탭과 Lexical 블록 스키마 중 지원되는 항목이 포함됩니다. 전체 Payload 설정을 직렬화하지 않고, 관련 없는 관리자 및 편집기 설정은 제외합니다.
기본값은 처리 대상 중 작성자에게 표시되는 텍스트 필드에 대해 해석됩니다. 제한되거나 숨겨진 기본값, 구조용 필드, 해석하거나 직렬화할 수 없는 값은 기본값 출력에서 제외됩니다. 스키마는 연동 기능이 살펴볼 수 있는 항목을 나타내며, 스키마를 가져오는 것만으로 번역이 요청되지는 않습니다.
원본 변경 후 연동 기능에 알림 전송 #
Lingo.dev에서 Payload를 연결한 다음, 발급된 권한 부여 주소를 서버 설정에 저장하고 플러그인에 전달하세요.
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 배열에서 lingo() 대신 plugin을 사용하세요. 환경 변수 이름은 애플리케이션에 맞게 정하면 됩니다. 이 주소 자체에 알림 전송 권한이 있으므로 브라우저 번들, 커밋된 소스 코드, 로그에 포함하지 마세요.
주소와 localization.defaultLocale이 모두 설정되면 플러그인은 기존 훅을 유지하면서 컬렉션과 글로벌에 afterChange 훅을 추가합니다. 컬렉션 알림은 슬러그와 문서 식별자를 보내며, 문서 상태를 선택적으로 포함합니다. 글로벌 알림은 슬러그를 보냅니다. 전송 데이터는 전체 문서가 아닌 참조 정보입니다. 연동 기능은 설정된 인증 정보로 콘텐츠를 다시 읽습니다.
다른 로캘에서 이루어진 것으로 명시된 변경은 건너뜁니다. 따라서 대상 언어의 번역 결과가 반영될 때마다 원본 번역이 반복해서 시작되는 것을 방지합니다. 로캘이 명시되지 않은 변경은 알림을 발생시킬 수 있습니다. 요청 제한 시간은 5초이며, 편집기에서 저장을 완료할 수 있도록 전송 오류는 무시합니다. 또한 HTTP 응답 상태가 성공이 아니더라도 훅 때문에 저장이 실패하지는 않습니다.
연결 결과 확인 #
먼저 연동 기능이 Payload 인증 정보로 원하는 스키마를 읽을 수 있는지 확인하세요. 그런 다음 연동 워크플로를 통해 권한에 따라 원본을 변경하고, 대상 로캘에 반영된 결과를 확인하세요. 원본은 저장되지만 대상 로캘에 결과가 도착하지 않는다면, 편집기에서 저장됐다는 이유만으로 전달까지 완료됐다고 판단하지 마세요. 알림이 수락되었는지와 번역 실행 상태를 확인하세요.
Lingo.dev의 연동 설정에서 컬렉션, 대상 로캘, 로컬라이제이션 엔진을 선택하세요. 이 항목들은 플러그인 옵션이 아니므로, 애플리케이션의 플러그인 등록 설정을 바꾸지 않고도 변경할 수 있습니다.