Payload CMS를 로컬라이제이션 엔진에 연결하고 번역할 collection과 global을 선택하면, Lingo.dev가 해당 localized field를 대상 로캘로 번역한 뒤 각 로캘 아래의 Payload에 다시 써 넣습니다.
로컬라이제이션이 활성화되어 있고 Lexical 리치 텍스트 편집기를 사용하는 Payload 3 프로젝트에서 사용할 수 있습니다. 기존 Slate 편집기는 지원되지 않습니다. 로컬라이즈된 text, textarea, richText 필드가 번역되며, 문서의 나머지 내용은 그대로 유지됩니다.
Payload 연동은 조직별로 활성화됩니다. Settings -> Integrations에 보이지 않는다면 문의해 주세요. 바로 활성화해 드릴게요.
시작하기 전에#
필요한 것은 세 가지입니다:
- 로컬라이제이션이 설정된 Payload 3. 소스 로캘과 대상 로캘이 Payload 설정에 있는 로캘과 일치하는지 확인하세요.
- API 키가 있는 서비스 사용자. auth collection(보통
useAPIKey: true)에서users을 설정하고, Lingo.dev용 사용자를 만든 뒤 Payload 관리자에서 해당 사용자의 API 키를 생성하세요. 이 사용자에게는 번역하려는 모든 collection과 global에 대한 읽기 및 업데이트 권한이 필요합니다. - 로컬라이제이션 엔진. 이 엔진의 glossary, 브랜드 보이스, 규칙이 번역 결과를 좌우합니다.
로캘 코드는 Payload 설정과 정확히 일치해야 합니다
Lingo.dev에서 선택하는 로캘은 localization.locales 아래의 코드와 정확히 일치해야 합니다. Payload에 en와 de가 있다면 **English (United States)**가 아니라 English와 German을 선택하세요. en-US와 en는 서로 다른 로캘입니다. 플러그인이 변경 사항을 감지하는 로캘이므로 Payload의 defaultLocale를 소스 로캘로 사용하세요.
Payload 인스턴스 연결하기#
연동 열기
Settings -> Integrations로 이동한 다음, Payload CMS 아래의 Connect를 클릭하세요.
인스턴스 정보 입력
| 필드 | 입력 내용 |
|---|---|
| 연결 이름 | Production 또는 Staging 같은 라벨 |
| Payload Base URL | 인스턴스의 루트 URL입니다. 예: https://cms.example.com. HTTPS만 지원합니다 |
| Auth Collection Slug | 서비스 API 키가 속한 컬렉션입니다. 보통 users입니다 |
| API Key | 서비스 사용자의 API 키 |
| Custom headers | 선택 사항입니다. 인스턴스로 보내는 모든 요청에 함께 전송됩니다 |
Lingo.dev는 다음 단계로 넘어가기 전에 해당 키를 인스턴스에서 확인합니다.
번역할 항목 선택하기
| 설정 | 설명 |
|---|---|
| Collections and Globals | 번역할 항목에 체크하세요. No read + update로 표시된 행은 서비스 사용자에게 해당 권한이 부여될 때까지 비활성화된 상태로 남아 있습니다 |
| Source Locale | 편집자가 작성하는 로캘입니다. Payload의 defaultLocale를 사용하세요 |
| Target Locales | 번역할 대상 로캘 |
| 엔진 | 이 콘텐츠를 번역하는 로컬라이제이션 엔진 |
| Translate draft saves | 끔이면 게시된 변경 사항만 번역합니다. 켜면 초안 저장도 번역하고 번역 결과도 초안으로 유지합니다 |
플러그인 설치하기
마지막 단계에서 webhook URL이 표시됩니다. 지금 복사하세요. 이 URL은 한 번만 표시됩니다. Payload 환경 변수에 LINGO_WEBHOOK_URL로 저장한 뒤, 플러그인을 설치하고 config에 추가하세요:
pnpm add @lingo.dev/payloadcmsimport { 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,
}),
],
});Payload를 다시 배포하세요. 이제부터 소스 로캘에서 게시되는 모든 변경 사항이 번역을 위해 Lingo.dev로 전송됩니다.
플러그인이 하는 일
Lingo.dev에 어떤 field가 localized text인지 알려주는 GET /api/lingo/schema 엔드포인트와, document 또는 global이 변경될 때 Lingo.dev에 신호를 보내는 hook이 추가됩니다. 범위, 로캘, 엔진은 대시보드에서 관리하므로 재배포 없이 바꿀 수 있습니다. hook을 건너뛰고 모든 번역을 대시보드에서 직접 시작하려면 webhookUrl를 생략하세요.
번역 대상 선택하기#
연결 페이지에는 Collections, Globals, Runs의 세 가지 탭이 있습니다.
범위는 collection별, global별로 설정됩니다. 선택한 collection에 있는 모든 document가 포함됩니다. 범위, 로캘, 엔진, 또는 초안 설정을 바꾸려면 페이지 헤더에서 Edit configuration을 클릭하세요. 변경 사항은 재배포 없이 다음 실행부터 적용됩니다.
문서 안에서는 Payload 필드 설정에 따라 번역 대상이 결정됩니다:
| 필드 | 번역 여부 |
|---|---|
text로 표시된 textarea, richText, localized: true 필드 | 예 |
로컬라이즈된 group, array, blocks, 또는 tabs 안에 있는 동일한 필드 유형 | 예 |
| 리치 텍스트에 포함된 블록 및 인라인 블록 | 예, 해당 텍스트 field도 같은 규칙으로 번역됩니다 |
select, radio, checkbox, number, date, relationship, upload, json, code, email, point | 아니요 |
| 로컬라이즈되지 않았고 로컬라이즈된 상위 필드도 없는 필드 | 아니요 |
id, blockType, blockName | 아니요 |
리치 텍스트는 Lexical 트리 형태로 번역됩니다. 서식, 링크, 업로드, 블록 구조는 그대로 유지되고, 내부 텍스트만 바뀝니다. 굵은 텍스트나 링크 때문에 문장이 나뉘어 있어도 하나의 문장으로 번역됩니다.
field를 범위에 포함하려면 Payload에서 해당 field를 localized: true로 표시한 뒤 다시 배포하세요. 다음 실행부터 반영됩니다.
동기화 및 재번역#
자동 실행. 플러그인에서 webhookUrl을 설정해 두면 소스 로캘의 문서나 글로벌 항목을 저장할 때마다 Lingo.dev에 알림이 전송됩니다. 짧은 시간 안에 연달아 저장된 항목은 디바운스되어 한 번의 실행으로 처리됩니다. 다른 로캘에서의 저장, 초안 저장(Translate draft saves가 켜져 있지 않은 경우), 그리고 범위에 포함되지 않은 콘텐츠는 무시됩니다.
수동 실행. 모든 collection, global, document 행에는 버튼이 두 개 있습니다:
| 버튼 | 설명 | 사용 시점 |
|---|---|---|
| Sync | 지난 실행 이후 변경된 내용만 번역합니다 | 연결 후 기존 콘텐츠를 채우거나 실패 후 다시 시도할 때 |
| Retranslate | 해당 행의 모든 항목을 처음부터 다시 번역합니다 | 엔진의 glossary, 브랜드 보이스, 또는 규칙을 변경한 뒤 |
collection을 열면 해당 document로 이동해 하나씩 동기화할 수 있습니다. 두 탭 모두 각 항목이 마지막으로 동기화된 시점을 보여줍니다.
연결한다고 해서 바로 번역이 시작되지는 않습니다. 이미 있는 콘텐츠를 번역하려면 각 collection과 global에서 Sync를 클릭하세요. 나중에 대상 로캘을 추가하는 경우도 마찬가지로, 다음 Sync에서 해당 로캘이 채워집니다.
하나의 연결에서는 한 번에 하나의 실행만 진행됩니다. 추가 요청은 대기열에 쌓이고 순서대로 시작됩니다. 어떤 행이 대기 중이거나 실행 중인 작업에 포함되어 있는 동안에는 해당 행의 버튼에 **Syncing...**가 표시됩니다.
Retranslate는 수동 편집 내용을 덮어씁니다
Retranslate는 범위 안의 모든 번역된 field를 다시 생성하며, 여기에는 팀이 Payload에서 직접 수정한 번역도 포함됩니다. 반면 Sync는 소스 텍스트가 바뀐 field만 다시 생성하므로, 다른 곳의 수동 수정은 유지됩니다.
실행 모니터링#
Runs 탭에서는 모든 실행의 상태, 트리거(Webhook 또는 Manual, sync 또는 retranslate), 시작 시간, 소요 시간을 확인할 수 있습니다. 대기 중이거나 실행 중인 작업은 목록에서 취소할 수 있습니다.
실행을 열면 현재 단계(Payload에서 읽는 중, 번역 중, 다시 쓰는 중), 전체 진행 상황, 대상 로캘별 진행 상황, 그리고 포함된 document, collection, global을 볼 수 있습니다. 각 항목은 Payload 관리자와 연결됩니다.
| 상태 | 의미 |
|---|---|
| Queued | 앞선 실행이 끝나기를 기다리는 중 |
| Running | 진행 중 |
| Completed | 모든 번역이 다시 기록되었습니다 |
| Up to date | 지난 실행 이후 범위 안에서 변경된 내용이 없습니다. 실패는 아닙니다 |
| Failed | 실행이 중단되었습니다. 이유는 실행 상세 상단에 표시됩니다 |
| Cancelled | 팀의 누군가가 중단했습니다 |
실행에 실패해도 이미 기록된 내용은 그대로 유지됩니다. 오류 메시지에는 기록되지 않은 문서가 표시되며, 다음 동기화에서 해당 문서들을 다시 시도합니다. 실행 도중 편집자가 저장한 문서는 건너뛰고, 다음 실행에서 다시 처리됩니다.
번역이 저장되는 위치#
각 번역은 Payload의 로컬라이제이션 모델에 따라 대상 로캘 아래의 동일한 문서 또는 글로벌에 기록됩니다. 번역된 필드만 기록되며, 나머지 필드는 그대로 유지됩니다. 다시 쓰기는 서비스 사용자로 실행되며 새 실행을 트리거하지 않습니다.
기존 번역은 유지됩니다. document를 처음 동기화할 때는 대상 로캘에 이미 있는 내용을 그대로 두고, 누락된 field만 번역합니다. 아직 Payload 기본값이 들어 있는 field는 누락된 것으로 간주됩니다. 기존 번역을 교체하려면 Retranslate를 사용하세요.
초안 vs 게시됨#
초안 저장 시 번역이 꺼져 있으면(기본값), 게시된 변경 사항만 실행을 시작하고 번역은 기록되는 즉시 게시됩니다. Payload는 문서 전체를 게시하므로, 해당 문서에 게시되지 않은 초안 수정 사항이 있다면 번역과 함께 함께 공개됩니다.
이 옵션을 켜면 초안 저장도 실행을 시작합니다. Lingo.dev는 소스의 최신 초안을 읽고 각 번역을 초안으로 기록합니다. 누군가 Payload에서 번역을 게시하기 전까지는 독자에게 보이는 내용이 바뀌지 않습니다. 번역 품질을 평가할 때나 번역이 검토를 거치는 워크플로우에서 유용합니다.
연결 관리#
Webhook URL 재생성#
Connection 페이지 헤더에서 메뉴를 열고 Regenerate webhook URL을 선택하세요. 기존 URL은 즉시 더 이상 작동하지 않습니다. LINGO_WEBHOOK_URL을 업데이트한 뒤 다시 배포하세요. 연결을 수정해도 URL은 유지됩니다.
연결 해제#
Settings -> Integrations -> Payload CMS에서 연결을 해제하세요. 그러면 연결, 실행 기록, 그리고 무엇이 번역되었는지에 대한 기록이 삭제됩니다. 이미 기록된 번역은 Payload에 그대로 남습니다. 이후에는 config에서 LINGO_WEBHOOK_URL 또는 플러그인을 제거하세요.
다시 연결하면 webhook URL도 새로 발급됩니다
새 연결에는 새 webhook URL이 발급되므로, 자동 실행을 다시 사용하려면 먼저 LINGO_WEBHOOK_URL를 업데이트하고 다시 배포해야 합니다. 첫 번째 동기화에서는 범위 안의 모든 document를 다시 읽고, Payload에 이미 있는 번역은 유지한 채 비어 있는 부분만 채웁니다.
제한 사항#
| 제한 | 세부 정보 |
|---|---|
| Payload 버전 | 로컬라이제이션이 설정된 Payload 3 |
| 필드 유형 | text로 표시된 textarea, richText, localized 필드(Lexical만 해당) |
| 범위 | 전체 컬렉션 및 글로벌. 필드별 선택은 지원하지 않음 |
| 연결 | 조직당 여러 개 가능, Payload 인스턴스당 하나 |
| 동시 실행 | 연결당 하나 |
| Base URL | HTTPS만 지원 |
문제 해결#
"Payload rejected the API key" 오류와 함께 연결에 실패합니다. 키, auth collection slug, 그리고 해당 collection에서 useAPIKey이 활성화되어 있는지 확인하세요.
collection 또는 global에 "No read + update"가 표시됩니다. 해당 collection의 access config에서 서비스 사용자에게 읽기 및 업데이트 권한을 부여한 뒤 구성을 다시 여세요.
첫 실행이 "The Lingo plugin isn't installed" 오류와 함께 실패합니다. Payload config의 @lingo.dev/payloadcms에 plugins를 추가하고 다시 배포하세요. 연결은 플러그인 없이도 가능하지만 동기화는 그렇지 않습니다.
Payload에서 게시해도 실행이 시작되지 않습니다. LINGO_WEBHOOK_URL이 설정되어 있는지, localization가 구성되어 있는지, 해당 collection 또는 global이 범위에 포함되어 있는지, 저장이 소스 로캘에서 이루어졌는지, 그리고 초안 저장이 아니라 게시였는지 확인하세요.
필드가 번역되지 않는 경우 해당 필드나 상위 항목에 localized: true이 없거나, text, textarea, richText 필드가 아니기 때문입니다.
연결에 "Couldn't reach this Payload instance"가 표시됩니다. 인스턴스가 실행 중인지, 키가 아직 유효한지, 그리고 게이트웨이 헤더가 여전히 작동하는지 확인하세요. Settings -> Integrations에서 연결을 업데이트하세요.
