DS_L10N/README.md

# DS_L10N

던전스토커즈 다국어 번역 통합 툴

## 🚀 빠른 시작

### 1. 라이브러리 설치

```bash
pip install -r requirements.txt
```

### 2. 배치 파일로 실행 (권장)

더블클릭으로 실행:

- `1_미번역추출.bat` - 미번역 항목 추출
- `2_번역검증.bat` - 번역 검증 (신규)
- `3_PO업데이트.bat` - PO 파일 업데이트
- `4_CSV병합.bat` - CSV 병합
- `5_파일정리.bat` - 파일 정리 (신규)
- `전체워크플로우.bat` - 2~5 자동 실행

### 3. 명령어로 실행

```bash
python ds_l10n.py extract    # 미번역 추출
python ds_l10n.py validate   # 번역 검증
python ds_l10n.py update     # PO 업데이트
python ds_l10n.py merge      # CSV 병합
python ds_l10n.py cleanup    # 파일 정리
```

## 📚 상세 가이드

자세한 사용법은 [`사용가이드.md`](사용가이드.md) 참조

## ✨ 주요 개선사항

### 기존 문제점
- ❌ 매번 파일/폴더 선택이 번거로움
- ❌ 번역 오류 사전 검증 불가
- ❌ po_update_from_tsv.py 가끔 오류 발생
- ❌ 결과물 파일이 너무 많이 쌓임

### 개선된 기능
- ✅ **자동 경로 인식** (config.yaml)
- ✅ **번역 검증 기능** (변수, 태그, 줄바꿈 확인)
- ✅ **polib 기반 안정적 업데이트**
- ✅ **컬러 로그** (오류 원인 명확히 표시)
- ✅ **자동 백업** (업데이트 전)
- ✅ **자동 파일 정리** (오래된 파일 보관)

## 📁 프로젝트 구조

```
DS_L10N/
├── ds_l10n.py                    # 메인 CLI 툴
├── config.yaml                   # 설정 파일
├── 번역업데이트.tsv               # 번역 입력 파일
├── requirements.txt              # 필요 라이브러리
├── 사용가이드.md                  # 상세 매뉴얼
│
├── 1_미번역추출.bat               # 배치 스크립트
├── 2_번역검증.bat
├── 3_PO업데이트.bat
├── 4_CSV병합.bat
├── 5_파일정리.bat
├── 전체워크플로우.bat
│
├── lib/                          # 라이브러리 모듈
│   ├── config_loader.py          # 설정 로더
│   ├── logger.py                 # 컬러 로깅
│   ├── validator.py              # 번역 검증
│   ├── po_handler.py             # PO 파일 처리
│   └── file_manager.py           # 파일 관리
│
├── output/                       # 출력 파일 (자동 생성)
├── logs/                         # 로그 파일 (자동 생성)
├── archive/                      # 보관 파일 (자동 생성)
│
├── po_extract_untranslated.py    # 기존 스크립트 (호환성 유지)
├── po_update_from_tsv.py         # 기존 스크립트 (호환성 유지)
└── po_merge_to_csv.py            # 기존 스크립트 (호환성 유지)
```

## 🔧 설정

`config.yaml` 파일에서 경로와 동작 설정:

```yaml
paths:
  unreal_localization: ../WorldStalker/Content/Localization/LocalExport
  output_dir: ./output
  logs_dir: ./logs

validation:
  check_variables: true
  check_rich_text_tags: true
  check_newlines: true

cleanup:
  keep_recent_files: 5
  auto_archive: true
```

## 🆚 기존 스크립트와 비교

| 기능 | 기존 | 신규 |
|------|------|------|
| 미번역 추출 | `po_extract_untranslated.py` | `ds_l10n.py extract` |
| 번역 검증 | ❌ 없음 | `ds_l10n.py validate` ✨ |
| PO 업데이트 | `po_update_from_tsv.py` | `ds_l10n.py update` |
| CSV 병합 | `po_merge_to_csv.py` | `ds_l10n.py merge` |
| 파일 정리 | ❌ 없음 | `ds_l10n.py cleanup` ✨ |
| 경로 관리 | GUI 선택 | config.yaml |
| 로그 | 기본 텍스트 | 컬러 + 아이콘 |
| 백업 | 수동 | 자동 |
| 안정성 | 정규식 파싱 | polib 라이브러리 |

## 📖 워크플로우

### 1단계: 언리얼 에디터
- 현지화 대시보드 → 텍스트 수집
- 텍스트 익스포트

### 2단계: 미번역 추출
```bash
python ds_l10n.py extract
```

### 3단계: 외부 번역
- Google AI Studio 번역 앱 사용
- 결과를 `번역업데이트.tsv`에 저장

### 4단계: 번역 검증
```bash
python ds_l10n.py validate
```

### 5단계: PO 업데이트
```bash
python ds_l10n.py update
```

### 6단계: 언리얼 에디터
- PO 파일 임포트
- 텍스트 컴파일

### 7단계: 사후 관리
```bash
python ds_l10n.py merge    # CSV로 백업
python ds_l10n.py cleanup  # 파일 정리
```

또는 **4~7단계 자동 실행**:
```bash
전체워크플로우.bat
```

## 💡 팁

### GUI 모드 사용
```bash
python ds_l10n.py extract --gui
```

### 시뮬레이션 모드
```bash
python ds_l10n.py update --dry-run
```

### 특정 파일 검증
```bash
python ds_l10n.py validate output/untranslated_20251029_123456.tsv
```

## 🐛 문제 해결

### "모듈을 찾을 수 없습니다"
```bash
pip install -r requirements.txt
```

### "PO 파일을 찾을 수 없습니다"
- `config.yaml`의 경로 확인
- 언리얼에서 텍스트 익스포트 완료 확인

### 업데이트 실패
- `logs/` 폴더의 최신 로그 파일 확인
- 실패 원인과 msgctxt 확인

## 📄 라이선스

Copyright © 2025 OneUniverse. All rights reserved.

---

**버전**: 2.0
**최종 수정**: 2025-01-29
**작성자**: Claude Code + DS_L10N Team