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를 사용합니다. 번역할 모든 컬렉션과 글로벌에 대해 해당 사용자에게 읽기 및 업데이트 권한을 부여하세요. 쓰기 작업은 이 사용자가 수행한 것으로 기록됩니다. 게이트웨이에 추가 헤더가 필요하면 연결할 때 입력하고, 헤더 값은 비밀로 유지하세요.
연결의 원본 로캘을 플러그인이 변경 사항을 감지하는 Payload의 localization.defaultLocale와 일치시키세요. 원본 및 대상 코드는 Payload에 설정된 코드와 정확히 일치해야 합니다. en와 en-US는 서로 다른 로캘을 나타냅니다. 연결된 Lingo.dev 조직에서 이용할 수 있는 로컬라이제이션 엔진을 선택하세요. 연결을 추가할 수 없다면 조직의 권한과 연결 기능 이용 권한을 확인하세요.
인스턴스 연결하고 스키마 노출하기 #
설정 → 연동을 열고 Payload CMS의 연결을 선택하세요. 연결 이름, 인스턴스의 루트 주소, 인증 컬렉션, 서비스 API 키, 필요한 게이트웨이 헤더를 입력하세요. 연결을 선택하면 접근 가능 여부를 확인하고 연결을 저장합니다. 이후 표시되는 웹훅 URL은 자동 알림에 사용할 수 있도록 보관하세요.
Payload 프로젝트에 플러그인을 설치하세요.
pnpm add @lingo.dev/payloadcms기존 plugins 배열에 lingo을 추가하세요. 아래 예시는 플러그인 설정 부분만 보여 줍니다. 프로젝트의 컬렉션, 글로벌, 로컬라이제이션 설정과 다른 플러그인은 그대로 유지하세요.
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을 Payload의 LINGO_WEBHOOK_URL 환경 변수에 복사하세요. 이 URL만 있으면 알림 요청을 보낼 수 있으므로 비밀 접근 정보로 취급하세요. 플러그인이나 환경을 변경한 뒤에는 Payload를 다시 배포하세요. 수동 번역만 사용하려면 webhookUrl를 생략하세요. 이 경우에도 플러그인은 스키마를 노출합니다.
Studio에서 연결됨 아래의 인스턴스를 선택한 다음 설정하기를 선택하세요. 로컬라이제이션 엔진, 원본 및 대상 로캘, 결과 기록 모드를 선택하세요. 계속을 선택한 다음 번역할 컬렉션과 글로벌을 선택하세요. 게시 모드는 아래에서 설명합니다.
리소스 하나 번역하기 #
로컬라이제이션이 설정된 짧은 텍스트 필드가 있는 컬렉션이나 글로벌 하나와 대상 로캘 하나를 선택하세요. 동기화를 실행하기 전에 Payload에서 현재 원본 값과 대상 값을 확인해 두세요.
원하는 게시 결과에 따라 모드를 선택하세요.
| 모드 | 원본 및 결과 기록 |
|---|---|
| 초안 | 초안 상태의 원본 콘텐츠를 읽고, Payload에서 검토할 수 있도록 번역된 필드를 초안으로 기록합니다. |
| 게시 | 게시된 변경 사항을 처리하고 번역을 게시된 상태로 기록합니다. |
Payload는 문서마다 하나의 공유 초안을 유지하고 초안 전체를 한 번에 게시합니다. 따라서 이미 게시된 문서에 미게시 수정 사항이 있는 상태에서 번역을 저장하면 수정 사항도 함께 게시됩니다. 이를 방지하기 위해 게시 모드는 해당 문서를 변경하지 않고 번역을 실패로 보고합니다. Payload에서 수정 사항을 게시하거나 게시된 버전으로 되돌린 다음 동기화를 다시 실행하세요. 이러한 수정 사항을 확인하려면 API 키에 연결된 사용자에게 선택한 컬렉션과 글로벌의 모든 버전에 대한 readVersions 접근 권한이 있어야 합니다. 이 접근 권한에 필터가 적용되어 있으면 게시 모드는 해당 컬렉션과 글로벌의 게시된 문서를 변경하지 않습니다. 한 번도 게시한 적이 없는 문서는 이 검사를 건너뜁니다. 게시 모드가 번역을 저장해도 해당 문서는 초안 상태로 유지됩니다. 검사는 내용을 저장하기 직전에 매번 실행되므로, 검사와 저장 사이에 저장된 초안은 번역과 함께 게시될 수 있습니다. 동기화가 문서에 내용을 저장하는 동안에는 해당 문서의 초안을 저장하지 말고, 동기화가 끝난 뒤 게시 상태를 확인하세요. 초안 처리 방식은 Payload 설정에 따라서도 달라지므로, 업데이트를 테스트할 때는 현재 공개된 버전을 확인하세요.
동기화를 실행하고 해당 워크플로 실행을 연 다음 Payload에서 실제 대상 필드를 확인하세요. 표현, 링크, 서식 있는 텍스트 구조, 로캘, 게시 상태를 점검하세요. 그런 다음 해당 콘텐츠를 사용하는 사이트에서도 읽어 보세요. 연결만으로는 카탈로그가 번역되지 않습니다.
첫 동기화에서는 완성된 기존 번역을 덮어쓰지 않고 유지합니다. 현재 값이 Payload 기본값을 그대로 반복하는 필드를 포함해 누락된 필드를 채웁니다. 필드가 그대로 유지되었다면 교체를 요청하기 전에 해당 값을 앞서 확인해 둔 상태와 비교하세요.
리소스와 필드 선택하기 #
컬렉션과 글로벌 표에는 선택 상태가 유지되는 동기화 스위치가 있습니다. 컬렉션을 선택하면 해당 컬렉션의 문서가 포함되고, 글로벌을 선택하면 해당 리소스가 포함됩니다. 헤더의 작업은 활성화된 리소스를 처리합니다. 행 선택 작업이 제공되는 경우에는 연결에 저장된 선택 범위를 바꾸지 않고, 선택한 범위만 큐에 추가합니다.
이 리소스 안에서 스키마는 로컬라이제이션이 설정된 text, textarea, Lexical richText 필드를 선택합니다. 로컬라이제이션이 설정된 그룹, 배열, 블록, 탭 내부의 텍스트도 따라가며, 중첩된 서식 있는 텍스트 블록과 인라인 서식 있는 텍스트 블록도 포함합니다.
로컬라이제이션이 설정되지 않은 필드와 id, blockType, blockName 같은 구조 값은 번역할 텍스트에 포함되지 않습니다. 선택 항목, 숫자, 관계, 업로드, 코드, 임의의 JSON은 해당 컬렉션을 선택했다는 이유만으로 번역 대상이 되지 않습니다. 다른 텍스트 필드를 포함하려면 Payload에서 해당 필드의 로컬라이제이션을 설정하고 다시 배포하세요.
Lexical 처리 과정에서는 인라인 서식과 링크에 걸친 문장의 맥락을 유지한 뒤, 링크, 미디어, 블록을 포함한 트리를 재구성합니다. 범위를 넓히기 전에 대표적인 문서로 테스트하세요. 특히 프로젝트에서 사용자 지정 필드나 편집기 확장 기능을 사용한다면 꼭 확인하세요.
원본 변경 사항에 맞춰 번역 유지하기 #
웹훅 URL과 기본 로캘이 설정되어 있으면 플러그인은 원본 로캘의 콘텐츠가 변경된 후 알림을 보냅니다. 알림에는 문서 본문이 아닌 리소스 참조가 포함됩니다. Lingo.dev는 저장된 서비스 인증 정보로 콘텐츠를 다시 읽고 연결의 범위와 모드를 적용하며, 짧은 시간 간격으로 들어온 알림을 묶어 처리합니다.
대상 로캘에 내용을 기록해도 추가 번역은 실행되지 않습니다. 알림 전송에 실패해도 편집자의 저장 작업은 실패하지 않으므로, 저장 성공만으로는 알림이 전달되었다고 볼 수 없습니다. 변경 사항이 누락되었다면 실행 기록을 확인하고 수동 동기화로 콘텐츠를 일치시키세요. 초안 저장은 초안 모드에서 처리 대상이 됩니다. 대상 로캘의 저장이나 범위 밖 리소스의 변경은 이 연결에서 원본 변경으로 간주되지 않습니다.
변경된 원본을 반영하거나 누락된 대상 콘텐츠를 채우려면 동기화를 사용하세요. 동기화는 사용 가능한 기준 상태와 콘텐츠를 비교합니다. 이전 원본 산출물을 사용할 수 없으면 복구 과정에서 해당 콘텐츠가 다시 생성될 수 있습니다. 수동 수정 사항이 모두 유지될 것이라고 가정하지 말고 변경 전후의 차이를 확인하세요. 대상 로캘을 추가한 후에는 동기화를 실행해 내용을 채우세요.
수동으로 편집한 필드를 포함해 선택한 번역을 교체하려면 다시 번역을 사용하세요. 예를 들어 로컬라이제이션 엔진의 지침을 크게 변경했다면 원본이 같아도 새 결과가 필요할 수 있습니다. 요청은 해당 연결에서 실행 중인 작업 뒤에 대기하므로, 같은 작업을 반복해서 요청해도 더 빨리 완료되지 않습니다.
변경되었거나 일부만 기록된 문서 복구하기 #
결과 기록 단계에서는 원본 콘텐츠를 다시 읽습니다. 처리 계획을 세운 뒤 편집자가 원본을 변경했다면, 다른 개정 버전이나 배열 순서에 번역 값을 적용하는 대신 해당 문서를 건너뜁니다. 이후 동기화에서 새 원본에 맞춰 처리합니다.
실행이 실패하거나 취소되어도 성공적으로 기록된 내용은 유지됩니다. 워크플로 실행에서 완료, 최신 상태, 건너뜀, 실패, 취소된 작업을 구분하고, 다시 시도하기 전에 영향을 받은 리소스를 확인하세요. 중지는 가능한 경우 진행 중인 작업을 취소하지만 이미 기록된 필드를 되돌리지는 않습니다. 최신 상태라는 결과는 선택한 범위에 처리할 변경 사항이 없었다는 뜻입니다.
결과가 전혀 나타나지 않으면 스키마 엔드포인트, 필드의 로컬라이제이션 설정과 유형, 서비스 사용자의 읽기 및 업데이트 권한, 정확한 로캘 코드, 리소스 동기화 선택 상태, 모드, 웹훅 환경 설정을 확인하세요. 인스턴스에 접근할 수 없거나 키가 거부된다면 다시 번역을 요청하기 전에 문제를 해결하세요.
설정 변경 또는 연결 해제하기 #
Studio에서 리소스 선택, 로캘, 로컬라이제이션 엔진, 모드를 변경하세요. 연결 이름을 바꾸거나 인증 정보를 관리하려면 설정 → 연동을 사용하세요. 이 설정을 변경해도 웹훅 URL은 유지됩니다.
API 키를 교체하려면 설정 → 연동에서 연결을 열고 키 교체를 선택하세요. 같은 인증 컬렉션의 키를 입력하고, 인스턴스에 여전히 필요한 사용자 지정 헤더도 모두 다시 입력하세요. 새로 입력한 헤더가 저장된 헤더를 대체합니다.
인스턴스 주소를 변경하려면 새 연결이 필요합니다. 자동 알림을 다시 사용하기 전에 새 연결의 번역 범위를 설정하고 Payload 환경의 웹훅 URL을 새 값으로 업데이트하세요.
연결을 해제하면 해당 연결의 로컬 기록과 동기화 상태가 삭제되고 이후의 읽기 및 쓰기가 중지됩니다. 기존 번역 콘텐츠는 Payload에 남습니다. 이전 웹훅 환경 변수 값이나 훅을 제거하고, 서비스 키가 더 이상 필요하지 않다면 별도로 폐기하세요.
새 연결을 만들면 기준 상태도 새로 설정됩니다. 첫 동기화에서는 유지 조건을 충족하는 기존 번역을 보존하고 누락된 부분을 채우지만, 이전 연결의 로컬 실행 기록을 복원하지는 않습니다. 다른 새 연결을 설정할 때와 마찬가지로 첫 실행 결과를 확인하세요.