Lingo.dev는 번역을 코드와 항상 동기화된 상태로 유지합니다. 변경이 생길 때마다 바뀐 콘텐츠를 감지하고, 연결된 로컬라이제이션 엔진으로 번역한 뒤 — 용어집 규칙, 브랜드 보이스, 로캘별 모델 구성을 일관되게 적용해 — 결과를 커밋하거나 풀 리퀘스트를 엽니다. 미완성 번역은 프로덕션에 절대 반영되지 않습니다.
통합 방식 선택#
각 통합 방식마다 전용 가이드가 있습니다. 현재 환경에 맞는 방식을 선택하세요:
| 통합 방식 | 실행 방식 |
|---|---|
| GitHub App | 한 번만 설치하면 됩니다. Lingo.dev가 기본 브랜치로의 push와, 활성화한 경우 풀 리퀘스트에서 로컬라이제이션을 대신 실행합니다. 러너도, API 키 시크릿도, lockfile도 필요 없습니다. |
| GitHub Actions | GitHub Actions 파이프라인에서 @lingo.dev/cli을 설치하고 lingo push을 실행한 뒤, 결과를 커밋하거나 PR을 엽니다. |
| GitLab CI/CD | GitLab 파이프라인 작업에서 @lingo.dev/cli을 설치하고 lingo push을 실행합니다. |
| Bitbucket Pipelines | Bitbucket 파이프라인 단계에서 @lingo.dev/cli을 설치하고 lingo push을 실행합니다. |
GitHub App은 Lingo.dev 서버에서 실행됩니다. 그 외 모든 통합은 Lingo.dev CLI를 실행하므로, Node.js 22+를 지원하는 어떤 CI/CD 환경에서든 퍼스트파티 통합 없이도 로컬라이제이션을 직접 실행할 수 있습니다.
GitHub App 작동 방식#
앱을 한 번 설치하고 저장소에 .lingo/config.json를 추가하면 됩니다. 그다음부터는 Lingo.dev가 로컬라이제이션을 대신 실행합니다. 파이프라인도, API 키 시크릿도, lockfile도 필요 없습니다:
- 변경 감지 - 별도 설정 없이 기본 브랜치에 대한 push에 반응하며,
onPullRequest를 활성화하면 풀 리퀘스트에도 반응하고, 구성한 소스 패턴을 기준으로 변경된 파일을 확인합니다. - 변경분만 번역 -
engineId에 지정된 엔진으로 변경된 소스 콘텐츠를 전송합니다. - 결과를 GitHub에 반영 - 기본 브랜치 push에서는 번역용 풀 리퀘스트를 열거나 업데이트하고, 풀 리퀘스트에서는 번역된 파일을 PR 브랜치에 커밋한 뒤 상태 코멘트를 남깁니다.
- 복구 및 배치 처리 - 이전 실행에서 놓친 변경 사항을 감지하고, 매우 큰 업데이트는 여러 커밋으로 나눠 처리합니다.
승인 단계 이후에만 실행되도록 설정하거나, 풀 리퀘스트에서 /lingo 명령으로 번역을 수동 실행할 수도 있습니다. 전체 구성은 GitHub App 가이드를 참고하세요.
CLI 통합은 이렇게 작동합니다#
GitHub Actions, GitLab CI/CD, Bitbucket 통합은 모두 기존 파이프라인의 한 단계에서 동일한 Lingo.dev CLI를 실행합니다. 필요한 것은 두 가지입니다. .lingo/config.json 설정 파일과 인증용 LINGO_API_KEY입니다.
실행할 때마다 작업은 CLI(npm install -g @lingo.dev/cli)를 설치하고 lingo push를 실행합니다. 이 명령은 다음을 수행합니다.
- 소스 파일 탐색 - 번역 가능한 콘텐츠를 찾기 위해 bucket configuration을 읽습니다.
- 변경 사항 감지 -
.lingo/lock.jsonlockfile과 비교해 새로 추가되었거나 수정된 문자열을 식별하므로, 변경분만 번역됩니다. - 번역 수행 - 구성된 로컬라이제이션 엔진으로 변경된 콘텐츠를 전송하며, 용어집, 브랜드 보이스, 로캘별 모델 설정 등 모든 규칙이 적용됩니다.
- 결과 반영 - 대상 로캘 파일을 제자리에서 업데이트하고
.lingo/lock.json을 새로 고칩니다.
그다음 파이프라인은 각 플랫폼의 기본 도구를 사용해 결과를 커밋하거나 pull request를 엽니다. 변경된 문자열만 번역하므로, 수십 개의 로캘에 걸쳐도 실행은 빠르고 비용 효율적입니다.
워크플로 옵션#
GitHub App#
앱의 동작은 .lingo/config.json에서 설정합니다:
| 옵션 | 설명 |
|---|---|
기본 브랜치로 push (onPushToDefaultBranch) | 기본값으로 활성화되어 있습니다. 기본 브랜치에 소스 변경이 반영되면 번역 PR을 열거나 업데이트합니다. |
풀 리퀘스트 번역 (onPullRequest) | 기본값으로 비활성화되어 있습니다. PR에 변경이 생길 때 번역을 PR 브랜치에 커밋합니다. |
승인 게이트 (requireApproval) | 기본값으로 비활성화되어 있습니다. 자동 실행으로 번역이 시작되기 전에 check run에서 Approve/Deny를 받거나, PR에서 /lingo approve를 실행해야 합니다. |
수동 명령 (/lingo translate) | PR 코멘트에서 언제든 특정 파일의 누락분을 채우거나 번역을 강제로 실행할 수 있습니다. |
전체 구성과 명령어 참조는 GitHub App 가이드를 참고하세요.
CI/CD에서 CLI 사용하기 (GitHub Actions, GitLab CI, Bitbucket)#
대부분의 팀 환경은 네 가지 워크플로 패턴으로 커버할 수 있습니다:
| 워크플로 | 트리거 | 출력 |
|---|---|---|
| main에 커밋 | main로 push | 번역이 main에 직접 커밋됨 |
| main에서 PR 생성 | main로 push | 번역이 포함된 풀 리퀘스트 |
| feature 브랜치에 커밋 | feature 브랜치로 push | 번역이 해당 브랜치에 커밋됨 |
| feature 브랜치에서 PR 생성 | feature 브랜치로 push | 해당 브랜치에서 풀 리퀘스트 생성 |
첫 번째 옵션인 main에 커밋이 가장 단순합니다. 개발자의 개입 없이도 번역이 자동으로 반영됩니다. PR 기반 옵션은 번역이 반영되기 전에 검토 단계를 추가합니다.
어떤 방식을 선택할지에 대한 자세한 내용은 Advanced Patterns를 참고하세요.
