다국어 프로젝트의 번역 누락 문제를 해결하는 i18n-sync 스킬

다국어 웹 프로젝트를 개발하다 보면 번역 파일 관리가 점점 골칫거리가 됩니다. 한국어로 새 기능을 추가하고, 영어 번역을 잊고, 일본어는 아예 손도 못 대고… 이런 경험 있으시죠? 오늘은 이 문제를 해결하기 위해 i18n-sync라는 Claude Code 스킬을 만든 이야기를 공유합니다.

Table of Contents

TL;DR

문제: 다국어 프로젝트에서 번역 키 누락이 빈번하게 발생
해결: i18n-sync 스킬로 누락 키 자동 감지 및 동기화
결과: “번역 동기화해줘” 한마디로 전체 검사 완료
GitHub: github.com/greeun/i18n-sync

왜 이 스킬이 필요했나?

현재 진행 중인 URL Shortener 프로젝트는 3개 언어(한국어, 영어, 일본어)를 지원합니다. 16개 도메인에 걸쳐 모듈화를 진행하게 되어서 48개의 번역 파일이 있죠.

src/lib/i18n/messages/
├── analytics/     (ko.json, en.json, ja.json)
├── auth/          (ko.json, en.json, ja.json)
├── common/        (ko.json, en.json, ja.json)
├── dashboard/     (ko.json, en.json, ja.json)
... 16개 도메인 × 3개 언어 = 48개 파일

개발하면서 자주 겪는 상황:

한국어(ko.json)에 새 키 추가 → 다른 언어 파일 업데이트 잊음
배포 후 영어 사용자가 “저장” 버튼 발견 → 번역 누락
수동으로 48개 파일 비교 → 시간 낭비 + 휴먼 에러

기존 방식의 문제점

방식	문제점
수동 비교	48개 파일을 일일이 열어서 키 비교 → 비현실적
스크립트 작성	매번 찾아서 실행해야 함, 프로젝트마다 다름
CI/CD 검사	푸시 후에야 발견, 이미 늦음
외부 도구	설정 복잡, 학습 비용, 유료인 경우 많음

i18n-sync 스킬의 해결 방식

Claude Code에서 자연어로 명령하면 자동으로 동작합니다.

명령	동작
“번역 동기화해줘”	전체 도메인 검사 후 누락 키 보고
“analytics 번역 동기화”	특정 도메인만 처리
“일본어 번역 누락 확인”	특정 언어만 검사

동기화 로직

기준 언어(ko.json)를 마스터로 사용하여 다른 언어 파일과 비교합니다.

ko.json (기준)
    │
    ├── 키 A ──→ en.json에 A 없음 → "[TODO: 번역필요] {ko값}" 추가
    │
    ├── 키 B ──→ en.json에 B 있음 → 기존 값 유지
    │
    └── 키 C ──→ en.json에 C 있음 → 기존 값 유지

핵심 원칙:

기준 언어(ko.json)를 마스터로 사용
누락된 키에는 [TODO: 번역필요] 플레이스홀더 추가
기존 번역은 절대 덮어쓰지 않음

실제 동기화 예시

ko.json (새 키 추가됨):

{
  "button": {
    "save": "저장",
    "cancel": "취소",
    "delete": "삭제"  // ← 새로 추가
  }
}

en.json (동기화 전):

{
  "button": {
    "save": "Save",
    "cancel": "Cancel"
    // delete 키 없음!
  }
}

en.json (동기화 후):

{
  "button": {
    "save": "Save",
    "cancel": "Cancel",
    "delete": "[TODO: 번역필요] 삭제"  // ← 자동 추가
  }
}

스킬 생성 과정

skill-wizard를 사용해 6단계로 스킬을 만들었습니다:

Purpose Discovery – 목적 파악
Type Selection – 스킬 유형 선택
Metadata Design – 이름 + 설명
Content Architecture – SKILL.md 구조 설계
Resource Planning – 스크립트/참조 파일
Validation – 검증 및 생성

핵심: 트리거 키워드 설계

스킬의 description은 Claude가 언제 이 스킬을 활성화할지 결정하는 핵심입니다.

description: |
  i18n 번역 파일 동기화 및 검증.
  "번역 동기화", "i18n 검사", "누락 번역", "번역 키 추가",
  "다국어 동기화", "i18n sync", "translation sync",
  "missing translations" 요청에 사용.

한국어와 영어 키워드를 모두 포함해 다양한 표현에 대응합니다.

검증 기능

단순 키 비교를 넘어 다양한 검증을 수행합니다.

검증 항목	설명
JSON 구문 유효성	파싱 가능한 올바른 JSON인지
키 일관성	기준 언어(ko) 대비 모든 키 존재 여부
빈 값 감지	빈 문자열(“”) 값 탐지
TODO 플레이스홀더	[TODO: 번역필요] 잔존 확인
중첩 구조 일치	객체 중첩 구조가 동일한지

출력 예시

=== 번역 동기화 결과 ===

📁 analytics
  ├─ en.json: ✅ 동기화됨 (3개 키 추가)
  └─ ja.json: ⚠️ 5개 누락

📁 common
  ├─ en.json: ✅ 완료
  └─ ja.json: ✅ 완료

📁 settings
  ├─ en.json: ✅ 완료
  └─ ja.json: ⚠️ 2개 누락

────────────────────────────
총계: 16개 도메인
  ✅ 동기화: 3개 키 추가
  ⚠️ TODO 남음: 7개

GitHub 저장소

스킬은 GitHub에 공개되어 있습니다:

저장소: https://github.com/greeun/i18n-sync

설치 방법:

git clone https://github.com/greeun/i18n-sync.git ~/.claude/skills/i18n-sync

마치며

i18n-sync 스킬의 핵심 가치:

자연어 인터페이스: 복잡한 명령어 없이 “번역 동기화해줘”로 끝
비파괴적 동기화: 기존 번역을 덮어쓰지 않음
TODO 트래킹: 미완료 번역을 명확히 표시
프로젝트 독립적: 도메인 기반 i18n 구조라면 어디서든 사용 가능

다국어 프로젝트를 진행 중이라면 한번 사용해 보세요. 번역 누락으로 인한 사용자 경험 저하를 미연에 방지할 수 있습니다.

이 포스트는 Claude Code와 wp-blog-post 스킬을 사용해 작성되었습니다.