Lingo.dev GitLab 통합

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

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

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

1. 콘텐츠 변경사항이 푸시될 때 브랜치에 직접 커밋
2. 번역 업데이트를 위한 브랜치 대상 머지 리퀘스트

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

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

시작해 보겠습니다!

사전 요구사항

리포지토리 설정

리포지토리에 유효한 i18n.json 파일로 구성된 Lingo.dev CLI가 설정되어 있어야 합니다. 아직 설정하지 않았다면 먼저 CLI 빠른 시작을 완료하세요.

1단계. 인증 설정

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

API 키 추가

리포지토리 설정 → CI/CD → 변수로 이동한 다음 번역 엔진 자격 증명을 추가하세요:

원시 LLM API 사용자의 경우:

• 변수 이름: OPENAI_API_KEY 또는 ANTHROPIC_API_KEY
• 변수 값: 해당 제공업체의 API 키

Lingo.dev 엔진 사용자의 경우:

• 변수 이름: LINGODOTDEV_API_KEY
• 변수 값: lingo.dev/app에서 프로젝트 API 키

GitLab 액세스 토큰 추가

리포지토리 작업을 위한 커스텀 액세스 토큰을 생성하세요:

1. 설정 → 액세스 토큰 → 새 토큰 추가로 이동
2. 다음 범위를 부여하세요:
   • api
   • read_repository
   • write_repository
3. 토큰을 리포지토리 변수로 추가하세요:
   • 변수 이름: GL_TOKEN
   • 변수 값: GitLab 액세스 토큰

중요: 기본 CI 작업 토큰으로는 충분하지 않습니다. 기본 토큰은 git 작업에 필요한 권한이 부족하므로 반드시 커스텀 액세스 토큰을 생성해야 합니다.

참고: 보호된 브랜치의 경우 변수도 보호된 것으로 표시되어 있는지 확인하세요. 보호되지 않은 변수는 보호된 브랜치 파이프라인에서 액세스할 수 없습니다.

2단계. 워크플로우 생성

다음과 같은 기본 구성으로 .gitlab-ci.yml 파일을 생성하거나 업데이트하세요:

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

이 구성은 최신 Docker 이미지를 사용하고 번역 엔진을 자동으로 실행합니다.

필수 권한

GitLab CI/CD는 저장소 변수 및 git 작업에 대한 액세스가 필요합니다:

저장소 변수:

• LINGODOTDEV_API_KEY — Lingo.dev 엔진 사용자에게 필요
• OPENAI_API_KEY 또는 ANTHROPIC_API_KEY — 원시 LLM API 사용자에게 필요
• GL_TOKEN — git 푸시 작업 및 병합 요청 생성에 필요

액세스 토큰 범위:

• api — 병합 요청 생성 및 관리
• read_repository — 저장소 콘텐츠 액세스
• write_repository — 커밋 푸시 및 브랜치 생성

이러한 권한을 통해 통합 시스템이 콘텐츠를 읽고, 번역을 생성하며, 현지화된 콘텐츠로 저장소를 업데이트할 수 있습니다.

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

Lingo.dev GitLab 통합은 팀의 코드 검토 요구 사항에 따라 두 가지 작동 모드를 지원합니다.

직접 커밋 모드 (기본값)

통합 시스템이 번역을 브랜치에 직접 커밋합니다:

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"

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

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

병합 요청 모드

통합 시스템이 번역 업데이트를 위한 병합 요청을 생성합니다:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_PULL_REQUEST: "true"
  script:
    - echo "Done"

병합 요청 모드를 위한 필수 설정

저장소 변수: LINGODOTDEV_API_KEY와 GL_TOKEN 모두 저장소 변수로 구성되어야 합니다.

액세스 토큰 요구 사항: GL_TOKEN에는 병합 요청을 생성하고 관리하기 위한 api 범위가 포함되어야 합니다.

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

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

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

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

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

트리거: 기능 브랜치에 푸시 액션: 번역 업데이트를 기능 브랜치에 직접 커밋

lingodotdev:
  image: lingodotdev/ci-action:latest
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

흐름: 기능 브랜치에 콘텐츠 변경 푸시 → 통합이 동일한 브랜치에 번역을 커밋

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

시나리오 2: 업데이트를 위한 머지 리퀘스트 (머지 리퀘스트 모드)

트리거: 구성된 브랜치에 푸시 액션: 번역 업데이트가 포함된 머지 리퀘스트 생성

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY # 또는 OPENAI_API_KEY/ANTHROPIC_API_KEY
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
  script:
    - echo "Done"

흐름: 브랜치에 콘텐츠 변경 푸시 → 통합이 번역이 포함된 머지 리퀘스트 생성

이는 번역 업데이트에 대한 별도의 검토를 유지합니다.

고급 구성

추가 변수를 사용하여 통합 동작을 사용자 정의할 수 있습니다:

Lingo.dev 엔진 사용 예시:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    LINGODOTDEV_API_KEY: $MY_LINGODOTDEV_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

원시 LLM API 사용 예시:

lingodotdev:
  image: lingodotdev/ci-action:latest
  variables:
    OPENAI_API_KEY: $MY_OPENAI_API_KEY # 또는 ANTHROPIC_API_KEY
    GL_TOKEN: $MY_GL_TOKEN
    LINGODOTDEV_PULL_REQUEST: "true"
    LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
    LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations via @lingodotdev"
    LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
    LINGODOTDEV_PROCESS_OWN_COMMITS: "true"
  script:
    - echo "Done"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH = /^feat/

구성 옵션:

• LINGODOTDEV_API_KEY — Lingo.dev 엔진을 사용하는 경우 Lingo.dev 엔진 API 키
• OPENAI_API_KEY — 원시 LLM API를 사용하는 경우 OpenAI API 키
• ANTHROPIC_API_KEY — 원시 LLM API를 사용하는 경우 Anthropic API 키
• LINGODOTDEV_PULL_REQUEST — 직접 커밋 대신 머지 리퀘스트 생성 (기본값: false)
• LINGODOTDEV_PULL_REQUEST_TITLE — 사용자 정의 머지 리퀘스트 제목 (기본값: feat: update translations via @lingodotdev)
• LINGODOTDEV_COMMIT_MESSAGE — 사용자 정의 커밋 메시지 (기본값: feat: update translations via @lingodotdev)
• LINGODOTDEV_WORKING_DIRECTORY — 하위 디렉토리에서 통합 실행 (기본값: .)
• LINGODOTDEV_PROCESS_OWN_COMMITS — 이 통합에 의해 생성된 커밋 처리 (기본값: false)

문제 해결

일반적인 오류와 해결책: