GitHub, GitLab 또는 Bitbucket에서 지속적 로컬라이제이션을 설정하세요. 지원되는 방식은 두 가지입니다. 관리형 Lingo.dev GitHub App과 자체 파이프라인에서 @lingo.dev/cli를 실행하는 방식입니다. 사용하는 플랫폼과 원하는 제어 수준에 맞는 옵션을 선택하세요.
어떤 방식을 선택해야 할까요?#
| 방식 | 추천 대상 | 필요한 것 |
|---|---|---|
| GitHub App | GitHub에 호스팅된 리포지토리 | 앱을 설치하고, .lingo/config.json가 포함된 engineId를 커밋하세요. runner, secret, CLI는 필요 없습니다. |
runner에서 @lingo.dev/cli 실행 | GitLab, Bitbucket 또는 완전한 제어가 필요한 GitHub Actions | Node 22+, @lingo.dev/cli, LINGO_API_KEY secret, 그리고 lingo push를 실행하는 job이 필요합니다. |
GitHub를 쓰고 계신가요? GitHub App부터 시작하세요
GitHub App은 서버 사이드에서 실행됩니다. 커밋된 .lingo/config.json(engineId 포함)를 읽고, push와 pull request에 반응하며, runner, API key secret, lock file이 필요 없습니다. GitHub App 가이드만 따르면 설정은 끝입니다. 이 페이지의 나머지 내용은 자체 파이프라인에서 CLI를 실행하는 방법을 다룹니다.
파이프라인에서 CLI 실행하기#
GitLab이나 Bitbucket을 사용 중이거나, GitHub에서 로컬라이제이션을 직접 제어하고 싶다면 파이프라인의 job으로 @lingo.dev/cli를 실행하세요. 설정은 모든 플랫폼에서 동일한 세 단계로 진행됩니다. CLI를 구성하고, API key를 추가하고, 워크플로를 선택하면 됩니다.
사전 준비 사항
CI에 추가하기 전에, .lingo/config.json 파일이 있고 로컬에서 lingo push를 실행할 수 있는 정상 동작하는 CLI setup이 필요합니다.
1단계. CLI 구성#
아직 설정하지 않았다면 CLI Quickstart를 따라 진행하세요. 완료되면 다음이 준비되어 있어야 합니다:
- 프로젝트 루트의
.lingo/config.json파일(Configuration 참고) - Lingo.dev 엔진용
LINGO_API_KEY lingo push로 로컬에서 번역을 생성할 수 있는 상태
CLI는 Node 22+에서 실행됩니다. 파이프라인에서는 다음 명령으로 설치하세요:
npm install -g @lingo.dev/cli2단계. API 키를 CI 시크릿으로 추가#
lingo push는 LINGO_API_KEY 환경 변수로 인증합니다. CI 플랫폼의 secret 관리 기능에 저장하세요:
- Settings > Secrets and variables > Actions로 이동합니다
- New repository secret를 클릭합니다
- 이름:
LINGO_API_KEY, 값: API 키 - Add secret를 클릭합니다
3단계. 워크플로를 선택하고 설정을 추가#
이 job은 lingo push를 실행해 번역을 생성한 뒤, 결과를 커밋하거나 플랫폼 자체 도구로 pull request를 엽니다. 팀에 맞는 워크플로를 선택하세요:
| 워크플로 | 추천 대상 |
|---|---|
| main에 커밋 | 번역 업데이트가 별다른 개입 없이 자연스럽게 반영되길 원하는 소규모 팀 |
| main에서 PR 생성 | 번역이 main에 반영되기 전에 검토하고 싶은 팀 |
| feature branch에 커밋 | 장기간 유지되는 feature branch를 운영하는 팀 |
| feature branch에서 PR 생성 | 모든 번역 변경을 최대한 세밀하게 관리하고 싶은 팀 |
어떤 워크플로를 선택할지 고민된다면 "main에 커밋"부터 시작하세요. 가장 간단한 방식이며, 나중에도 .lingo/config.json을 바꾸지 않고 전환할 수 있습니다.
플랫폼별 설정 방법과 워크플로 예시는 다음 문서를 참고하세요.
설정 확인#
CI job 구성을 마친 뒤 변경 사항을 push해 트리거하세요. 파이프라인은 다음 작업을 수행해야 합니다:
- 새 콘텐츠와 변경된 콘텐츠를 번역하기 위해
lingo push실행 - 번역을 커밋하거나 PR 열기(선택한 워크플로에 따라 다름)
- 이미 번역된 내용을 추적하는
.lingo/lock.json파일 업데이트
새 번역을 생성하지 않고 CI에서 번역이 모두 완료됐는지 확인하려면 lingo check를 실행하세요:
lingo check번역되지 않은 콘텐츠가 하나라도 있으면 0이 아닌 상태 코드로 종료합니다. 배포 게이트로 활용하기에 유용합니다. 예시는 고급 패턴을 참고하세요.
