---
name: plan-translation-generator
description: 번역 요청 엑셀 파일의 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. **데이터 파악**
   ```python
   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 파일을 생성 또는 갱신한다.
   - 파일 위치: `docs/translation/<엑셀파일명>.md` (확장자 `.xlsx` → `.md` 치환)
     - 예) `smilegate-ax-2026.xlsx` → `docs/translation/smilegate-ax-2026.md`
   - `docs/translation/` 디렉토리가 없으면 자동 생성한다.
   - 파일 내용: 엑셀의 **전체** 번역코드(기존 + 신규)를 아래 형식으로 작성
     - 헤더에서 `KO` 컬럼을 탐지하여 함께 기록한다 (개발 시 번역코드 매칭 참조용)
     ```markdown
     # 번역 코드 참조 — <엑셀파일명>

     > 생성일: YYYY-MM-DD
     > 원본 파일: <엑셀파일 상대경로>

     | 번역코드 | KO | EN |
     |----------|----|----|
     | BRAND-smilegate-ax | 스마일게이트 x AX | Smilegate x AX |
     | NAV-main | 메인 | Main |
     | ... | ... | ... |
     ```
   - 파일이 이미 존재하면 **덮어쓰지 않는다**. 새로 생성된 코드 행만 테이블 하단에 추가(append)한다.
     - 이미 파일에 존재하는 번역코드는 중복 추가하지 않는다.
   - 생성 완료 후 경로와 추가된 행 수를 사용자에게 출력한다.

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

| 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`

```bash
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`
- 사용자가 코드를 직접 수정 요청하면 수정 후 재저장한다.