Buildkite 구성 예제
Buildkite 파이프라인에서 파일을 번역하고 결과를 브랜치에 다시 푸시하며, 번역이 최신 상태가 아닌 풀 리퀘스트를 실패 처리합니다.
Buildkite 단계에서 자체 에이전트의 Lingo.dev CLI로 저장소 파일을 번역할 수 있습니다. CLI는 Lingo.dev 설정에 따라 선택된 소스 파일을 제출하고 번역된 파일을 checkout에 기록합니다. 결과를 전달하는 방식은 파이프라인에서 결정합니다. Buildkite는 에이전트, 비밀 정보, 저장소 접근을 관리하고, Lingo.dev는 로컬라이제이션 엔진으로 파일을 처리합니다.
이 문서는 Buildkite 기본 제공 연결이 아닌 CI 구성 예제입니다. 먼저 기본 브랜치나 풀 리퀘스트 빌드에 번역 단계 하나를 추가하고, 이 단계가 생성하는 첫 커밋을 확인하세요. 풀 리퀘스트 검사는 아래 표에서 해당 검사 조건이 적합하다고 안내하는 구성에만 추가하세요.
저장소와 에이전트 준비 #
로컬에서 CLI 빠른 시작을 완료하세요. .lingo/config.json, 승인된 대상 파일, .lingo/lock.json을 커밋하세요. 설정에서 소스 로캘, 대상 로캘, 파일 패턴, 로컬라이제이션 엔진을 선택합니다. 예제에서는 locales/en.json를 소스로, locales/es.json에 있는 기존 스페인어 파일을 대상으로 사용합니다. 대상이 더 있다면 각 대상 파일에 대해 test -s 및 JSON 검사를 한 번씩 실행하세요. locales/es.json을 지정하는 다른 명령에도 모든 대상 경로를 나열하거나, locales/처럼 대상 디렉터리 전체를 스테이징하세요. Lockfile에는 소스가 번역된 것으로 기록되므로 이후 푸시에서는 해당 소스를 건너뜁니다. 커밋에서 빠진 대상 파일은 최신 상태가 아닌 채로 남습니다.
반복 실행 단계를 도입하기 전에 lingo push --backfill-missing --wait로 누락된 대상 파일을 생성하세요. 이후 소스를 수정할 때는 일반적인 lingo push --wait를 사용하세요. 누락된 파일을 보충해도 기존 대상 파일 안에서 빠진 키는 복구되지 않습니다.
에이전트에는 Node.js, npm, Git이 필요하며, npm 레지스트리와 Lingo.dev에 네트워크로 접근할 수 있어야 합니다. 배포 키 등 에이전트가 checkout에 사용하는 저장소 자격 증명으로는 이 단계가 결과를 기록하는 브랜치에 푸시할 수도 있어야 합니다.
Lingo.dev API 키를 LINGO_API_KEY라는 이름의 Buildkite 비밀 정보로 저장하세요. CLI는 이 이름만 읽습니다. 이전 CLI에서 사용하던 LINGODOTDEV_API_KEY 변수는 무시되므로 이름을 바꾸세요. 비밀 정보는 번역 단계에서만 불러오세요. 단계의 secrets: 키를 사용하려면 비밀 정보가 저장된 클러스터에서 Buildkite 에이전트 3.106.0 이상을 실행해야 합니다. 이전 버전의 에이전트에서는 파이프라인이 실패합니다. 이전 버전이거나 클러스터에 속하지 않은 에이전트를 사용한다면 secrets:를 제거하세요. 대신 에이전트의 environment 훅이나 비밀 정보 플러그인에서 해당 단계에 사용할 LINGO_API_KEY를 환경 변수로 내보내세요.
파이프라인의 GitHub 설정에서 타사 포크 저장소의 빌드 허용을 꺼 두세요. 포크의 풀 리퀘스트는 포크 자체의 pipeline.yml로 빌드되므로, 여기에 비밀 정보를 읽는 단계가 추가될 수 있습니다. 사용자의 파일에 있는 if:로는 이를 막을 수 없습니다. 이 파이프라인의 빌드만 비밀 정보를 읽을 수 있도록 비밀 정보에도 접근 정책을 추가하세요.
예제에서는 CLI 버전을 1.21.0으로 고정합니다. lingo check는 CLI 1.20.0부터 번역 파일 검사를 지원합니다. 프로젝트 의존성과 Lockfile로 버전을 관리하려면 CI 설정 가이드를 따르세요.
번역 후 브랜치에 다시 푸시 #
이 단계는 기본 브랜치에 반영되는 각 변경 사항을 번역하고 결과를 같은 브랜치에 푸시합니다. 초기 보충 작업 결과가 커밋되어 있고 엔진의 휴먼 리뷰가 꺼져 있어 번역이 한 단계에서 완료된다는 전제입니다. .buildkite/pipeline.yml에 추가하세요.
steps:
- label: "Translate"
if: build.branch == pipeline.default_branch && build.pull_request.id == null
concurrency: 1
concurrency_group: "lingo-translations"
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# Replace 1.21.0 with the current CLI version.
npx -y @lingo.dev/cli@1.21.0 push --wait
test -s locales/es.json
node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
git add -- locales/es.json .lingo/lock.json
if git diff --cached --quiet; then exit 0; fi
git config user.name "Localization bot"
git config user.email "localization@example.com"
git commit -m "[skip ci] Update translations"
git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"--wait를 사용하면 단계가 실행 완료를 기다린 뒤 번역된 파일을 checkout에 기록합니다. 이 옵션이 없으면 lingo push는 실행을 제출한 뒤 바로 종료하므로 단계에서 커밋할 파일을 찾지 못합니다. lingo push --wait는 대상 작업이 실패하면 0이 아닌 종료 코드를 반환하므로 커밋 전에 단계가 중단됩니다. 변경 사항이 없으면 "푸시할 내용 없음"을 출력하며, 스테이징된 변경 사항도 없어 커밋 없이 종료됩니다.
Buildkite는 브랜치가 아닌 단일 커밋을 checkout하므로 푸시할 때 브랜치를 지정합니다. $$는 단계 실행 시 셸이 확장할 수 있도록 BUILDKITE_BRANCH를 그대로 남겨 둡니다. $를 하나만 사용하면 Buildkite가 파이프라인을 업로드할 때 명령문에 브랜치 이름을 넣습니다. concurrency와 concurrency_group는 번역을 한 번에 하나씩 실행하도록 합니다. 번역 중 브랜치가 이동하면 Git이 푸시를 거부하며, 더 최신 커밋의 빌드가 해당 커밋을 번역합니다.
이 단계는 무한 반복되지 않습니다. Buildkite는 커밋 메시지에 [skip ci]가 포함된 경우 빌드를 건너뜁니다. 이 항목이 없더라도 커밋된 .lingo/lock.json에 이미 새 소스가 기록되어 있으므로 다음 빌드에서는 푸시할 내용이 없습니다.
기본 브랜치에 바로 푸시하면 번역 풀 리퀘스트를 검토하는 과정이 생략됩니다. 따라서 브랜치 정책을 정할 때 이 점을 신중하게 고려하세요. 번역을 먼저 검토하려면 lingo/translations 같은 별도 브랜치에 푸시하고 Git 제공업체의 도구로 풀 리퀘스트를 여세요.
풀 리퀘스트 빌드에서 번역 #
각 풀 리퀘스트의 소스 변경 사항을 해당 브랜치에서 번역하려면 기본 브랜치용 단계 대신 이 단계를 사용하세요. 전제 조건은 기본 브랜치용 단계와 같습니다. 포크의 브랜치에는 푸시할 수 없으므로 이 단계의 if:는 포크에서 생성된 풀 리퀘스트를 건너뜁니다.
이 단계를 사용하려면 파이프라인의 GitHub 설정에서 두 가지를 설정해야 합니다. 풀 리퀘스트를 열거나 업데이트할 때 빌드를 켜세요. 브랜치 빌드는 끄거나 기본 브랜치로 제한하세요. 브랜치 빌드가 켜져 있으면 풀 리퀘스트 브랜치에 푸시할 때 풀 리퀘스트 세부 정보 없이 빌드가 시작될 수 있습니다. 이 단계는 해당 빌드를 건너뛰므로 번역도 수행되지 않고 실패도 발생하지 않습니다.
if:는 LINGO_API_KEY를 보호하지 않습니다. Buildkite는 풀 리퀘스트 자체의 pipeline.yml에서 이를 읽으며, 포크에서 해당 파일을 변경할 수 있습니다. 따라서 설정 안내에 설명된 대로 포크 빌드는 꺼 두어야 합니다. 저장소 내부 브랜치의 풀 리퀘스트도 이 파일을 변경할 수 있으므로 브랜치를 푸시할 수 있는 사람은 누구나 이 단계를 통해 키를 읽을 수 있습니다. 푸시 권한이 있는 모든 사람이 키를 보유해도 되는 환경에서만 이 단계를 사용하세요.
steps:
- label: "Translate pull request"
if: build.pull_request.id != null && build.pull_request.repository.fork != true
# secrets: needs Buildkite agent 3.106.0 or later.
secrets:
- LINGO_API_KEY
command: |
# Replace 1.21.0 with the current CLI version.
npx -y @lingo.dev/cli@1.21.0 push --wait
test -s locales/es.json
node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
git add -- locales/es.json .lingo/lock.json
if git diff --cached --quiet; then exit 0; fi
git config user.name "Localization bot"
git config user.email "localization@example.com"
git commit -m "Update translations"
git push origin "HEAD:refs/heads/$${BUILDKITE_BRANCH}"커밋 메시지에는 의도적으로 [skip ci]를 넣지 않습니다. Buildkite가 번역 커밋을 빌드하면 이 단계가 다시 실행되고, 푸시할 내용이 없어 커밋 없이 종료됩니다. 따라서 한 번의 추가 빌드 후 반복이 끝납니다. 이 빌드는 풀 리퀘스트의 최신 커밋에 상태를 부여합니다. [skip ci]를 넣으면 최신 커밋에 대한 Buildkite 빌드가 실행되지 않아 필수 Buildkite 상태 검사가 병합을 차단하게 됩니다.
에이전트의 checkout 자격 증명으로 풀 리퀘스트 브랜치에 푸시할 수 있어야 합니다. 번역 중 브랜치가 이동하면 Git이 푸시를 거부하고 단계가 실패합니다. 더 최신 커밋의 빌드가 해당 커밋을 번역하므로, 짧은 간격으로 두 번 푸시하면 번역도 두 번 시작되고 둘 다 요금이 청구됩니다. 파이프라인 설정에서 중간 빌드 취소를 켜서 새 푸시가 이전 빌드를 취소하도록 하세요. 이전 빌드에서 이미 제출한 번역은 취소되지 않습니다.
번역이 최신 상태가 아닌 풀 리퀘스트 실패 처리 #
lingo check는 설정된 각 소스를 .lingo/lock.json와 비교하고 모든 대상 파일이 있는지 확인합니다. 마지막 번역 이후 소스가 변경되었거나, 소스에 해당하는 Lockfile 항목이 없거나, 대상 파일이 누락되었거나, files 패턴과 일치하는 소스 파일이 없으면 종료 코드 1을 반환합니다. API 키나 비밀 정보가 필요하지 않으며 아무것도 기록하지 않습니다. DO_NOT_TRACK=1로 비활성화하는 CLI 원격 분석을 제외하면 네트워크 호출도 하지 않습니다. 다만 npx 예제는 검사 전에 npm에서 CLI를 다운로드합니다. 이 검사는 이전 CLI의 --frozen 검사 조건을 대체합니다.
검사 대상은 키가 아니라 파일입니다. 수동으로 편집한 대상 파일도 통과하며, React .jsonc 카탈로그를 제외하면 기존 대상 파일 안에서 누락된 키는 보고하지 않습니다. .lingo/lock.json가 없으면 소스 변경을 감지할 수 없으므로 소스가 변경되었거나 한 번도 푸시되지 않았어도 검사가 실패하지 않으며, 이 사실을 표준 오류로 알립니다. lingo push가 기록하는 Lockfile을 커밋하세요.
아래 표에서 검사 조건이 적합하다고 안내하는 구성이라면 .buildkite/pipeline.yml에 이 단계를 추가하세요. 이 단계는 위의 두 번역 단계를 모두 사용하지 않는 구성에 해당합니다. 따라서 여기에 있는 각 예제는 한 가지 구성에 필요한 전체 steps: 목록입니다. 두 번째 steps: 키를 추가하지 말고 기존 steps: 목록에 해당 단계를 합치세요.
steps:
- label: "Check translations"
if: build.pull_request.id != null
command:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 check이 검사 조건은 번역을 소스 변경 사항과 함께 커밋하는 구성에 적합합니다.
| 번역 실행 위치 | 모든 풀 리퀘스트에 검사 조건 적용 |
|---|---|
개발자가 풀 리퀘스트를 열기 전에 lingo push --wait를 실행하고 결과를 커밋 | 적합합니다. 번역 없이 소스가 변경된 풀 리퀘스트를 실패 처리합니다. |
| 번역 단계가 병합 후 기본 브랜치에 푸시 | 적합하지 않습니다. 이 구성에서는 기능 개발용 풀 리퀘스트가 번역에 앞서 소스를 변경하도록 설계되어 있습니다. |
| 풀 리퀘스트 단계가 풀 리퀘스트 브랜치에 커밋 | 적합하지 않습니다. 번역을 수행하는 빌드에서는 검사가 번역 전 커밋을 확인하므로 실패합니다. 번역 커밋에서 이 단계가 다시 실행되어 푸시할 내용을 찾지 못하면 .lingo/lock.json 이후 소스가 변경되지 않았음을 알 수 있습니다. |
소스 해시는 바이트 단위로 정확히 일치해야 합니다. lingo push를 실행한 checkout과 CI의 checkout에서 같은 줄바꿈 형식을 사용하세요. 예를 들어 .gitattributes에 * text=auto eol=lf를 지정할 수 있습니다.
단계 조정 #
모노레포에서는 .lingo/config.json가 있는 패키지에서 CLI를 실행하고 해당 패키지의 대상 파일과 Lockfile을 스테이징하세요. 예를 들어 명령 시작 부분에 cd apps/web를 사용할 수 있습니다. 독립된 패키지는 각각 별도의 Lockfile을 유지하며 서로 다른 로컬라이제이션 엔진을 사용할 수 있습니다.
로컬라이제이션 엔진이 작업을 사람이 하는 검토로 보내면 lingo push --wait는 완료된 파일만 기록한 뒤 종료 코드 0을 반환합니다. 일부만 완료된 결과를 전체 완료 결과로 간주해 커밋하지 마세요. CI 실행 상태 보존 절차를 추가하고, 검토가 끝나면 같은 에이전트에서 가져오기로 나머지 파일을 가져오세요.
단계 복구 및 사용 종료 #
오류를 확인해 다음 조치를 결정하세요. 패키지 설치를 복구하거나, 비밀 정보를 제공하거나, 검토를 완료하거나, 가져오기 충돌을 해결하거나, 원인을 수정한 뒤 실패한 대상 작업을 다시 시도하세요. 0이 아닌 종료 코드가 드러나도록 유지하세요. || true를 사용하면 원인이 가려집니다.
새 빌드가 시작되지 않도록 하려면 단계나 트리거를 제거하세요. 빌드를 취소할 때는 이미 제출된 번역을 별도로 확인하세요. 이 구성을 더 이상 사용하지 않을 때는 LINGO_API_KEY 비밀 정보와 에이전트의 쓰기 권한을 제거하세요.