Lingo.dev GitHub 통합

Lingo.dev GitHub Action은 새로운 콘텐츠를 자동으로 현지화하고 불완전한 번역이 프로덕션 환경에 배포되는 것을 방지하는 안전한 오픈소스 CI/CD 통합 솔루션입니다. 팀의 워크플로우 요구사항에 따라 풀 리퀘스트를 생성하거나 브랜치에 직접 커밋합니다.

또한 자동 충돌 해결을 구현하여 수동 개입 없이도 번역이 코드와 동기화된 상태를 유지합니다.

이 액션은 다양한 워크플로우 시나리오를 지원합니다:

1. 콘텐츠 변경사항이 병합될 때 메인 브랜치에 직접 커밋
2. PR이 열리거나 업데이트될 때 풀 리퀘스트 브랜치에 직접 커밋
3. 번역 업데이트를 위해 메인 브랜치를 대상으로 하는 풀 리퀘스트
4. 번역 업데이트를 위해 기존 풀 리퀘스트 브랜치를 대상으로 하는 풀 리퀘스트

이 가이드를 완료하면 다음과 같은 결과를 얻을 수 있습니다:

1. 코드 푸시에 의해 트리거되는 자동화된 현지화 설정
2. 리포지토리 시크릿을 사용한 보안 인증 구성
3. 직접 커밋 또는 풀 리퀘스트 워크플로우 중 선택
4. 지속적인 현지화가 기존 프로세스에 어떻게 적용되는지 이해

시작해 보겠습니다!

사전 요구사항

리포지토리 설정

리포지토리에 유효한 i18n.json 파일로 구성된 Lingo.dev CLI가 설정되어 있어야 합니다. 아직 설정하지 않았다면, 먼저 CLI 퀵스타트를 완료하세요.

1단계. 인증 설정

Lingo.dev GitHub Actions는 번역 엔진과 리포지토리에 접근해야 합니다. 인증은 자격 증명을 안전하게 유지하는 리포지토리 시크릿을 통해 이루어집니다.

API 키 추가

리포지토리의 Settings → Secrets and variables → Actions로 이동한 다음 번역 엔진 자격 증명을 추가하세요:

원시 LLM API 사용자의 경우:

• 시크릿 이름: OPENAI_API_KEY 또는 ANTHROPIC_API_KEY
• 시크릿 값: 해당 제공업체의 API 키

Lingo.dev Engine 사용자의 경우:

• 시크릿 이름: LINGODOTDEV_API_KEY
• 시크릿 값: lingo.dev/app에서 가져온 프로젝트 API 키

2단계. 워크플로우 생성

저장소에 .github/workflows/i18n.yml 파일을 다음과 같은 기본 구성으로 생성하세요:

name: Lingo.dev i18n

