GitLab 지속적 통합 구성 예시

신뢰할 수 있는 GitLab 파이프라인에서 파일을 번역하고 병합 요청으로 전달하세요. 번역이 최신 상태가 아닌 병합 요청은 실패 처리할 수 있습니다.

GitLab 러너에서 Lingo.dev CLI로 저장소 파일을 번역하고 결과를 작업 아티팩트로 보관할 수 있습니다. 이렇게 하면 번역에도 애플리케이션의 나머지 부분과 동일한 checkout, 검사, 릴리스 절차를 적용할 수 있습니다. GitLab은 파이프라인 실행과 저장소를 통한 전달을 담당하고, Lingo.dev는 선택한 원본 파일을 로컬라이제이션 엔진으로 처리합니다.

이 문서는 지속적 통합 구성 예시로, GitLab 계정을 직접 연결하는 방식은 아닙니다. 먼저 기본 브랜치에서 파이프라인을 수동으로 실행하세요. 결과를 확인한 뒤 정기 실행 트리거와 병합 요청을 통한 전달을 추가하세요.

원본과 자격 증명 준비 #

로컬에서 CLI 빠른 시작을 완료하세요. .lingo/config.json, 승인된 대상 파일, .lingo/lock.json을 커밋하세요. 구성에서는 원본 로캘, 대상 로캘, 파일 패턴, 로컬라이제이션 엔진을 선택합니다. 해당 구성이 있는 디렉터리에서 CLI를 실행하세요.

lingo push --backfill-missing --wait으로 누락된 대상 파일을 생성하세요. 이후 원본을 수정할 때는 일반적인 lingo push --wait을 사용하세요. 로컬라이제이션 엔진의 지침만 변경한다고 승인된 파일이 다시 작성되지는 않습니다. 의도적으로 다시 생성하려면 별도의 작업이 필요합니다.

프로젝트의 CI/CD 변수 설정에서 LINGO_API_KEY을 마스킹된 변수로 저장하세요. CLI는 이 이름만 읽고 이전 CLI에서 사용하던 LINGODOTDEV_API_KEY 변수는 무시하므로, 변수 이름을 바꿔야 합니다. 번역 작업을 제출하도록 허용된 신뢰할 수 있는 브랜치나 환경에서만 이 변수를 사용할 수 있도록 제한하세요. 보호된 변수는 보호되지 않은 브랜치나 병합 요청에서 사용하지 못할 수 있습니다. 신뢰할 수 없는 코드에 변수를 노출하는 대신, 사용 권한이 있는 브랜치를 이용하세요.

API 키는 번역 권한을 부여합니다. 저장소 쓰기 권한이 있는 GitLab 자격 증명은 커밋을 통한 전달을 추가할 때만 필요합니다.

예제에서는 CLI 버전을 1.21.0으로 고정합니다. lingo check 명령은 CLI 1.20.0부터 번역 파일 검사를 지원합니다. 프로젝트의 의존성과 Lockfile로 버전을 관리하려면 CI 설정 가이드를 따르세요.

아티팩트 우선 파이프라인 실행 #

이 .gitlab-ci.yml 예제는 locales/en.json이 원본으로 설정되어 있고, 기존 스페인어 파일인 locales/es.json이 유일한 대상이라고 가정합니다. 대상이 여러 개라면 대상 파일마다 test -s 및 JSON 검사를 한 번씩 실행하고, locales/es.json을 명시하는 다른 명령에도 모든 대상 경로를 나열하세요. Lockfile은 원본이 번역되었다고 기록하므로 이후 푸시에서는 해당 원본을 건너뜁니다. 따라서 아티팩트나 커밋에서 누락된 대상은 최신 상태로 반영되지 않은 채 남습니다. 이 예제는 기본 브랜치에서 수동으로 시작하는 파이프라인을 사용합니다.

yaml
stages:
  - translate

translate_catalog:
  stage: translate
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  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:
    paths:
      - locales/es.json
      - .lingo/lock.json

