CI/CD 로컬라이제이션 워크플로

Lingo.dev는 CI/CD에서 로컬라이제이션을 자동으로 실행합니다. 방법은 두 가지입니다. 서버 사이드에서 push와 pull request에 반응하는 GitHub App을 쓰거나, 자체 파이프라인 안에서 CLI를 실행하는 방식입니다. 두 방식 모두 변경이 있을 때마다 번역을 동기화하고, 실제로 바뀐 문자열만 처리하므로 프로젝트 규모가 커져도 로컬라이제이션을 빠르고 비용 효율적으로 유지할 수 있습니다.

옵션 1: GitHub App(권장)#

GitHub App은 지속적 로컬라이제이션을 가장 간단하게 운영하는 방법입니다. 저장소를 감시하며 서버 사이드에서 번역을 수행하므로, 파이프라인에 따로 설치할 것도 없고 CI secret으로 보관할 API 키도 필요하지 않습니다.

설정은 한 번이면 끝입니다:

1. 저장소에 Lingo.dev GitHub App을 설치합니다.
2. .lingo/config.json를 커밋하세요. 여기에는 orgId, engineId, 소스 로캘, 대상 로캘, 그리고 번역할 파일이 들어갑니다. 먼저 로컬에서 lingo init와 lingo link를 실행해 파일을 생성한 뒤, 결과를 커밋하면 됩니다.
3. Push합니다.

그다음부터는 App이 두 가지 워크플로 방식을 모두 처리합니다:

• 기본 브랜치로 push하면 번역을 해당 브랜치에 다시 커밋합니다.
• pull request에서는 번역을 해당 PR에 추가해 머지 전에 검토할 수 있게 해줍니다.

App은 번역 상태를 서버 사이드에서 추적하므로 저장소 안에서 충돌할 lockfile이 없고, 별도의 검증 단계를 연결할 필요도 없습니다. 소스와 대상 로캘을 항상 동기화된 상태로 유지해 줍니다.

옵션 2: 자체 파이프라인에서 CLI 실행#

GitHub를 사용하지 않거나, 빌드와 테스트 작업 옆에 로컬라이제이션을 명시적인 단계로 두고 싶다면 CLI를 직접 실행하세요. Node.js 22 이상을 지원하는 모든 CI 환경에서 사용할 수 있습니다. GitHub Actions, GitLab CI, Bitbucket Pipelines는 물론 그 외 환경에서도 동작합니다.

흐름은 언제나 같습니다:

1. @lingo.dev/cli를 설치합니다.
2. LINGO_API_KEY 환경 변수를 통해 API 키로 인증합니다.
3. 변경된 문자열을 번역하려면 lingo push를 실행합니다.
4. 결과를 커밋하거나, 작업에서 pull request를 엽니다.

Lingo.dev API 키는 CI secret으로 저장하고 LINGO_API_KEY로 노출하세요. 커밋된 .lingo/config.json는 CLI에 무엇을 번역할지 알려 주고, 커밋된 .lingo/lock.json(lingo push로 다시 생성됨)는 상태를 추적해 변경된 문자열만 처리하도록 합니다.

최소 GitHub Actions 예제#

이 워크플로는 CLI를 설치하고, main에 push가 발생할 때마다 번역을 실행한 뒤, 결과를 다시 커밋합니다:

name: Localize
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  localize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @lingo.dev/cli
      - run: lingo push
        env:
          LINGO_API_KEY: ${{ secrets.LINGO_API_KEY }}
      - name: Commit translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add .
          git commit -m "chore: update translations" || echo "No changes"
          git push

같은 두 줄, 즉 npm install -g @lingo.dev/cli 다음 lingo push를 GitLab CI의 script: 블록이나 Bitbucket Pipelines 단계에도 그대로 넣을 수 있습니다. 이 플랫폼에서는 LINGO_API_KEY를 마스킹/보호된 CI 변수로 설정하세요.

직접 커밋할까, pull request로 보낼까?#

어느 방식을 선택하든 번역 결과를 반영하는 방식은 직접 정할 수 있습니다:

GitHub App은 이 두 가지를 자동으로 모두 제공합니다. 기본 브랜치로 push되면 번역을 커밋하고, 열려 있는 PR에는 번역을 추가합니다. 자체 파이프라인에서는 선택이 여러분 몫입니다. 위 예시처럼 결과를 커밋해도 되고, 브랜치에 push하는 대신 작업이 pull request를 열도록 해도 됩니다.

배포 전 번역 검증#

번역되지 않은 콘텐츠가 배포되지 않게 하려면, 배포 단계 전에 lingo check를 게이트로 추가하세요. 아직 번역이 필요한 문자열이 하나라도 있으면 0이 아닌 상태 코드로 종료합니다:

- name: Verify translations
  run: lingo check

GitHub App은 로캘을 지속적으로 동기화해 주므로, 별도의 검증 단계는 주로 CLI를 직접 실행할 때 유용합니다.

모노레포#

각 패키지마다 자체 .lingo/config.json가 있는 모노레포라면 glob을 전달해 특정 패키지로 실행 범위를 좁히거나, 해당 패키지 디렉터리에서 CLI를 실행할 수 있습니다:

lingo push "apps/web/**"

다음 단계#