Bitbucket Pipelines 구성 예제
Bitbucket Pipelines에서 파일을 번역하고 결과를 다시 커밋하세요. 번역이 최신 상태가 아닌 풀 리퀘스트는 실패 처리할 수 있습니다.
Bitbucket 파이프라인으로 Lingo.dev 구성에서 선택한 소스 파일을 번역하세요. CLI는 작업을 제출하고 대상 파일을 다운로드하며, 파이프라인은 파일을 보관하고 전달할 방식을 결정합니다. 이 예제에서는 수동으로 실행하는 사용자 지정 파이프라인부터 구성합니다. 반복 작업을 예약하기 전에 번역 결과를 한 차례 확인할 수 있습니다.
연결은 기본 제공 Bitbucket 계정 커넥터가 아닌 실행기의 API 호출을 통해 이루어집니다. 저장소에 쓰거나 풀 리퀘스트를 생성하려면 별도의 Bitbucket 권한이 필요합니다.
정상 작동하는 카탈로그 하나 준비하기 #
로컬에서 CLI 빠른 시작을 따라 진행한 다음, .lingo/config.json, 확인한 대상 파일, .lingo/lock.json을 커밋하세요. 소스 및 대상 로캘, 로컬라이제이션 엔진, 파일 패턴은 이 구성에 지정합니다.
이 예제는 locales/en.json을 사용하며, locales/es.json에 있는 기존 스페인어 파일 하나만 대상으로 합니다. 대상이 여러 개라면 각 대상 파일마다 test -s 및 JSON 검사를 한 번씩 실행하고, locales/es.json을 지정하는 다른 명령에도 모든 대상 경로를 나열하세요. Lockfile에는 소스가 번역된 것으로 기록되므로 이후 푸시에서는 해당 소스를 건너뛰고, 아티팩트에서 빠진 대상은 갱신되지 않은 상태로 남습니다. 아래 명령으로 소스 변경을 반복 처리하기 전에 lingo push --backfill-missing --wait으로 누락된 대상 파일을 생성하세요. 일반 푸시는 이후의 소스 변경을 처리하지만, 누락된 파일을 채우는 작업으로는 기존 대상 파일에서 빠진 키를 복구할 수 없습니다.
LINGO_API_KEY을 보안 저장소 변수로 저장하세요. CLI는 이 이름의 변수만 읽습니다. 이전 CLI에서 사용하던 LINGODOTDEV_API_KEY 변수는 무시되므로 이름을 바꿔야 합니다. 신뢰할 수 있는 코드에서 파이프라인을 실행하고, 자격 증명을 다루는 구간에서는 셸 추적을 끄세요. 보안 변수로 설정했더라도 풀 리퀘스트의 임의 스크립트에 노출하면 안전하지 않습니다.
예제에서는 CLI 버전을 1.21.0으로 고정합니다. lingo check는 CLI 1.20.0부터 번역 파일 검사를 지원합니다. 프로젝트의 의존성과 Lockfile로 버전을 관리하려면 지속적 통합 설정 가이드를 따르세요.
번역하고 결과 보관하기 #
bitbucket-pipelines.yml에 다음 사용자 지정 파이프라인을 추가하세요.
image: node:22
pipelines:
custom:
translate-catalog:
- step:
name: Translate and inspect
script:
# 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 diff -- locales/es.json .lingo/lock.json
artifacts:
- locales/es.json
- .lingo/lock.json실행기가 npm에서 CLI를 다운로드할 수 있는지 확인하세요. 파일 경로는 구성에 맞게 조정하세요.
커밋된 .lingo/config.json에서 조직 및 엔진 식별자를 확인하세요. 영어 소스를 조금 수정해 커밋한 뒤, 신뢰할 수 있는 해당 브랜치에서 translate-catalog을 실행하세요. 실행 결과와 변경 내역을 확인한 다음 아티팩트를 다운로드하고, 변경된 스페인어 항목을 소스 리비전과 대조해 읽어 보세요. 애플리케이션에서 카탈로그를 불러와 변수와 렌더링도 확인하세요.
파일 존재 여부와 JSON 구문을 검사하면 결과물의 누락이나 잘못된 형식을 감지할 수 있습니다. 하지만 형식이 올바른 기존 파일과 새로 요청한 번역 결과를 구별할 수는 없습니다. 로컬라이제이션 엔진에서 사람이 하는 검토를 요구한다면, 검토를 마치고 완료된 결과물을 가져온 뒤 아티팩트를 수락하세요.
제출 및 가져오기 상태 보존하기 #
푸시는 기본적으로 비동기로 실행됩니다. push --wait은 실행이 끝날 때까지 기다린 뒤 번역된 파일을 checkout에 기록합니다. --wait가 없으면 lingo push은 실행을 요청한 뒤 바로 종료하므로, 다음 명령에서 보관하거나 커밋할 새 파일을 찾을 수 없습니다. 휴먼 리뷰를 기다리는 경우에는 나중에 결과를 가져오는 단계가 여전히 필요할 수 있습니다.
검토를 기다리거나 결과물 가져오기를 별도 단계로 나누기 전에 지속적 통합 실행 상태 보존 절차를 추가하세요. 제출 후에는 해당 실행의 포인터와 원래 프로젝트 루트의 절대 경로를 내보내세요. 이후 검증이 실패하더라도 내보내야 합니다. .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, 대상 파일, Lockfile을 접근이 제한된 아티팩트로 보관하고, 검토에 충분한 보관 기간을 설정하세요. 원래 단계의 실패가 가려지지 않도록 하고, ~/.lingo 전체나 자격 증명은 절대 보관하지 마세요.
결과물을 가져오려면 기록된 절대 루트 경로에 동일한 리비전과 보관된 파일 상태를 복원하세요. 해당 포인터만 복원하고 자격 증명은 별도로 제공하세요. 결과물을 수집하기 전에 --dry-run과 함께 풀을 사용하세요. 이후 파이프라인 단계에서 해당 경로를 재현할 수 없다면, 권한이 부여된 영구 실행기를 제출과 가져오기에 모두 사용하세요. 로컬 결과물의 충돌은 신중하게 해결하세요. 강제로 풀하면 검토자의 변경 사항이 사라질 수 있습니다.
결과물을 저장소에 전달할 방식 선택하기 #
전달 전에 사람이나 후속 릴리스 작업에서 결과물을 확인해야 한다면 아티팩트만으로 충분합니다. 완료된 동일 작업에서 나온 번역 파일과 Lockfile을 함께 보관하세요.
검토를 거쳐 저장소를 업데이트하려면 번역 브랜치에 푸시한 다음, Bitbucket에서 또는 문서에 안내된 API를 통해 풀 리퀘스트를 여세요. 다음 섹션에서 설명하듯 각 단계는 별도의 자격 증명 없이 기본 origin을 통해 자체 저장소에 푸시할 수 있습니다. 브랜치 권한 때문에 푸시가 차단되거나 API로 풀 리퀘스트를 생성해야 할 때만 저장소 SSH 키나 액세스 토큰을 추가하세요. API로 풀 리퀘스트를 생성하려면 풀 리퀘스트 쓰기 권한이 필요합니다. 팀의 봇 계정 정보를 설정하고, 확인된 대상 경로와 .lingo/lock.json만 스테이징한 뒤 스테이징된 변경 사항이 없으면 종료하세요. 동시에 실행되는 작업이 서로의 결과를 덮어쓰지 않도록 서로 다른 브랜치 이름을 사용하거나 브랜치 재사용 방식을 신중하게 정하세요.
직접 커밋하는 방식에서도 동일하게 결과물을 검사하고 스테이징 범위를 제한하되, 명시적으로 지정한 신뢰할 수 있는 브랜치에 푸시합니다. 기본 브랜치에 직접 전달하면 번역 풀 리퀘스트의 검토 단계가 생략되므로, 브랜치 정책에 따라 의도적으로 선택해야 합니다. 어느 방식이든 최종 애플리케이션 결과물을 검토하세요.
Lingo.dev API 키는 저장소 자격 증명과 분리해 관리하세요. 이 키는 번역 프로세스 환경에만 두어야 하며, 깃 원격 주소, 커밋된 파일, 결과물 아티팩트에는 절대 포함하면 안 됩니다. 관련 없는 실행기 파일까지 포함하지 않도록 git add . 대신 경로를 명시해 스테이징하세요.
브랜치에 번역 결과 다시 커밋하기 #
이 브랜치 파이프라인은 main에 반영되는 각 변경 사항을 번역하고 결과를 main에 커밋합니다. 초기 일괄 번역 결과가 커밋되어 있고 엔진의 휴먼 리뷰가 꺼져 있어 번역이 한 단계에서 완료되는 구성을 전제로 합니다. 사용자 지정 파이프라인과 동일한 pipelines 키 아래에 이 파이프라인의 branches 섹션을 추가하세요. 전체 파일은 다음과 같습니다.
image: node:22
pipelines:
custom:
translate-catalog:
- step:
name: Translate and inspect
script:
- 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 diff -- locales/es.json .lingo/lock.json
artifacts:
- locales/es.json
- .lingo/lock.json
branches:
main:
- step:
name: Translate and commit
auth:
system:
scopes:
- read:git:bitbucket
- write:git:bitbucket
script:
# 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:$BITBUCKET_BRANCH"대상 중 하나라도 실패하면 lingo push --wait은 0이 아닌 종료 코드를 반환하므로 커밋 전에 단계가 중단됩니다. 변경 사항이 없으면 "푸시할 내용 없음"을 출력하고, 스테이징된 변경 사항도 없으므로 커밋 없이 단계가 종료됩니다.
파이프라인은 각 단계에서 별도의 자격 증명 없이 자체 저장소로 다시 푸시할 수 있도록 origin 원격 저장소를 설정합니다. 단계의 auth 블록은 내장 토큰에 깃 푸시 권한을 부여합니다. 2027년 4월 30일부터 Bitbucket은 auth 블록이 없는 단계에 이 권한을 더 이상 부여하지 않습니다. 자체 호스팅 실행기에서 auth을 사용하려면 버전이 6.1.0 이상이어야 합니다. main의 브랜치 제한으로 푸시가 차단되면 해당 제한의 파이프라인 쓰기 권한 설정에서 main을 소스 브랜치로 추가하세요. 또는 Bitbucket의 저장소로 다시 푸시하기 가이드에 따라 쓰기 권한이 있는 SSH 키나 액세스 토큰을 단계에 제공하세요.
이 단계는 무한 반복되지 않습니다. 커밋 메시지의 [skip ci]은 Bitbucket이 번역 커밋으로 파이프라인을 시작하지 않도록 합니다. 이것이 없더라도 커밋된 .lingo/lock.json에 새 소스가 이미 기록되어 있으므로 다음 실행에서는 푸시할 내용이 없습니다. 번역 중에 브랜치가 변경되면 Git이 푸시를 거부하고, 더 최신 커밋의 파이프라인이 해당 커밋을 번역합니다.
트리거와 패키지 경로 조정하기 #
자격 증명에 접근할 수 있는 소스 코드와 쓰기를 허용할 브랜치를 먼저 결정한 뒤, 자동 브랜치 또는 풀 리퀘스트 트리거를 추가하세요. 포크에는 비밀 값이나 쓰기 가능한 대상이 없을 수 있습니다. 이를 해결하려고 신뢰할 수 없는 포크 코드를 높은 권한의 자격 증명으로 실행하지 마세요.
생성된 커밋이 번역을 끝없이 트리거하지 않도록 하세요. 관련 소스 경로와 신뢰할 수 있는 브랜치를 선택하고, 생성된 커밋에 적절한 규칙을 적용하세요. 변경 사항이 없으면 종료하는 동작도 유지하세요. 소스가 바뀌지 않았다면 변경 내역이 없는 것이 정상일 수 있습니다.
구성이 apps/web/.lingo/config.json에 있다면 apps/web에서 CLI를 실행하세요. 파이프라인 아티팩트 경로에는 여전히 Bitbucket의 저장소 기준 상대 경로 규칙이 적용되므로, apps/web/locales/es.json과 apps/web/.lingo/lock.json 같은 경로를 사용하세요. CLI 작업 디렉터리를 바꿔도 아티팩트 경로 규칙은 달라지지 않습니다.
번역이 최신 상태가 아닌 풀 리퀘스트 실패 처리하기 #
lingo check는 설정된 각 소스를 .lingo/lock.json과 비교하며, 모든 대상 파일이 있어야 검사를 통과합니다. 마지막 번역 이후 소스가 변경되었거나, 소스에 해당하는 Lockfile 항목이 없거나, 대상 파일이 누락되었거나, files 패턴과 일치하는 소스 파일이 없으면 종료 코드 1로 종료됩니다. API 키나 저장소 변수가 필요하지 않으며 아무것도 기록하지 않습니다. DO_NOT_TRACK=1으로 비활성화되는 CLI 원격 측정 외에는 네트워크 호출을 하지 않습니다. 다만 npx 예제에서는 검사를 실행하기 전에 여전히 npm에서 CLI를 다운로드합니다. 이 명령은 이전 CLI의 --frozen 통과 조건 검사를 대체합니다.
키가 아니라 파일을 검사합니다. 따라서 대상 파일을 직접 수정해도 검사를 통과하며, 리액트 .jsonc 카탈로그를 제외하면 기존 대상 파일 안에서 누락된 키는 보고하지 않습니다. .lingo/lock.json이 없으면 소스 변경을 감지할 수 없어, 소스가 변경되었거나 한 번도 푸시되지 않았더라도 검사가 실패하지 않습니다. 이 사실은 표준 오류로 안내합니다. lingo push이 기록하는 Lockfile을 커밋하세요.
이 검증 단계는 위의 브랜치 파이프라인을 사용하지 않는 구성을 위한 것입니다. 그 이유는 아래 표에서 확인할 수 있습니다. pipelines 아래에 pull-requests 섹션을 추가하세요. 수동 파이프라인을 유지한다면 custom 옆에 추가하세요. 이 검증 단계만 사용하는 경우 전체 파일은 다음과 같습니다.
image: node:22
pipelines:
pull-requests:
"**":
- step:
name: Check translations
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 check이 검증 단계는 번역 결과를 소스 변경과 함께 커밋하는 구성에 적합합니다.
| 번역 실행 위치 | 모든 풀 리퀘스트에 검증 적용 |
|---|---|
개발자가 풀 리퀘스트를 열기 전에 lingo push --wait을 실행하고 결과를 커밋 | 예. 소스가 변경되었지만 번역되지 않은 풀 리퀘스트를 실패 처리합니다. |
브랜치 파이프라인이 병합 후 main에 커밋 | 아니요. 이 방식에서는 기능 개발 풀 리퀘스트가 번역 전에 소스를 변경하도록 설계되어 있습니다. |
소스 해시는 바이트 하나의 차이도 구분합니다. lingo push을 실행한 checkout과 지속적 통합 환경의 checkout이 같은 줄바꿈 형식을 사용하도록 하세요. 예를 들어 .gitattributes에 * text=auto eol=lf을 설정할 수 있습니다. 애플리케이션의 리소스 검사도 유지하세요.
누락된 결과물 복구 또는 작업 중지하기 #
결과물이 누락되었다면 선택한 소스 파일, 기준 상태, 대상 포함 범위, 보안 변수 사용 가능 여부, 검토 상태, 보고된 실패를 확인하세요. 다시 제출하기로 결정하기 전에 기록된 실행을 복구하세요. 기존 프로젝트에서 누락된 대상을 보충하려면, 먼저 기존 대상의 일반 업데이트를 완료하고 결과물을 가져와 확인하세요. 그런 다음 보충 작업이 끝날 때까지 소스 리비전을 고정하세요. 이 순서는 언어 추가를 따르세요. 선택된 승인 텍스트를 교체하려는 경우에만 강제 재생성을 사용하세요. 강제로 교체하지 않고 재시도를 요청하는 방법은 실패한 실행 복구에서 확인할 수 있습니다.
새 작업이 시작되지 않도록 하려면 파이프라인 트리거를 비활성화하세요. 실행기를 취소할 때는 이미 제출된 서버 실행을 별도로 확인하세요. 이 구성을 더 이상 사용하지 않을 때는 사용하지 않는 API 변수와 제공업체 쓰기 권한을 제거하세요.