--wait은 작업이 실행 완료를 기다리고 번역된 파일을 checkout에 쓰도록 합니다. 이 옵션이 없으면 lingo push은 실행을 제출한 뒤 바로 종료하므로, 이후 단계에서 검사하거나 커밋할 새 파일이 없습니다.

러너에서 레지스트리에 접근할 수 있는지 확인하고, 이후 단계에 필요한 도구를 준비하세요. 예를 들어 다른 최소 구성 이미지를 사용한다면 변경 사항을 확인하거나 커밋하기 전에 깃을 설치해야 할 수 있습니다.

커밋된 .lingo/config.json에서 조직 및 엔진 식별자를 확인하세요. 원본을 한 번 수정한 뒤 파이프라인을 실행하세요. 로그에 보고된 실행 상태와 변경된 대상 항목을 확인하세요. 아티팩트를 다운로드해 번역을 해당 원본 리비전과 비교하고, 애플리케이션에서 불러오세요. 파일 존재 여부와 JSON 검사만으로는 최신 상태나 의미의 정확성을 확인할 수 없습니다.

--wait은 완료된 결과를 다운로드하지만, 사람이 하는 검토가 설정되어 있으면 작업이 검토 대기 상태로 남을 수 있습니다. 검토 대기 기능이나 별도의 결과 가져오기 작업을 사용하기 전에 지속적 통합 실행 상태 보존 절차를 추가하세요. 제출 후에는 해당 포인터와 원래 프로젝트 루트의 절대 경로를 내보내세요. 접근이 제한된 작업 아티팩트에 .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, 대상 파일, Lockfile을 포함하세요. artifacts 구성에서 when: always을 설정하고 검토에 충분한 보존 기간을 지정하세요. 이후 검증이 실패해도 내보내기가 실행되도록 하되, 원래 발생한 실패를 숨기지 마세요.

검토를 완료한 뒤, 결과를 가져오는 러너에서 원래와 동일한 절대 경로의 루트에 기록된 리비전과 파일 상태를 복원하세요. 해당 포인터만 복원하고 인증은 별도로 수행하세요. 결과를 수집하기 전에 lingo pull --dry-run을 사용하세요. 러너에서 원래 경로를 재현할 수 없다면 두 작업 모두에 권한이 있는 영구 러너를 사용하세요. ~/.lingo 전체를 아카이브하지 마세요. 제출에 성공했거나 이전 대상 파일이 있다는 사실만으로 게시할 새 파일이 확보되는 것은 아닙니다.

번역을 병합 요청에 커밋 #

이 작업은 병합 요청의 원본 변경 사항을 번역하고 결과를 같은 브랜치에 커밋합니다. 초기 누락분을 채운 결과가 커밋되어 있고 엔진에서 사람이 하는 검토가 꺼져 있어, 하나의 작업으로 번역을 완료할 수 있다고 가정합니다.

GitLab 18.4 이상에서는 설정 → 지속적 통합 및 배포 → 작업 토큰 권한 → 저장소에 대한 깃 푸시 요청 허용을 활성화하세요. 이 작업은 GitLab의 기본 제공 토큰을 사용하며, 작업을 시작하는 사람에게는 원본 브랜치에 푸시할 권한이 있어야 합니다. GitLab 작업 토큰 설정을 참조하세요.

LINGO_API_KEY은 마스킹 및 보호 상태로 유지하세요. 같은 프로젝트 안에서 신뢰할 수 있는 원본 브랜치와 대상 브랜치를 사용하고 두 브랜치를 모두 보호하세요. 그런 다음 프로젝트의 지속적 통합 및 배포 설정에서 병합 요청 파이프라인이 보호된 변수 및 러너에 접근하도록 허용을 활성화하세요. 파이프라인을 시작하는 사람에게는 대상 브랜치에 푸시하거나 병합할 권한도 필요합니다. 이는 보호된 변수에 대한 GitLab 요구 사항입니다.

첫 번째 예시와 동일한 원본 및 대상 경로를 사용하세요. 다음 작업을 translate 단계에 추가하세요:

yaml
translate_merge_request:
  stage: translate
  image: node:22
  resource_group: lingo-mr-$CI_MERGE_REQUEST_IID
  rules:
    - if: >-
        $CI_PIPELINE_SOURCE == "merge_request_event" &&
        $CI_MERGE_REQUEST_EVENT_TYPE == "detached" &&
        $CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_MERGE_REQUEST_TARGET_PROJECT_ID
  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 "Update translations"
    - git push "$CI_REPOSITORY_URL" "HEAD:refs/heads/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"

resource_group은 병합 요청마다 번역 작업을 한 번에 하나씩 실행합니다. 이 작업은 스페인어 대상 파일과 번역 Lockfile만 커밋합니다. 번역 중에 브랜치가 변경되면 깃이 푸시를 거부하므로, 업데이트된 브랜치에서 파이프라인을 실행하세요.

CI_REPOSITORY_URL은 작업 토큰 자격 증명을 제공합니다. 이 토큰으로 푸시해도 다른 파이프라인이 시작되지 않으므로, 커밋 단계 전에 애플리케이션의 리소스 검사를 추가하세요. 병합 요청에서 번역 변경 사항을 검토하고, 병합하기 전에 나머지 검사를 실행하세요.

이 푸시는 파이프라인을 시작하지 않으므로 병합 요청의 최신 커밋에는 파이프라인이 없습니다. 프로젝트에서 파이프라인 성공 필수를 요구하면 GitLab이 병합을 차단할 수 있습니다. 이때는 병합 요청의 파이프라인 탭에서 파이프라인 실행을 선택하세요. 작업은 푸시할 항목이 없어 커밋 없이 종료되며, 해당 파이프라인이 최신 커밋에 상태를 부여합니다.

기본 브랜치에서 번역 병합 요청 열기 #

이 작업은 기본 브랜치에 반영되는 각 변경 사항을 번역하고 그 결과로 병합 요청을 엽니다. GitLab 푸시 옵션으로 동일한 git push에서 병합 요청을 생성하므로 API 호출이나 추가 도구가 필요하지 않습니다. 위 작업과 마찬가지로 초기 일괄 번역이 커밋되어 있고 휴먼 리뷰가 꺼져 있다고 가정합니다.

개발자 역할과 write_repository 범위가 부여된 프로젝트 액세스 토큰을 생성하세요. 이 토큰을 GITLAB_PUSH_TOKEN이라는 이름의 마스킹된 보호 CI/CD 변수로 저장하세요. GitLab.com에서 프로젝트 액세스 토큰을 사용하려면 유료 요금제가 필요합니다. CI_JOB_TOKEN은 여기서 사용하지 않습니다. 이를 사용해 푸시하면 GitLab이 파이프라인을 시작하지 않기 때문입니다. 푸시 URL에는 CI_SERVER_FQDN을 사용하므로 자체 관리형 인스턴스에서 비표준 포트를 사용하더라도 해당 포트가 유지됩니다. CI_SERVER_FQDN을 사용하려면 GitLab 16.10 이상이 필요합니다. 이전 버전의 자체 관리형 인스턴스에서는 대신 ${CI_SERVER_HOST}:${CI_SERVER_PORT}을 사용하세요.

translate 단계에 이 작업을 추가하세요.

yaml
translate_default_branch:
  stage: translate
  image: node:22
  resource_group: lingo-translations
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - git fetch --quiet "$CI_REPOSITORY_URL" "$CI_DEFAULT_BRANCH"
    - if [ "$(git rev-parse FETCH_HEAD)" != "$CI_COMMIT_SHA" ]; then exit 0; fi
    # 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 --force
      -o ci.skip
      -o merge_request.create
      -o merge_request.target="$CI_DEFAULT_BRANCH"
      -o merge_request.title="Update translations"
      "https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_FQDN}/${CI_PROJECT_PATH}.git"
      "HEAD:refs/heads/lingo/translations"

lingo push --wait은 대상 검사에 실패하면 0이 아닌 상태 코드로 종료하므로, 커밋 전에 작업이 중단됩니다. 변경 사항이 없으면 "푸시할 항목 없음"을 출력하며, 스테이징된 변경 내역이 비어 있어 커밋 없이 작업을 종료합니다.

