GitHub Actions 지속적 통합 구성 예제

신뢰할 수 있는 GitHub Actions 작업에서 번역을 실행하고 아티팩트를 확인한 뒤, 결과가 준비되면 풀 리퀘스트로 전달하는 단계를 추가하세요.

번역에 기존 파이프라인의 트리거와 검사를 활용해야 한다면 GitHub Actions에서 Lingo.dev CLI를 실행하세요. 러너가 저장소 구성을 읽고 원문 변경 사항을 제출한 다음 번역 파일을 다운로드합니다. 이 파일을 아티팩트로 보관할지, 풀 리퀘스트로 만들지는 직접 결정할 수 있습니다.

이 예제는 수동 실행과 저장소 읽기 전용 권한으로 시작합니다. 변경된 메시지 하나를 확인한 뒤, 번역 풀 리퀘스트에 필요한 쓰기 권한을 추가할 수 있습니다. 기본 제공 GitHub App을 사용하면 이 러너를 구성하지 않고도 저장소 처리를 맡길 수 있습니다.

저장소 준비 #

로컬에서 원본 파일 하나와 대상 언어 하나로 CLI 빠른 시작을 완료하세요. .lingo/config.json, 확인을 마친 대상 파일, .lingo/lock.json을 커밋하세요. 구성에서는 로컬라이제이션 엔진, 원본 및 대상 로캘, 파일 패턴을 지정합니다. Lockfile은 이후 원문 변경 사항을 처리할 기준 상태를 기록합니다.

아래 예제에서는 locales/en.json을 원본으로, 스페인어를 대상 언어로 설정해 locales/es.json을 생성합니다. 아직 없는 대상 파일을 처음 생성할 때는 lingo push --backfill-missing --wait을 사용하고, 이후 원문을 수정할 때는 lingo push --wait을 사용합니다. 백필은 누락된 대상 파일을 선택하는 기능이므로, 기존 파일 안에 빠진 키를 복구하는 용도로는 사용할 수 없습니다.

저장소 또는 환경의 액션 비밀 값에 LINGO_API_KEY을 추가하세요. 이 값은 GitHub 저장소 권한과는 별개로 Lingo.dev 접근 권한을 부여합니다. 자격 증명을 사용하는 작업은 신뢰할 수 있는 코드에서만 실행하세요. 특히 pull_request_target을 사용해 신뢰할 수 없는 풀 리퀘스트의 최신 커밋을 체크아웃한 뒤, 비밀 값이 제공된 상태에서 실행해서는 안 됩니다.

이 예제에서는 CLI 버전을 고정합니다. 프로젝트의 의존성과 Lockfile로 버전을 관리하려면 지속적 통합 설정 가이드를 따르세요.

번역 아티팩트 가져오기 #

다음을 .github/workflows/translate.yml으로 저장하세요. 이 예제는 Node.js 22를 사용합니다.

yaml
name: Translate catalog
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Translate and download
        # Replace 1.21.0 with the current CLI version.
        run: npx -y @lingo.dev/cli@1.21.0 push --wait
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Inspect expected output
        run: |
          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
      - uses: actions/upload-artifact@v4
        with:
          name: translated-catalog
          include-hidden-files: true
          path: |
            locales/es.json
            .lingo/lock.json

커밋된 .lingo/config.json에서 조직과 엔진 식별자를 확인하세요. 영어 원문 한 곳을 수정해 커밋한 뒤, 신뢰할 수 있는 해당 브랜치에서 워크플로를 수동으로 실행하세요. 작업 로그에서 실행 결과와 변경 내역을 확인한 다음, 아티팩트를 다운로드해 수정한 부분에 해당하는 스페인어 항목을 찾으세요. 애플리케이션에서 해당 항목을 불러와 의미와 변수를 확인하세요.

업로드에 숨김 파일도 포함되므로 .lingo/lock.json이 보존됩니다. 경로 목록에는 의도한 대상 파일과 Lockfile만 포함하세요. 자격 증명이나 다른 비공개 숨김 파일까지 포함하도록 범위를 넓히지 마세요.

셸 검사는 파일 존재 여부와 JSON 구문을 확인합니다. 이전 대상 파일도 두 검사를 모두 통과할 수 있으므로, 변경된 항목을 직접 확인하는 것이 중요합니다. 로컬라이제이션 엔진에서 사람이 하는 검토를 요구한다면, 명령이 종료된 뒤에도 해당 실행은 검토를 기다리고 있을 수 있습니다. 일회성 러너에서 이 정책을 사용하기 전에 지속적 통합 실행 상태 보존 절차를 추가하세요. 제출 후 해당 실행의 포인터와 원래 프로젝트 루트의 절대 경로를 내보내고, .lingo-ci/run.json, .lingo-ci/project-root.txt, .lingo/config.json, locales/en.json, 대상 파일, Lockfile을 접근이 제한된 아티팩트로 업로드하세요. 이후 검사에 실패하더라도 복구 가능한 상태가 사라지지 않도록 내보내기와 업로드 단계에 if: always()을 사용하세요. 포인터가 없다면 제출 상태를 조사해야 하며, 임의로 만들어서는 안 됩니다.

검토가 끝나면 기록된 절대 루트 경로에 정확히 같은 리비전과 파일 상태를 복원하세요. 포인터도 복원한 뒤 별도로 인증하고, 충돌 검사를 거치는 가져오기를 사용하세요. 다른 러너에서 해당 경로를 재현할 수 없다면, 권한이 있는 영구 러너에서 제출과 가져오기를 수행하세요. 첫 번째 아티팩트에 있는 이전 대상 파일을 완료된 번역으로 간주하지 마세요.

