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

Lingo.dev CLI는 Node.js를 지원하는 모든 CI/CD 환경에서 실행할 수 있습니다. 파이프라인 단계에 추가하면 푸시할 때마다 자동으로 번역되며, lockfile이 변경된 문자열만 처리해 프로젝트가 커져도 빠르고 비용 효율적인 번역을 유지할 수 있습니다.

GitHub를 쓰고 계신가요? 실행 방법은 두 가지입니다

GitHub App은 GitHub에서 가장 간편한 방법입니다. 한 번만 설치하면 푸시와 pull request에 자동으로 반응합니다. 러너도, API 키 시크릿도, lockfile도 필요 없고, .lingo/config.json와 engineId만으로 저장소를 설정할 수 있습니다.

GitHub Action과 아래 다른 통합 방식은 i18n.json, i18n.lock lockfile, 그리고 LINGODOTDEV_API_KEY 시크릿을 사용해 자체 파이프라인 안에서 CLI를 실행합니다. 번역을 다른 CI 단계와 함께 돌리고 싶거나 GitHub를 사용하지 않는다면 이 방식을 선택하세요.

이 가이드의 나머지 내용은 GitHub Action과 CLI를 중심으로 설명합니다.

작동 방식#

CI/CD 파이프라인은 체크아웃 이후 단계에서 CLI를 실행합니다. CLI는 i18n.json 설정을 읽고, 소스 파일을 lockfile과 비교해 변경된 내용을 찾은 뒤, 설정된 로컬라이제이션 엔진을 통해 변경분만 번역하고, 결과를 대상 로캘 파일에 기록합니다. 이후 파이프라인은 워크플로 선호에 따라 번역된 파일을 커밋하거나 pull request를 생성합니다.

워크플로 선택하기#

대부분의 팀 구조는 아래 네 가지 워크플로 패턴으로 커버할 수 있습니다. 가장 단순한 방식부터 시작해 팀이 성장하면 점진적으로 확장해 보세요.

워크플로	작동 방식	추천 대상	트레이드오프
main에 커밋	번역 후 main 브랜치에 바로 커밋	소규모 팀, 마찰 없는 운영	번역 검토 단계가 없음
main에서 PR 생성	번역 후 검토용 PR 생성	번역을 검토하는 팀	PR을 수동으로 승인해야 함
기능 브랜치에 커밋	기능 브랜치에 푸시할 때 번역 실행	장기간 유지되는 기능 브랜치	브랜치 히스토리에 번역 커밋이 남음
기능 브랜치에서 PR 생성	번역 후 기능 브랜치에서 PR 생성	기능 단위로 최대한 세밀하게 제어하고 싶은 경우	기능마다 여러 개의 PR이 생김

시작은 이렇게 추천합니다

대부분의 팀에는 main에 커밋하는 방식이 잘 맞습니다. 푸시할 때마다 번역이 함께 배포되고, lockfile이 일관성을 보장하며, 로컬라이제이션 엔진의 용어집과 브랜드 보이스 규칙이 품질을 뒷받침합니다. 번역에 사람의 검토가 필요해지면 PR 기반 워크플로로 전환하세요.

빠른 설정#

Lingo.dev API 키를 CI/CD 시크릿으로 저장한 뒤, 파이프라인에 번역 단계를 추가하세요.

Lingo.dev는 체크아웃, 번역, 커밋/PR 생성까지 처리하는 공식 GitHub Action을 제공합니다.

워크플로 파일이나 API 키 시크릿, lockfile을 직접 관리하고 싶지 않으신가요? GitHub App을 사용하면 그런 것 없이 GitHub에서 지속적으로 로컬라이제이션할 수 있습니다. 한 번 설치하고 .lingo/config.json만 설정하면 됩니다.

main에 커밋:

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

main에서 PR 생성 - pull-request: true와 GH_TOKEN를 추가하세요:

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          pull-request: true
        env:
          GH_TOKEN: ${{ github.token }}

기능 브랜치 워크플로, 커스텀 커밋 메시지, 모노레포 지원, GPG 서명에 대해서는 전체 GitHub Actions 통합 가이드를 참고하세요.

번역 검증#

--frozen 플래그와 lockfile은 GitHub Action과 CLI에서 사용됩니다. GitHub App은 서버 측에서 번역 상태를 추적하므로 lockfile도 없고, 이에 대응하는 --frozen도 없습니다.

번역되지 않은 콘텐츠가 프로덕션에 배포되지 않도록 --frozen 플래그를 배포 게이트로 활용하세요. 번역이 필요한 문자열이 하나라도 있으면 CLI는 0이 아닌 상태 코드로 종료됩니다.

bash

npx lingo.dev@latest run --frozen

배포 전에 실행되는 별도의 파이프라인 단계로 다음을 추가하세요:

yaml

- name: Verify translations
  run: npx lingo.dev@latest run --frozen

모노레포 워크플로#