처음 두 줄은 기본 브랜치가 작업 실행 기준이 된 커밋보다 앞서 나갔을 때 작업을 중단합니다. resource_group은 한 번에 하나의 작업만 실행하지만, GitLab의 기본 unordered 처리 모드에서는 대기 중인 작업을 일정한 순서 없이 시작합니다. 이 검사가 없으면 오래된 작업이 마지막에 실행되어 강제 푸시로 최신 번역을 이전 번역으로 덮어쓸 수 있습니다. 최신 커밋의 작업은 해당 커밋을 번역하고, 이미 오래된 커밋에 대해서는 아무것도 제출하지 않습니다.

이 작업은 무한 반복되지 않습니다. 기본 브랜치에 푸시할 때만 실행되고 lingo/translations에만 기록합니다. GitLab 문서에 따르면 -o ci.skip은 병합 요청 파이프라인이 아닌 브랜치 파이프라인에만 영향을 줍니다. 또한 병합 요청 파이프라인은 병합 요청을 생성하거나 원본 브랜치에 새 커밋을 추가할 때 실행됩니다. 따라서 아래 통과 검사는 번역 병합 요청에서 실행되어야 합니다. 첫 실행 시 이를 확인하세요. 해당 병합 요청을 병합하면 작업이 한 번 더 시작되지만, 푸시할 항목은 없습니다.

실행할 때마다 기준이 된 기본 브랜치 커밋에서 lingo/translations을 다시 구성하고 강제 푸시하므로, 열려 있는 병합 요청에는 최신 번역 변경 내역이 표시됩니다. 해당 브랜치에서 직접 수정한 내용은 다음 실행에서 덮어쓰이므로, 수동 수정은 병합 후에 하세요. 병합 요청이 병합되기 전까지 기본 브랜치는 이전 .lingo/lock.json을 유지하므로, 다음 실행에서도 동일한 원본 변경 사항을 다시 제출합니다. 이후 커밋에서 병합 요청이 번역한 원본 변경 사항을 모두 되돌리면, 다음 실행에서는 푸시할 항목이 없어 오래된 번역이 담긴 병합 요청이 열린 상태로 남습니다. 이 경우에는 병합하지 말고 닫으세요.

번역이 최신 상태가 아닌 병합 요청 실패 처리하기 #

lingo check 명령은 설정된 각 원본을 .lingo/lock.json과 비교하고 모든 대상 파일이 있는지 확인합니다. 마지막 번역 이후 원본이 변경되었거나, 원본의 Lockfile 항목이 없거나, 대상 파일이 없거나, files 패턴과 일치하는 원본 파일이 없으면 상태 코드 1로 종료합니다. API 키나 CI/CD 변수가 필요하지 않고 아무것도 기록하지 않으므로, 포크에서 보낸 병합 요청에서도 실행할 수 있습니다. DO_NOT_TRACK=1으로 비활성화되는 CLI 원격 측정 외에는 네트워크를 호출하지 않습니다. 다만 npx 예제에서는 검사 실행 전에 npm에서 CLI를 다운로드합니다. 이 명령은 이전 CLI의 --frozen 통과 검사를 대체합니다.

키가 아니라 파일을 검사합니다. 직접 수정한 대상 파일도 통과하며, React .jsonc 카탈로그를 제외하면 기존 대상 파일에서 누락된 키는 보고하지 않습니다. .lingo/lock.json이 없으면 원본 변경 사항을 확인할 수 없으므로, 원본이 변경되었거나 한 번도 푸시되지 않았더라도 검사에 실패하지 않습니다. 이 경우 해당 사실을 표준 오류로 알립니다. lingo push이 작성하는 Lockfile을 커밋하세요.

stages 목록에 check을 추가한 다음, 사용 환경에 맞는 작업을 추가하세요. 개발자가 lingo push --wait을 실행하고 그 결과를 원본 변경 사항과 함께 커밋한다면 모든 병합 요청을 검사하세요.

