game-fe-agent/skills/translation-keys/SKILL.md

name, description

name	description
translation-keys	번역 요청 엑셀 파일의 EN 셀을 기반으로 '번역코드' 컬럼에 함축적인 코드를 자동 생성합니다. 사용자가 "번역코드 만들어줘", "translation key 생성", "번역 키 추출" 등을 요청하면 트리거됩니다.

번역 코드 생성 (Translation Key Generator)

이 skill 은 번역 요청 엑셀 파일의 EN 컬럼 텍스트를 분석하여 번역코드 컬럼에 함축적이고 일관된 코드를 자동으로 작성합니다.

코드 생성 규칙

규칙	설명	예시
단어 수	3단어 이하	NAV-main ✅ / NAV-main-section-title ❌
구분자	단어 사이 - (하이픈)	EVENT-title
첫 단어	카테고리를 나타내는 대문자	HERO, NAV, TOAST
함축성	텍스트의 핵심 의미를 최대한 압축	HERO-czn-title (CHAOS ZERO NIGHTMARE → czn)

카테고리 가이드

카테고리	사용 상황	예시
BRAND	브랜드명, 서비스 이름	BRAND-smilegate-ax
NAV	내비게이션, 메뉴 항목	NAV-main, NAV-location
EVENT	이벤트 정보 (제목/날짜/장소)	EVENT-title, EVENT-date, EVENT-venue
HERO	히어로 배너 텍스트	HERO-miresi-title
SECTION	섹션 헤더/소제목	SECTION-intro
BTN	버튼 레이블	BTN-register, BTN-more
TOAST	토스트/알림 메시지	TOAST-link-copied, TOAST-paste-hint
LABEL	폼 레이블, 태그	LABEL-date, LABEL-venue
MSG	일반 안내 메시지	MSG-loading, MSG-empty
MODAL	모달/팝업 내 텍스트	MODAL-confirm-title

작업 순서

1. 파일 확인

   • 사용자가 엑셀 파일 경로를 제공했는지 확인
   • 미제공 시: 파일 경로를 먼저 요청

2. 데이터 파악

   import openpyxl
   wb = openpyxl.load_workbook('파일경로.xlsx')
   ws = wb.active
   # 헤더 행에서 '번역코드', 'EN' 컬럼 인덱스 찾기
   

   • 1행(헤더)에서 번역코드 컬럼과 EN 컬럼 위치를 동적으로 탐지
   • 데이터가 있는 행(EN 값이 None이 아닌 행)만 처리

3. 코드 생성

   • EN 텍스트를 분석해 카테고리와 핵심 키워드 추출
   • 이미 번역코드 값이 있는 행은 덮어쓰지 않음 (사용자 확인 후 진행)
   • 생성한 코드 목록을 사용자에게 미리 보여주고 승인 요청

4. 중복 코드 검사 ← 저장 전 반드시 수행

   • 기존에 이미 작성된 코드 + 이번에 새로 생성한 코드를 전체 합산하여 중복 여부 검사
   • 중복이 발견되면 저장을 중단하고 사용자에게 아래 형식으로 보고:

     ⚠️ 중복 코드 발견
     - HERO-title: 3행, 12행 (2건)
     - EVENT-date: 8행, 15행 (2건)
     

   • 중복 해소 방법을 제안하고 사용자 승인 후 재생성
   • 중복이 없으면 "중복 없음 확인" 메시지 출력 후 저장 진행

5. 엑셀 저장

   • 사용자 승인 후 번역코드 컬럼에 값 기입 및 저장
   • 저장 완료 메시지와 변경 내역 요약 출력

6. 참조 MD 파일 생성

   • 엑셀 저장 완료 후 로컬 참조용 MD 파일을 생성 또는 갱신한다.
   • 파일 위치: doc/translation/<엑셀파일명>.md (확장자 .xlsx → .md 치환)
     • 예) smilegate-ax-2026.xlsx → doc/translation/smilegate-ax-2026.md
   • doc/translation/ 디렉토리가 없으면 자동 생성한다.
   • 파일 내용: 엑셀의 전체 번역코드(기존 + 신규)를 아래 형식으로 작성

     # 번역 코드 참조 — <엑셀파일명>
     
     > 생성일: YYYY-MM-DD
     > 원본 파일: <엑셀파일 상대경로>
     
     | 번역코드 | EN |
     |----------|----|
     | BRAND-smilegate-ax | Smilegate x AX |
     | NAV-main | Main |
     | ... | ... |
     

   • 파일이 이미 존재하면 덮어쓴다 (엑셀이 단일 소스 오브 트루스).
   • 생성 완료 후 경로를 사용자에게 출력한다.

코드 작성 예시 (실제 케이스)

EN 텍스트	생성 코드	근거
Smilegate x AX	BRAND-smilegate-ax	브랜드명 전체
Main	NAV-main	내비 메인 항목
Program & Events	NAV-program-events	내비 항목, 특수문자 제거
Smilegate x Anime Expo	EVENT-title	이벤트 대표 제목
07/02/2026 (THU)~ 07/05/2026 (SUN)	EVENT-date	날짜 데이터
Los Angeles Convention Center	EVENT-venue	행사 장소
The link has been copied.	TOAST-link-copied	토스트 알림, 링크 복사 완료
You may now paste it elsewhere.	TOAST-paste-hint	토스트 알림, 붙여넣기 안내
MIRESI ARRIVES AT <br> ANIME EXPO!	HERO-miresi-title	히어로 배너, 캐릭터명
CHAOS ZERO NIGHTMARE ARRIVES AT <br> ANIME EXPO!	HERO-czn-title	히어로 배너, 약어 처리

처리 스크립트

스크립트 파일: scripts/generate_translation_keys.py

python scripts/generate_translation_keys.py <엑셀파일경로>

스크립트 주요 함수:

함수	역할
load_existing_codes(ws, code_col)	기존 번역 코드를 {행번호: 코드} 로 수집
check_duplicates(existing, new)	기존+신규 코드 합산 중복 검사, 결과 반환
run(filepath, new_codes)	중복 검사 → 저장 실행 (중복 시 중단)

new_codes 딕셔너리는 Claude AI가 EN 텍스트를 분석하여 직접 채웁니다. 스크립트는 중복 검사와 저장만 담당합니다.

주의사항

• 행 순서 고정: 엑셀의 기존 행 순서를 절대 변경하지 않는다. 코드는 원래 행 위치에 그대로 기입한다.
• 이미지 셀 보존: 셀에 이미지가 삽입된 경우 해당 셀 및 시트의 이미지를 덮어쓰거나 삭제하지 않는다. openpyxl.load_workbook(path, keep_vba=True) 옵션을 사용하고, 이미지 객체(ws._images)를 건드리지 않는다.
• 기존 코드 보존: 이미 번역코드 값이 있는 셀은 덮어쓰지 않는다.
• 중복 코드 방지: 동일한 코드가 두 행에 생기지 않도록 확인한다.
• HTML 태그 무시: <br>, <b> 등 마크업 태그는 의미 분석에서 제외한다.
• 날짜/숫자 데이터: 날짜 형식 셀은 EVENT-date, LABEL-date 등 의미 기반으로 처리한다.
• 약어 처리: 3단어 초과 시 캐릭터명·고유명사를 약어(초성/이니셜)로 압축한다.
  • 예) CHAOS ZERO NIGHTMARE → czn
• 사용자가 코드를 직접 수정 요청하면 수정 후 재저장한다.