on:
  workflow_dispatch:
  push:
    branches:
      - main
      - feat/*

permissions:
  contents: write
  pull-requests: write

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

또는 기존 워크플로우에 Lingo.dev GitHub Action을 단계로 추가할 수 있습니다:

- name: Lingo.dev
  uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

필수 권한

워크플로우가 제대로 작동하려면 특정 권한이 필요합니다. GitHub Actions는 워크플로우 파일에 명시적인 권한 선언을 요구합니다:

permissions:
  contents: write # 필수: 번역 업데이트로 커밋 생성
  pull-requests: write # 선택 사항: 풀 리퀘스트 모드를 사용하는 경우에만 필요

contents: write 권한은 액션에 다음을 허용합니다:

• 번역 업데이트로 커밋 생성
• 변경 사항을 저장소에 직접 푸시
• 저장소의 파일에 접근 및 수정

이러한 권한은 워크플로우의 임시 GitHub 토큰(${{ github.token }})에 부여되며, 이 토큰은 각 워크플로우 실행마다 GitHub에서 자동으로 생성되고 워크플로우 파일에 지정한 정확한 권한을 갖습니다.

이 구성은:

• main 및 기능 브랜치에 대한 푸시 시 트리거됩니다
• 커밋 및 풀 리퀘스트에 대한 필요한 권한을 부여합니다
• 자동 업데이트를 위한 최신 액션 버전을 사용합니다
• 저장소 시크릿을 통해 API 키에 안전하게 접근합니다

추가 팁:

• Lingo.dev에서는 모든 워크플로우에 workflow_dispatch 트리거를 추가하여 GitHub Actions UI에서 수동으로 (재)실행할 수 있도록 하는 것을 선호합니다. 이는 완전히 선택 사항이지만, 매우 유용하다고 생각합니다.

3단계. 워크플로우 모드 선택

Lingo.dev GitHub Actions는 팀의 코드 검토 요구사항에 따라 두 가지 운영 모드를 지원합니다.

직접 커밋 모드 (기본값)

이 액션은 번역을 직접 브랜치에 커밋합니다:

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

이 모드는 다음과 같은 경우에 적합합니다:

• 개인 개발자 또는 소규모 팀
• 병합 전 검토가 필요한 기능 브랜치
• 번역 업데이트에 별도의 검토가 필요하지 않은 프로젝트

풀 리퀘스트 모드

이 액션은 번역 업데이트를 위한 풀 리퀘스트를 생성합니다:

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    pull-request-title: "feat: update translations"

풀 리퀘스트 모드에 필요한 권한

풀 리퀘스트 모드는 추가 권한 및 저장소 설정이 필요합니다:

permissions:
  contents: write # 필수: 저장소 콘텐츠 접근 및 커밋 생성
  pull-requests: write # 필수: 풀 리퀘스트 생성 및 업데이트

GitHub 토큰 설정: GH_TOKEN 환경 변수는 ${{ github.token }}으로 설정해야 합니다. 이는 GitHub가 각 워크플로우 실행마다 자동으로 생성하는 임시 토큰입니다. 이 토큰은 워크플로우 파일의 permissions 섹션에 지정된 권한을 정확히 가집니다.

저장소 설정: 저장소 설정에서 GitHub Actions가 풀 리퀘스트를 생성할 수 있도록 허용해야 합니다:

1. 설정 → Actions → 일반으로 이동
2. 페이지 하단으로 스크롤
3. "워크플로우 권한" 아래에서 **"GitHub Actions가 풀 리퀘스트를 생성하고 승인할 수 있도록 허용"**이 활성화되어 있는지 확인

저장소 설정에서 이 옵션이 보이지 않는 경우, 조직 설정을 확인하세요:

1. 조직의 설정 → Actions → 일반으로 이동
2. "GitHub Actions가 풀 리퀘스트를 생성하고 승인할 수 있도록 허용" 설정을 찾으세요

이 모드는 다음과 같은 경우에 적합합니다:

• 엄격한 코드 검토 요구사항이 있는 팀
• 번역 변경 사항에 별도의 승인이 필요한 프로젝트
• 모든 변경 사항에 명시적 검토가 필요한 워크플로우

4단계. 워크플로우 시나리오

Lingo.dev GitHub Action은 다양한 개발 워크플로우에 자동으로 적응합니다. 이러한 시나리오를 이해하면 팀에 맞는 최적의 구성을 선택하는 데 도움이 됩니다.

시나리오 1: 메인 브랜치 업데이트 (직접 커밋)

트리거: 메인 브랜치로 푸시 (예: 풀 리퀘스트 병합 시) 액션: 번역 업데이트를 메인 브랜치에 직접 커밋

on:
  push:
    branches: [main]

# 액션이 메인 브랜치에 직접 커밋

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

흐름: main에 푸시된 콘텐츠 변경 → 액션이 main에 번역을 커밋

이 시나리오는 콘텐츠 변경이 병합된 직후 메인 브랜치에 항상 최신 번역이 유지되도록 보장합니다.

팁: 이 모드를 권장합니다. 완벽한 현지화를 보장하기 위해 잘 구성된 AI 현지화 엔진이 필요합니다. 장점은 누락된 번역이 모든 프로덕션 배포 전에 자동으로 확인되고 채워지므로 수동 개입이 전혀 필요 없다는 것입니다.

시나리오 2: 풀 리퀘스트 업데이트 (직접 커밋)

트리거: 콘텐츠 변경이 있는 풀 리퀘스트 생성 또는 업데이트 액션: 번역 업데이트를 풀 리퀘스트 브랜치에 직접 커밋

on:
  pull_request:
    types: [opened, synchronize]

# 액션이 PR 브랜치에 직접 커밋

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

흐름: PR 브랜치의 콘텐츠 변경 → 액션이 동일한 PR 브랜치에 번역을 커밋

이는 번역 업데이트를 기능 브랜치 내에 유지하여 원본 변경 사항과 함께 번역이 검토되도록 보장합니다.

시나리오 3: 메인으로의 풀 리퀘스트 (풀 리퀘스트 모드)

트리거: 메인 브랜치로 푸시 (예: 풀 리퀘스트 병합 시) 액션: 번역 업데이트가 포함된 풀 리퀘스트 생성

on:
  push:
    branches: [main]

# 액션이 PR 생성: main/lingo.dev → main

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

흐름: main에 콘텐츠 변경사항 푸시 → 액션이 main/lingo.dev 브랜치 생성 → main/lingo.dev에서 main으로 PR 오픈

시나리오 4: 기능 브랜치로의 풀 리퀘스트(풀 리퀘스트 모드)

트리거: 콘텐츠 변경사항이 있는 풀 리퀘스트 오픈 또는 업데이트 액션: 기능 브랜치를 대상으로 번역 업데이트가 포함된 풀 리퀘스트 생성

on:
  pull_request:
    types: [opened, synchronize]

# 액션이 PR 생성: feat/new-feature/lingo.dev → feat/new-feature

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true

흐름: feat/new-feature의 콘텐츠 변경 → 액션이 feat/new-feature/lingo.dev 브랜치 생성 → feat/new-feature/lingo.dev에서 feat/new-feature로 PR 오픈

이는 각 기능 브랜치에 대한 별도의 번역 검토를 유지합니다.

브랜치 명명 규칙

풀 리퀘스트 모드를 사용할 때, Lingo.dev GitHub 액션은 일관된 명명 패턴을 따릅니다:

형식: <base-branch>/lingo.dev

예시:

• 메인 브랜치 업데이트: main/lingo.dev → main
• 기능 브랜치 업데이트: feat/user-auth/lingo.dev → feat/user-auth
• 릴리스 브랜치 업데이트: release/v2.0/lingo.dev → release/v2.0

이 명명 규칙은 번역 브랜치가 명확하게 식별되고 소스 브랜치에 자동으로 연결되도록 보장합니다.

외부 기여 처리

외부 포크로 작업할 때, 저장소 보안을 유지하기 위해 선택적 체크아웃을 구현하세요:

jobs:
  i18n:
    name: Run i18n
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: find locales/** -name "*.json" | xargs git checkout ${{ github.event.pull_request.head.sha }} --
        shell: bash
      - uses: lingodotdev/lingo.dev@main
        with:
          api-key: ${{ secrets.LINGODOTDEV_API_KEY }}

외부 기여에 필요한 권한

외부 포크를 처리하려면 기여를 안전하게 처리하기 위한 권한 상승이 필요합니다:

permissions:
  actions: write # 필수: 워크플로우 정보 및 아티팩트 접근
  contents: write # 필수: 커밋 생성 및 저장소 콘텐츠 접근
  pull-requests: write # 필수: 외부 포크의 풀 리퀘스트 업데이트

actions: write 권한은 특히 다음을 위해 필요합니다:

• 외부 포크의 풀 리퀘스트 메타데이터 접근
• 보안 검증을 위한 워크플로우 컨텍스트 읽기
• 아티팩트 및 워크플로우 상태를 안전하게 처리

이러한 상승된 권한은 선택적 파일 체크아웃을 통해 저장소 보안을 유지하면서 액션이 외부 기여자의 번역을 안전하게 처리할 수 있도록 보장합니다.

이 접근 방식은:

• 포크에서 번역 파일만 체크아웃
• 민감한 저장소 코드 노출 방지
• 액션에 필요한 쓰기 권한 유지

고급 구성

추가 매개변수를 사용하여 액션 동작을 사용자 정의하세요:

- uses: lingodotdev/lingo.dev@main
  env:
    GH_TOKEN: ${{ github.token }}
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    pull-request: true
    commit-message: "feat: update translations via lingo.dev"
    working-directory: "apps/web"
    version: "latest"
    process-own-commits: false
    parallel: true

구성 옵션:

• commit-message — 번역 커밋을 위한 사용자 정의 메시지
• working-directory — 하위 디렉토리에서 액션 실행
• version — 특정 CLI 버전으로 고정(권장하지 않음)
• process-own-commits — 이 액션에 의해 생성된 커밋 처리
• parallel — 로컬라이제이션 작업의 병렬 처리 활성화(기본값: false)

병렬 처리

GitHub 액션은 대규모 프로젝트의 번역 워크플로우를 크게 가속화하기 위해 로컬라이제이션 작업의 병렬 처리를 지원합니다. parallel: true로 설정하여 이 기능을 활성화하세요:

- uses: lingodotdev/lingo.dev@main
  with:
    api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
    parallel: true

활성화되면 액션은 다음과 같은 작업을 수행합니다:

• 여러 동시 작업자에게 로컬라이제이션 작업 분배
• 처리량을 최대화하기 위한 지능형 작업 분배 알고리즘 사용
• 신중한 동시성 관리를 통해 파일 손상 및 경쟁 조건 방지
• 많은 번역 파일이 있는 프로젝트의 처리 시간 대폭 단축

이 기능은 특히 다음과 같은 경우에 유용합니다:

• 광범위한 번역 요구 사항이 있는 대규모 프로젝트
• 여러 로케일을 동시에 처리하는 워크플로우
• 더 빠른 CI/CD 파이프라인 실행이 필요한 팀

참고: 병렬 처리는 API 사용량을 증가시킬 수 있습니다. 엄격한 속도 제한이 있는 경우 사용량을 모니터링하세요.

검증 모드

모든 프로덕션 배포 전에 --frozen 플래그를 사용하여 모든 번역이 최신 상태인지 확인할 수 있습니다.

배포 파이프라인에서 --frozen 플래그를 사용하는 예시입니다:

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx lingo.dev@latest i18n --frozen
      - run: npm run build
      - run: npm run deploy

--frozen 플래그는 다음과 같은 기능을 수행합니다:

• 모든 번역이 최신 상태인지 확인
• 파일에 변경 사항을 적용하지 않음
• 번역이 누락되거나 오래된 경우 빌드 실패