각 패키지가 자체 번역 파일을 갖는 멀티 패키지 모노레포라면, 특정 패키지를 대상으로 working-directory 옵션을 사용하세요:

yaml

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    working-directory: apps/web

병합 충돌#

이 내용은 GitHub Action과 CLI에 해당합니다. GitHub App은 lockfile을 사용하지 않기 때문에 해결해야 할 i18n.lock 충돌도 없습니다.

번역 변경이 포함된 브랜치들이 병합될 때 lockfile(i18n.lock) 충돌이 발생할 수 있습니다. 해결 방법은 간단합니다. 충돌 난 lockfile을 삭제하고 병합을 완료한 다음 다시 생성하면 됩니다:

bash

git merge feature-branch
rm i18n.lock
git add .
git merge --continue
npx lingo.dev@latest lockfile --force

lockfile --force 명령은 새 번역을 트리거하지 않고 현재 소스 파일 상태를 기준으로 lockfile을 다시 생성합니다. 리베이스 기반 해결 방법과 충돌 방지 전략은 고급 통합 패턴 가이드를 참고하세요.

다음 단계#

GitHub App

GitHub에서 관리형 지속 로컬라이제이션 — 러너, 시크릿, lockfile 없이

GitHub Actions

GPG 서명과 커스텀 구성을 포함한 전체 GitHub Actions 설정

GitLab CI

액세스 토큰과 merge request를 포함한 전체 GitLab CI/CD 설정

Bitbucket Pipelines

Pipe와 pull request를 포함한 전체 Bitbucket Pipelines 설정

고급 패턴

워크플로 선택, 충돌 해결, 배포 게이트

GitHub를 쓰고 계신가요? 실행 방법은 두 가지입니다

이 가이드의 나머지 내용은 GitHub Action과 CLI를 중심으로 설명합니다.

작동 방식#

워크플로 선택하기#

대부분의 팀 구조는 아래 네 가지 워크플로 패턴으로 커버할 수 있습니다. 가장 단순한 방식부터 시작해 팀이 성장하면 점진적으로 확장해 보세요.

워크플로	작동 방식	추천 대상	트레이드오프
main에 커밋	번역 후 main 브랜치에 바로 커밋	소규모 팀, 마찰 없는 운영	번역 검토 단계가 없음
main에서 PR 생성	번역 후 검토용 PR 생성	번역을 검토하는 팀	PR을 수동으로 승인해야 함
기능 브랜치에 커밋	기능 브랜치에 푸시할 때 번역 실행	장기간 유지되는 기능 브랜치	브랜치 히스토리에 번역 커밋이 남음
기능 브랜치에서 PR 생성	번역 후 기능 브랜치에서 PR 생성	기능 단위로 최대한 세밀하게 제어하고 싶은 경우	기능마다 여러 개의 PR이 생김

시작은 이렇게 추천합니다

빠른 설정#

Lingo.dev API 키를 CI/CD 시크릿으로 저장한 뒤, 파이프라인에 번역 단계를 추가하세요.

Lingo.dev는 체크아웃, 번역, 커밋/PR 생성까지 처리하는 공식 GitHub Action을 제공합니다.

main에 커밋:

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

main에서 PR 생성 - pull-request: true와 GH_TOKEN를 추가하세요:

yaml

name: Translate
on:
  push:
    branches: [main]
permissions:
  contents: write
  pull-requests: write
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
          pull-request: true
        env:
          GH_TOKEN: ${{ github.token }}

기능 브랜치 워크플로, 커스텀 커밋 메시지, 모노레포 지원, GPG 서명에 대해서는 전체 GitHub Actions 통합 가이드를 참고하세요.

번역 검증#

bash

npx lingo.dev@latest run --frozen

배포 전에 실행되는 별도의 파이프라인 단계로 다음을 추가하세요:

yaml

- name: Verify translations
  run: npx lingo.dev@latest run --frozen

모노레포 워크플로#

각 패키지가 자체 번역 파일을 갖는 멀티 패키지 모노레포라면, 특정 패키지를 대상으로 working-directory 옵션을 사용하세요:

yaml

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    working-directory: apps/web

병합 충돌#

이 내용은 GitHub Action과 CLI에 해당합니다. GitHub App은 lockfile을 사용하지 않기 때문에 해결해야 할 i18n.lock 충돌도 없습니다.

bash

git merge feature-branch
rm i18n.lock
git add .
git merge --continue
npx lingo.dev@latest lockfile --force

다음 단계#

GitHub App

GitHub에서 관리형 지속 로컬라이제이션 — 러너, 시크릿, lockfile 없이

GitHub Actions

GPG 서명과 커스텀 구성을 포함한 전체 GitHub Actions 설정

GitLab CI

액세스 토큰과 merge request를 포함한 전체 GitLab CI/CD 설정

Bitbucket Pipelines

Pipe와 pull request를 포함한 전체 Bitbucket Pipelines 설정

고급 패턴

워크플로 선택, 충돌 해결, 배포 게이트