yaml
check_translations:
  stage: check
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    # lingo check needs CLI 1.20.0 or newer.
    - npx -y @lingo.dev/cli@1.21.0 check

기본 브랜치 작업을 사용한다면 해당 작업이 생성한 번역 병합 요청만 검사하세요. 기능 병합 요청에서는 번역 전에 원본이 변경되기 때문입니다.

yaml
check_translations:
  stage: check
  image: node:22
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME == "lingo/translations"'
  script:
    # lingo check needs CLI 1.20.0 or newer.
    - npx -y @lingo.dev/cli@1.21.0 check

이 통과 검사는 번역과 원본 변경 사항을 함께 커밋하는 구성에 적합합니다.

번역 실행 위치모든 병합 요청에 통과 검사 적용
개발자가 병합 요청을 열기 전에 lingo push --wait을 실행하고 결과를 커밋예. 번역 없이 원본만 변경된 병합 요청을 실패 처리합니다.
병합 요청 작업이 원본 브랜치에 커밋아니요. 번역 전 커밋을 검사하게 되며, 작업에서 푸시해도 새 파이프라인이 시작되지 않습니다.
기본 브랜치 작업이 번역 병합 요청을 생성위의 두 번째 작업으로 lingo/translations에만 적용합니다. 기능 병합 요청은 설계상 번역 전에 원본을 변경합니다.

원본 해시는 바이트 단위까지 정확히 일치해야 합니다. lingo push을 실행한 checkout과 CI의 checkout에서 같은 줄바꿈 형식을 사용하도록 하세요. 예를 들어 .gitattributes에 * text=auto eol=lf을 설정할 수 있습니다.

반복 작업의 예측 가능성 확보 #

자동 작업이 의도한 신뢰할 수 있는 브랜치와 원본 경로에서만 실행되도록 필터링하세요. 병합 요청 트리거를 사용한다면 원본 프로젝트와 대상 브랜치도 제한하세요. 적절한 브랜치 규칙이나 지속적 통합 건너뛰기 정책을 적용하고, 변경 사항이 없으면 종료하도록 설정해 자동 생성된 커밋이 번역을 반복 제출하지 않게 하세요.

모노레포에서는 사용하려는 구성이 있는 패키지로 이동하고, 해당 패키지의 상대 경로를 기준으로 출력과 상태를 보존하세요. 독립적인 패키지는 서로 다른 로컬라이제이션 엔진과 로캘을 사용할 수 있으므로 Lockfile도 각각 따로 유지하세요. 네트워크 접근, 러너 도구, 변수, 저장소 정책이 뒷받침된다면 자체 관리형 GitLab에서도 같은 러너 방식을 사용할 수 있습니다.

일반적인 증분 번역에서는 원본이 바뀌지 않는 한 수동으로 수정한 대상 키가 유지될 수 있습니다. 원본이 변경되면 해당 키가 다시 생성될 수 있습니다. 누락된 파일 채우기와 강제 재생성은 적용 범위가 다릅니다. 파일 패턴을 지정하지 않으면 --force은 구성된 모든 원본 및 대상 로캘에 적용되며, 승인된 번역을 대체할 수 있습니다. 패턴을 명시하고, 강제로 작업을 실행하기 전에 예상치를 확인하세요. 제출 명령을 변경할 때는 푸시를 참조하세요.

파이프라인 복구 및 사용 종료 #

오류를 바탕으로 다음 조치를 결정하세요. 패키지 설치 문제를 해결하거나, 권한이 있는 변수를 제공하거나, 검토를 완료하거나, 병합 충돌을 해결하세요. 실패한 대상 작업은 원인을 수정한 뒤 다시 시도하세요. 성공한 아티팩트는 보존하되, 일부만 완료된 릴리스는 미완료 상태임을 명확히 표시하세요.

새 파이프라인 실행을 중지하려면 트리거를 비활성화하세요. 러너 실행을 취소할 때는 이미 제출된 번역의 상태를 별도로 확인하세요. 이 구성을 더 이상 사용하지 않을 때는 불필요해진 API 및 저장소 자격 증명을 제거하세요.