CI에서 번역 자동화하기

확인된 소스 리비전부터 파일 검수와 애플리케이션 검사까지, 번역을 릴리스마다 반복할 수 있는 절차로 만드세요.

릴리스 파이프라인은 소스 리비전을 사람들이 실제로 사용할 수 있는 결과물로 연결합니다. 번역 과정에서도 이 연결이 유지되어야 합니다. 작업은 어떤 소스가 바뀌었는지 파악하고, 그에 맞는 대상 파일을 가져오고, 다음 단계에서 결과를 수락하거나 거부할 수 있도록 충분한 근거를 남겨야 합니다.

까다로운 상황은 첫 요청이 성공한 뒤부터 나타납니다. 검토자가 아직 편집 중이거나, 실행기가 사라지거나, 이전 번역이 끝나기도 전에 원문의 새 버전이 도착하는 경우입니다. 이 가이드에서는 최신 상태가 아닌 파일을 게시하거나 이미 승인된 수정 사항을 불필요하게 덮어쓰지 않고도 이런 상황에 대응할 수 있는 CI 프로세스를 구축합니다. 제공업체별 YAML 설정은 GitHub Actions, GitLab, Bitbucket, 빌드카이트 설정 예제에서 확인할 수 있습니다.

번역을 릴리스의 어느 단계에 반영할지 결정하기 #

관리형 GitHub App의 저장소 워크플로가 요구 사항에 맞는다면 이를 사용하세요. 기본 브랜치가 변경되면 번역 풀 리퀘스트가 생성됩니다. 풀 리퀘스트 처리를 별도로 활성화하면 해당 풀 리퀘스트의 브랜치에 결과가 기록됩니다. 실행 승인은 번역 작업을 허용하는 절차이며, 콘텐츠 검토와 병합은 그 이후에 이루어집니다.

CLI 실행기를 사용하면 파이프라인이 제출, 가져오기, 전달을 담당합니다. 릴리스 절차에 맞는 전달 대상을 선택하세요.

전달 대상검토 및 전달 방식
아티팩트만 생성저장소나 릴리스를 변경하기 전에 다른 작업이나 사람이 결과물을 검사합니다.
번역 브랜치 및 풀 리퀘스트번역 변경 사항을 기본 브랜치에 반영하기 전에 별도로 검토합니다.
소스 풀 리퀘스트의 브랜치소스와 번역을 하나의 변경 사항으로 함께 검토합니다.
기본 브랜치에 직접 커밋브랜치 정책에서 명시적으로 허용하는 경우 별도의 번역 풀 리퀘스트 없이 전달합니다.

저장소에 기록할 때는 동일한 번역 상태를 기록하는 실행 주체가 한 번에 하나만 작동하도록 하세요. 그렇지 않으면 서로 다른 소스 리비전을 사용하는 두 실행기가 파일과 Lockfile을 커밋하려다 경합할 수 있습니다. 생성된 커밋이 번역을 반복해서 실행하지 않도록 브랜치, 경로 또는 생성된 커밋을 기준으로 한 규칙도 필요합니다.

실행기가 이어받을 기준 상태 마련하기 #

반복 실행을 활성화하기 전에 로컬에서 소스 파일 하나를 한 언어로 번역하고 애플리케이션의 리소스 검사를 실행하세요. 구성, 수락된 대상 파일, .lingo/lock.json을 함께 커밋하세요. 변경 사항이 없는 깨끗한 checkout 상태에서도 동일한 소스 선택과 대상 파일 배치가 재현되어야 합니다.

서비스별 예제에서는 @lingo.dev/cli@1.21.0으로 버전을 고정합니다. 워크플로를 설정할 때는 해당 버전을 최신 CLI 릴리스로 바꾸세요. CLI를 프로젝트 의존성과 함께 관리하려면 npm install --save-dev --save-exact @lingo.dev/cli@1.21.0으로 설치하고 package.json 및 package-lock.json을 커밋하세요. 그런 다음 npm ci 및 npx --no-install lingo으로 Lockfile에 기록된 버전을 실행하세요.

.lingo/config.json은 로캘, 파일 패턴, 로컬라이제이션 엔진을 선택합니다. 설정 단계에서 조직과 로컬라이제이션 엔진에 대한 접근 권한을 확보하세요. 작업에서 프로젝트를 초기화하거나 연결해야 한다면 무인 실행 중 입력을 기다리게 하지 말고, 초기화 및 연결 레퍼런스에 나오는 명시적 옵션을 사용하세요.

모노레포에서는 CLI를 실행하기 전에 사용할 구성이 들어 있는 패키지로 이동하세요. 위치 인수로 전달하는 패턴은 해당 구성에서 선택한 소스의 범위를 좁힐 뿐, 다른 패키지의 구성을 선택하지는 않습니다. 독립적으로 구성된 각 패키지의 상태와 아티팩트 경로는 함께 유지하세요.

실행기의 비밀 값 관리 기능으로 LINGO_API_KEY을 주입하세요. 대화형 로그인 없이 사용할 수 있습니다. 브랜치의 스크립트를 바꿔 키를 노출할 수 있으므로, 자격 증명을 사용하는 작업은 신뢰할 수 있는 코드에서만 실행하세요. 신뢰할 수 없는 작업을 성공시키려고 보호된 변수와 포크에 대한 제한을 해제하지 말고, 해당 제한에 따라 작업을 실행할 위치를 정하세요.

적절한 유형의 작업 제출하기 #

처음부터 번역을 시작할 때는 누락된 대상 파일을 요청하세요. 기존 프로젝트에서는 먼저 기존 대상의 일반적인 소스 업데이트를 완료하고 결과를 가져와 검사하세요. 그런 다음 해당 소스 리비전을 고정한 채 누락된 로캘을 추가하고 백필하세요. 아래 명령을 실행하기 전에 언어 추가하기를 따르세요.

sh
lingo push --backfill-missing --wait

확립된 기준 상태를 바탕으로 소스 변경 사항을 처리하려면 다음을 실행하세요.

sh
lingo push --wait

최초의 일반 푸시는 번역 없이 소스 상태만 기록할 수 있습니다. 백필은 누락된 파일을 생성하는 작업을 제공하고, 이후의 일반 푸시는 소스 변경 사항을 기준으로 작업을 결정합니다. 범위를 지정한 푸시나 백필 푸시가 기존 대상 파일 안의 누락된 키를 모두 복구해 주는 것은 아닙니다.

--wait은 실행이 끝날 때까지 기다린 뒤 완료된 결과물을 다운로드합니다. 이 옵션이 없으면 푸시는 제출 직후 반환됩니다. 검토를 기다리거나 별도의 작업으로 결과를 가져오려면 CI 실행 상태 보존 절차가 필요합니다. 실행기가 종료되기 전에 홈 디렉터리에 있는 특정 비밀 정보가 아닌 포인터, 원래 프로젝트 루트의 절대 경로, 서로 일치하는 소스·구성·대상 파일·Lockfile 상태를 보존하세요. 이를 동일한 루트 경로에 복원하고 별도로 인증한 뒤 lingo pull --dry-run, lingo pull 순서로 사용하세요. 실행기에서 같은 경로를 재현할 수 없다면 접근 권한이 있는 영구 checkout 작업 공간을 사용하세요. 자격 증명이나 ~/.lingo 전체를 보관해서는 안 됩니다.

종료 상태와 보고된 대상별 결과를 보존하세요. 현재 CLI는 실패한 대상이 보고되면 실패로 종료하지만, 사람이 하는 검토로 인해 실행이 결정을 기다리는 상태로 남을 수 있습니다. 새 버전이 대기하는 동안에도 이전 파일은 그대로 존재할 수 있습니다. 전달 작업이 결과를 게시하도록 허용하기 전에 검토를 마치고 결과를 가져오세요.

정확한 명령 동작은 푸시 및 풀을 참고하세요. --yes은 강제 재생성 확인만 건너뜁니다. 사람이 하는 검토를 승인하거나 대기 중인 모든 작업을 완료 상태로 바꾸지는 않습니다.

CLI는 CI에서 업데이트 확인을 건너뜁니다. 필요한 경우 LINGO_DISABLE_UPDATE_CHECK=1 및 LINGO_TELEMETRY_DISABLED=1를 사용하면 번역 트래픽을 차단하지 않고도 업데이트 확인을 명시적으로 제어할 수 있습니다.

다음 단계에서 사용할 수 있는 파일인지 확인하기 #

변경이 예상되는 항목을 소스 리비전과 대조하세요. checkout 작업 공간에 이전 대상 파일이 이미 있다면 파일이 존재한다는 사실만으로는 근거가 부족합니다. 동일한 작업에서 다운로드한 결과물과 잠금 상태를 함께 보존하고, 실패했거나 아직 대기 중인 로캘은 미완료 상태가 분명히 드러나도록 하세요.

그런 다음 리소스 특성에 맞는 검사를 실행하세요.

  • 리액트 추출의 경우 lingo extract --check, lingo check, 프로젝트의 타입스크립트 검사, 실제 애플리케이션 빌드를 실행하세요. 각각 결과물의 서로 다른 부분을 검사합니다.
  • 네이티브 리소스는 해당 플랫폼의 리소스 생성 또는 컴파일을 실행하세요.
  • 정적 콘텐츠는 번역된 문서를 파싱하고 링크, 변수, 보존된 구문을 검사하세요.
  • 번역이 최신 상태가 아닐 때 병합 요청이 실패하도록 하려면 lingo check을 실행하세요. API 키는 필요하지 않습니다.

lingo check은 파일 단위로 작동합니다. 구성된 모든 로캘에 대해 변경된 소스와 누락된 대상 파일을 보고합니다. 기존 안드로이드, 애플, ARB 또는 마크독 파일 안에서 누락된 키를 보고하는 것은 아닙니다.

선택한 수락 절차에서 번역의 의미도 확인하세요. 빌드는 형식이 잘못된 리소스를 잡아낼 수 있지만, 중요한 조건을 바꾸는 문장은 그대로 통과시킬 수 있습니다. 검사와 검토를 통과하면 의도한 출력 경로만 커밋하거나 게시하세요. 변경 사항이 없으면 종료하는 처리는 유지하세요. 무조건 커밋해 필수 검사 실패를 감추지 말고, 필수 검사가 실패하면 작업도 실패하도록 하세요.

대체 작업을 만들기 전에 기록된 작업 재개하기 #

작업이 중단되면 해당 실행의 식별 정보와 대상별 결과를 복구하세요. 번역이 완료되었다면 새 요청을 제출하기 전에 그 결과물을 가져오세요. 대기 중에 로컬 대상 파일이 바뀌었다면 수락된 편집 내용을 확인하면서 가져오기 충돌을 해결하세요. 강제로 덮어쓰면 워크플로가 보존해야 할 바로 그 수정 사항을 잃을 수 있습니다.

원인을 진단하는 동안 Lockfile을 유지하세요. 이를 삭제하면 다음 실행의 소스 기준 상태가 달라져, 일부만 복구하려던 작업이 다른 작업으로 바뀔 수 있습니다. 변경 내역을 확인하고 아직 완료되지 않은 범위만 다시 시도하세요. 이 판단 과정은 중단된 로컬라이제이션 실행 복구하기에서 자세히 다룹니다.

작업 일정을 설정하기 전에 성공하는 경우뿐 아니라 사람이 하는 검토로 대기하는 경우와 가져오기가 중단되는 경우도 한 번씩 연습하세요. 릴리스 단계에서는 우연히 존재하는 파일을 그대로 수락하지 말고, 마지막으로 수락된 상태를 유지하면서 미완료 로캘을 식별해야 합니다.