push --wait은 대기하면서 완료되어 사용 가능한 결과를 다운로드합니다. --wait이 없으면 푸시는 일반적으로 제출 직후 종료됩니다. 제출과 가져오기를 별도 작업으로 나누는 경우에도 같은 실행 상태 내보내기와 복원 절차가 필요합니다. Lockfile만 복사해서는 충분하지 않습니다. 동일한 작업이 완료되면서 다운로드한 대상 파일과 Lockfile은 함께 보관하고, ~/.lingo 전체를 압축해 보관하지 마세요.

풀 리퀘스트로 전달 #

아티팩트 확인을 성공적으로 마쳤다면 작업에 contents: write 및 pull-requests: write 권한을 부여하세요. 저장소 정책에서도 액션의 풀 리퀘스트 생성을 허용해야 합니다. GITHUB_TOKEN은 이러한 GitHub 작업에 권한을 부여하며, 번역에는 계속 LINGO_API_KEY을 사용해야 합니다.

팀의 봇 정책에 따라 깃 사용자 정보를 설정하세요. 그런 다음 결과 검증 단계 뒤에 예상한 대상 파일과 Lockfile만 스테이징하는 단계를 추가하세요.

bash
git add locales/es.json .lingo/lock.json
git diff --cached --quiet && exit 0
branch="lingo/translations-${GITHUB_RUN_ID}"
git switch -c "$branch"
git commit -m "chore: update translations"
git push origin "$branch"
gh pr create --fill --base "$GITHUB_REF_NAME" --head "$branch"

GitHub 호스팅 러너에는 GitHub CLI가 포함되어 있습니다. 이 단계에 secrets.GITHUB_TOKEN의 GH_TOKEN을 제공하세요. 이 절차는 신뢰할 수 있는 브랜치에서의 수동 실행과 새 브랜치 이름을 전제로 합니다. 기존 브랜치로 다시 실행할 때는 브랜치를 재사용할지 교체할지 명시적으로 결정해야 합니다. 포크에 변경 사항을 다시 쓰는 워크플로는 아닙니다.

풀 리퀘스트의 대상은 작업을 수동 실행한 브랜치입니다. GitHub에서 해당 워크플로를 승인 대기 상태로 표시하면 저장소 쓰기 권한이 있는 사용자가 워크플로 실행 승인을 선택해야 합니다. GitHub의 GITHUB_TOKEN 동작을 참고하세요. 병합하기 전에 번역 변경 내역, 검사 결과, 애플리케이션 출력을 검토하세요.

브랜치 정책이 허용한다면 작업을 트리거한 브랜치에 직접 커밋할 수도 있습니다. 다만 이 경우 별도의 콘텐츠 검토 단계가 사라지며, 반복 실행을 방지하는 조치가 필요합니다.

작업 예약 및 모노레포 처리 #

첫 실행에서 유용한 결과를 얻었다면 신뢰할 수 있는 브랜치의 푸시 트리거와 원본 경로 필터를 추가하세요. 생성된 번역 커밋이 번역 작업을 계속 다시 트리거해서는 안 됩니다. 적절한 브랜치 또는 경로 필터를 적용하고, 전달 단계에서는 변경 사항이 없으면 종료하도록 처리하세요.

모노레포에서는 번역 단계의 작업 디렉터리를 .lingo/config.json이 포함된 패키지로 설정하세요. 아티팩트 경로와 스테이징 경로에도 해당 패키지를 포함하세요. 매트릭스를 사용하면 독립적인 패키지들을 처리할 수 있지만, 두 항목이 같은 설정과 Lockfile을 동시에 업데이트하며 충돌하지 않도록 해야 합니다. 같은 실행에 속한 항목들은 실행 식별자를 공유하므로, 각 항목에 고유한 아티팩트 이름과 번역 브랜치를 지정하세요. 예를 들어 translated-catalog와 lingo/translations-${GITHUB_RUN_ID}에 패키지 이름을 추가하면 됩니다.

미완료 실행 복구 #

먼저 보고된 상태를 확인하세요. 실패한 대상은 오류를 해결해야 하고, 검토 대기 중인 대상은 검토 결정을 내려야 합니다. 로컬에서 가져오기 충돌이 발생했다면 로컬 수정본과 다운로드한 결과 중 하나를 선택해야 합니다. 성공한 결과는 확인할 수 있도록 보관하되, 미완료 로캘은 미해결 상태로 남겨 두세요. 일부만 완료된 결과를 완성된 로캘 릴리스로 처리해서는 안 됩니다.

종료 코드가 0이 아닌 경우는 명확히 드러나도록 하세요. || true, 수정 사항을 덮어쓰는 강제 가져오기, 모든 대상의 강제 처리는 원인을 숨기고 이미 승인된 작업을 덮어쓸 수 있습니다. 복구 중 리비전과 기준 상태를 보존하는 방법은 지속적 통합 워크플로 가이드에서 확인하세요.

새 러너 작업이 실행되지 않도록 하려면 워크플로나 트리거를 비활성화하세요. 작업에서 이미 번역을 제출했다면 액션을 취소할 때 해당 서버 실행도 별도로 확인하세요. 워크플로 사용을 종료할 때는 사용하지 않는 비밀 값과 저장소 쓰기 권한을 제거하세요.