Lingo.dev Bitbucket 통합

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

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

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

콘텐츠 변경사항이 푸시될 때 브랜치에 직접 커밋
번역 업데이트를 위해 브랜치를 대상으로 하는 풀 리퀘스트

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

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

시작해 보겠습니다!

사전 요구사항

리포지토리 설정

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

1단계. 인증 설정

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

API 키 추가

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

원시 LLM API 사용자의 경우:

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

Lingo.dev Engine 사용자의 경우:

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

Bitbucket 액세스 토큰 추가 (풀 리퀘스트 모드용)

풀 리퀘스트 모드를 사용할 계획이라면 액세스 토큰을 생성하세요:

Repository settings → Access tokens → Create Repository Access Token으로 이동
다음 권한 범위를 부여하세요:
- Read & write repositories
- Read & write pull requests
토큰을 리포지토리 변수로 추가하세요:
- 변수 이름: BB_TOKEN
- 변수 값: Bitbucket 액세스 토큰

2단계. 워크플로우 생성

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

script:
  - pipe: lingodotdev/lingo.dev:main

이 구성은 Lingo.dev 파이프를 사용하여 번역 엔진을 자동으로 실행합니다.

필수 권한

Bitbucket Pipelines는 저장소 변수 및 git 작업에 대한 액세스가 필요합니다:

저장소 변수:

LINGODOTDEV_API_KEY — Lingo.dev 엔진 사용자에게 필수
OPENAI_API_KEY 또는 ANTHROPIC_API_KEY — 원시 LLM API 사용자에게 필수

풀 리퀘스트 모드의 경우:

BB_TOKEN — 풀 리퀘스트 생성 및 관리에 필수

액세스 토큰 범위(풀 리퀘스트 모드 사용 시):

저장소 읽기 및 쓰기 — 저장소 콘텐츠에 액세스하고 수정
풀 리퀘스트 읽기 및 쓰기 — 풀 리퀘스트 생성 및 관리

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

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

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

직접 커밋 모드(기본값)

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

script:
  - pipe: lingodotdev/lingo.dev:main

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

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

풀 리퀘스트 모드

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

script:
  - pipe: lingodotdev/lingo.dev:main
    variables:
      LINGODOTDEV_PULL_REQUEST: "true"

풀 리퀘스트 모드를 위한 필수 설정

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

액세스 토큰 요구 사항: BB_TOKEN에는 저장소와 풀 리퀘스트 모두에 대한 읽기 및 쓰기 권한이 포함되어야 합니다.

참고: 풀 리퀘스트 모드를 사용할 때는 BB_TOKEN 변수가 필요합니다.

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

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

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

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

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

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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main

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

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

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

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

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}" # 또는 OPENAI_API_KEY/ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

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

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

고급 구성

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

Lingo.dev 엔진 사용 예시:

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                LINGODOTDEV_API_KEY: "${MY_LINGODOTDEV_API_KEY}"
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

원시 LLM API 사용 예시:

image:
  name: atlassian/default-image:2

pipelines:
  branches:
    feat/*:
      - step:
          name: Run i18n
          script:
            - pipe: lingodotdev/lingo.dev:main
              variables:
                OPENAI_API_KEY: "${MY_OPENAI_API_KEY}" # 또는 ANTHROPIC_API_KEY
                BB_TOKEN: "${MY_ACCESS_TOKEN}"
                LINGODOTDEV_PULL_REQUEST: "true"
                LINGODOTDEV_PULL_REQUEST_TITLE: "feat: update translations"
                LINGODOTDEV_COMMIT_MESSAGE: "feat: update translations"
                LINGODOTDEV_WORKING_DIRECTORY: "apps/web"
                LINGODOTDEV_PROCESS_OWN_COMMITS: "true"

구성 옵션:

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)
BB_TOKEN — Bitbucket 액세스 토큰 (풀 리퀘스트 모드에 필요)