언어팩 MR 자동 생성 + 충돌 해결을 위한 GitLab 파이프라인 구현

프로젝트내 다국어(i18n) 처리 과정에서 매번 반복되는 작업과 불편함이 있었습니다. 이번 글에서는 기존 방식(AS IS)부터 개선 과정(TO BE), 그리고 최종적으로 어떻게 구조를 확정했는지까지 공유해 보려고 한다.

AS IS

현재 프로젝트 내 다국어 처리 과정은 다음과 같았다.
  1. 번역 시트(Google Sheets)에서 문구를 각 언어로 번역
  1. 개발자가 로컬에서 스크립트를 실행해 시트 내용으로 언어별 JSON 파일을 생성·갱신
  1. 갱신된 JSON 파일을 작업 중인 브랜치에 함께 커밋해 PR 생성
  1. JSON 파일은 빌드 시 번들에 포함되어, 배포 후 화면에 언어별 문구로 노출
겉보기에는 큰 문제가 없어 보이지만 두 가지 불편함이 있다
  • 코드 충돌: 스크립트는 시트 전체를 기준으로 JSON 파일을 통째로 덮어쓴다. 여러 브랜치에서 각자 다른 시점에 스크립트를 실행하면 같은 파일이 서로 다르게 바뀌어, 머지할 때마다 언어 파일에서 충돌이 발생할 수 있다
  • 반복적인 수작업: 문구만 바뀌어도 누군가 스크립트를 실행하고, 커밋하고, MR을 만들어야 한다. 번역이 반영되는 시점도 그 작업을 누가 언제 하느냐에 달려 있다

TO BE

이러한 불편을 해소하기 위해, 이번에 CI 기반 자동화를 도입하게 되었다.
우선, 작업자의 개입 없이 다국어 파일이 자동으로 업데이트되는 방향을 목표로 삼아 스크립트 초안을 작성하고 PR을 생성다.
처음 구상한 흐름은 다음과 같다.
  • prebuild 단계에서 스크립트를 실행해 다국어 JSON 파일을 자동으로 업데이트 한다
    • 단, 로컬에서 생성된 JSON 파일은 commit 되지 않도록 .gitignore에 추가한다
  • 이후 빌드 → 배포 를 진행한다
이 접근 방식은 프로젝트내 JSON 파일을 따로 관리할 필요가 없다는 장점이 있었지만, 여러 팀원들과 논의하면서 몇 가지 한계를 확인했다.
  1. 배포된 문구를 추적할 수 없다
      2. 파일이 빌드 중에만 생성되고 저장소에는 남지 않는다. 그래서 어떤 문구가 언제 바뀌어 배포됐는지 이력을 볼 수 없고, 머지 전에 변경 내용을 검토할 수도 없다.
  1. 환경마다 문구가 달라질 수 있다.
      2. dev, staging, prod는 각자 다른 시점에 빌드된다. 빌드할 때마다 그 시점의 시트를 가져오므로, staging에서 확인한 문구와 prod에 나간 문구가 같다는 보장이 없다.
즉, 단순히 자동화하는 것을 넘어 버전 관리와 환경 간 일관성까지 고려해야 한다는 결론에 이르렀다.

최종 개선

논의 끝에 다음과 같은 구조로 정리했다. 최선의 방법이라고 단정할 수는 없지만, 현재 번역 운영 방식과 배포 흐름을 고려했을 때 가장 현실적인 절충안이라고 판단했다.
  • 정기 자동화 평일 오전 10시 에 CI Job이 실행된다. 시트에 변경이 있으면 chore/i18n 브랜치로 PR이 자동 생성·최신화 한다. 단, 필요하다면 Pipeline 수동 실행을 통해 진행도 가능하다.
    • 번역 시트 업데이트 주기가 불안정하기에 우선 하루에 한 번으로 설정했다.
  • 기본 동작 자동 생성된 MR이 머지되어야 번역 변경이 저장소에 들어오고, 이후 dev → staging → master 배포를 거쳐 실제 서비스에 반영된다. 변경 이력이 MR로 남고 환경마다 같은 문구가 순서대로 반영되므로, 앞서 짚은 버전 관리와 환경 간 일관성 문제를 해결할 수 있다.
  • 즉시 반영이 필요한 경우 (긴급 케이스)
      • 배포 주기를 기다릴 수 없는 경우에는 대상 브랜치에서 Run pipeline → Variables → RUN_LANG_UPDATE=1 로 빌드를 실행한다. 그러면 빌드 직전에 시트의 최신 문구를 받아 해당 환경에만 반영된다. 다만 이 방식은 임시 반영이다.
    • 저장소에는 남지 않으므로, 다음 정규 배포 때 저장소에 있는 문구로 되돌아간다. 같은 변경이 담긴 i18n MR도 함께 머지·배포해야 한다.
    • 시트 전체를 그 시점 기준으로 반영하므로, 급한 문구 외에 아직 검토되지 않은 다른 변경도 같이 나갈 수 있다.
👉 평소에는 자동화된 PR과 머지 과정을 통해 이력과 일관성을 지키고, 필요할 때는 수동 변수를 활용해 빠르게 대응할 수 있는 구조다. 임시 반영은 앞서 짚은 한계를 감수하는 선택이므로 예외로만 사용한다.
notion image

개선 효과

notion image
이번 개선을 통해 얻은 효과는 다음과 같다.
  • 반복 작업 제거: 문구를 반영하려고 스크립트를 실행하고 커밋하고 MR을 만들던 수작업이 사라졌다. 도입 이후 언어 파일 변경은 모두 자동 MR로만 들어온다.
  • 코드 충돌 최소화: 언어 파일을 바꾸는 주체가 chore/i18n 브랜치 하나로 모였다. 기능 브랜치마다 언어 파일을 따로 덮어쓰던 구조가 사라져 언어 파일 충돌이 거의 발생하지 않는다.
  • 변경 이력 추적: 번역 변경이 MR 단위로 남아 언제 어떤 문구가 바뀌었는지 확인할 수 있고, 머지 전에 변경 내용을 검토할 수 있다.
  • 환경별 일관성 확보: 번역도 코드와 같은 dev → staging → prod 흐름을 탄다. staging에서 확인한 문구가 그대로 prod에 반영된다.
  • 유연한 대응 가능: 기본 흐름은 유지하면서, 급할 때는 수동 변수로 특정 환경에 임시 반영할 수 있다.
무엇보다 팀원들이 만족해하는 모습을 보며, 자동화는 단순한 편의가 아니라 팀 전체의 생산성을 높이는 핵심이라는 점을 실감했다.

© 2026 dan.dev.log, All right reserved.

Built with NextJS