DS_L10N/사용가이드.md

# DS_L10N 사용 가이드

던전 스토커즈 현지화 통합 툴

## 목차

1. [설치](#설치)
2. [설정](#설정)
3. [기본 사용법](#기본-사용법)
4. [개선된 워크플로우](#개선된-워크플로우)
5. [명령어 상세](#명령어-상세)
6. [문제 해결](#문제-해결)

---

## 설치

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

```bash
cd D:\Work\WorldStalker\DS_L10N
pip install -r requirements.txt
```

설치되는 라이브러리:
- `polib`: PO 파일 안정적 처리
- `PyYAML`: 설정 파일 관리
- `pandas`: 데이터 처리 (기존 스크립트 호환)

### 2. 설정 파일 확인

`config.yaml` 파일에서 경로와 설정 확인:

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

모든 경로는 상대 경로로 설정되어 있으며, `DS_L10N` 폴더 기준입니다.

---

## 설정

### config.yaml 주요 설정

```yaml
# 검증 설정
validation:
  check_variables: true          # {Value} 같은 변수 일치 확인
  check_rich_text_tags: true     # <Red></> 태그 일치 확인
  check_newlines: true           # \r\n 줄바꿈 일치 확인
  stop_on_validation_error: false  # 검증 실패 시 중단 여부

# 자동 정리
cleanup:
  keep_recent_files: 5           # 최근 N개 파일만 유지
  auto_archive: true             # 오래된 파일 자동 보관
```

필요에 따라 `config.yaml`을 수정하여 사용하세요.

---

## 기본 사용법

### 명령어 구조

```bash
python ds_l10n.py <명령어> [옵션]
```

### 주요 명령어

| 명령어 | 설명 | 기존 스크립트 대체 |
|--------|------|-------------------|
| `extract` | 미번역 항목 추출 | `po_extract_untranslated.py` |
| `validate` | 번역 검증 (신규) | - |
| `update` | PO 파일 업데이트 | `po_update_from_tsv.py` |
| `merge` | CSV 병합 | `po_merge_to_csv.py` |
| `cleanup` | 파일 정리 (신규) | - |

### 도움말 보기

```bash
python ds_l10n.py --help
python ds_l10n.py extract --help
```

---

## 개선된 워크플로우

### Before (기존 방식)

1. 언리얼 에디터: 텍스트 수집 → 익스포트
2. `po_extract_untranslated.py` 실행 → 파일 선택 (GUI)
3. 외부 번역 수행 (Google AI Studio 앱)
4. `번역업데이트.tsv`에 결과 저장
5. `po_update_from_tsv.py` 실행 → 파일/폴더 선택 (GUI)
6. 언리얼 에디터: PO 임포트 → 컴파일
7. `po_merge_to_csv.py` 실행 → 폴더 선택 (GUI)

**문제점**: 매번 파일/폴더 선택, 검증 부재, 오류 발생 시 원인 파악 어려움

### After (개선된 방식)

1. 언리얼 에디터: 텍스트 수집 → 익스포트
2. **`python ds_l10n.py extract`** - 미번역 추출
3. 외부 번역 수행
4. **`python ds_l10n.py validate`** - 번역 검증 ✨ 신규
5. **`python ds_l10n.py update`** - PO 업데이트
6. 언리얼 에디터: PO 임포트 → 컴파일
7. **`python ds_l10n.py merge`** - CSV 병합
8. **`python ds_l10n.py cleanup`** - 파일 정리 ✨ 신규

**개선점**:
- ✅ 경로 자동 인식 (config.yaml)
- ✅ 번역 검증 기능 추가
- ✅ 컬러 로그로 가독성 향상
- ✅ 자동 백업 생성
- ✅ 실패 원인 명확히 출력
- ✅ 오래된 파일 자동 정리

---

## 명령어 상세

### 1. extract - 미번역 항목 추출

```bash
# CLI 모드 (자동 경로)
python ds_l10n.py extract

# GUI 모드 (파일 선택)
python ds_l10n.py extract --gui
```

**출력**:
- `output/untranslated_YYYYMMDD_HHMMSS.tsv`
- msgctxt, SourceLocation, msgid 컬럼

**사용 시기**: 언리얼에서 텍스트 익스포트 후

---

### 2. validate - 번역 검증 ✨ 신규

```bash
# 기본 입력 파일 (번역업데이트.tsv)
python ds_l10n.py validate

# 특정 파일 지정
python ds_l10n.py validate output/untranslated_20251029_123456.tsv
```

**검증 항목**:
- ❌ **변수 누락**: `{Value}`, `{Count}` 등이 번역문에 없음
- ❌ **태그 불일치**: `<Red></>` 개수가 원문과 다름
- ⚠️ **줄바꿈 불일치**: `\r\n` 개수가 원문과 다름
- ℹ️ **길이 초과**: 번역문이 200자 초과 (설정 가능)

**출력 예시**:
```
🔍 번역 검증 결과
================================================================================

❌ 오류 (3건):
  - en: DT_Skill.Fireball.Desc
    분류: 변수 누락
    문제: 누락된 변수: {Damage}
    원문: {Damage} 피해를 입힙니다
    번역: Deals damage

⚠️  경고 (2건):
  - ja: UI.Combat.AttackPower
    분류: 태그 불일치
    ...

================================================================================
📊 통계:
  - total: 241
  - errors: 3
  - warnings: 2
  - passed: 238

✅ 검증 완료: 238건 통과 (경고 2건)
```

**사용 시기**: 외부 번역 완료 후, PO 업데이트 전

---

### 3. update - PO 파일 업데이트

```bash
# 기본 입력 파일 (번역업데이트.tsv)
python ds_l10n.py update

# 특정 파일 지정
python ds_l10n.py update translations/my_translations.tsv

# 시뮬레이션 모드 (실제 수정 안함)
python ds_l10n.py update --dry-run
```

**개선 사항**:
- ✅ **polib 사용**: 정규식 대신 안정적인 라이브러리
- ✅ **자동 백업**: 업데이트 전 `.backup_YYYYMMDD_HHMMSS.po` 생성
- ✅ **상세 로그**: 업데이트/스킵/실패 건수와 이유 출력
- ✅ **msgctxt 매칭**: 언리얼 해시 키로 정확히 매칭

**출력 예시**:
```
언어 처리 중: en
  백업 생성: LocalExport.backup_20251029_123456.po
  ✅ en: 234건 업데이트
  ⏭️  en: 5건 스킵 (변경사항 없음)

언어 처리 중: ja
  백업 생성: LocalExport.backup_20251029_123456.po
  ✅ ja: 230건 업데이트
  ❌ ja: 2건 실패
     - ,ABC123...: PO 파일에서 msgctxt를 찾을 수 없음

📊 전체 업데이트 결과:
  - 업데이트됨: 464
  - 스킵됨: 5
  - 실패: 2
  - 처리 언어: 2
```

**사용 시기**: 번역 검증 완료 후

---

### 4. merge - CSV 병합

```bash
python ds_l10n.py merge
```

**출력**:
- `LocalExport/merged_po_entries_YYYYMMDD_HHMMSS.csv`
- 모든 언어의 번역을 하나의 CSV로 통합

**사용 시기**: PO 임포트/컴파일 후, 엑셀에서 관리할 때

---

### 5. cleanup - 파일 정리 ✨ 신규

```bash
python ds_l10n.py cleanup
```

**정리 항목**:
- 📦 오래된 CSV 파일 → `archive/YYYYMM/` 폴더로 이동
- 📦 오래된 미번역 TSV 파일 보관
- 🗑️ 7일 이상 된 백업 파일 삭제
- 🗑️ 30일 이상 된 로그 파일 삭제

**설정** (`config.yaml`):
```yaml
cleanup:
  keep_recent_files: 5           # 최근 5개만 유지
  keep_backups_days: 7           # 백업 보관 기간
  delete_old_logs_days: 30       # 로그 보관 기간
```

**사용 시기**: 파일이 너무 많이 쌓였을 때

---

## 문제 해결

### Q1. 명령어 실행 시 "모듈을 찾을 수 없습니다" 오류

```bash
# 필요 라이브러리 재설치
pip install -r requirements.txt
```

### Q2. "PO 파일을 찾을 수 없습니다" 오류

`config.yaml`의 경로 설정 확인:

```yaml
paths:
  unreal_localization: ../WorldStalker/Content/Localization/LocalExport
```

상대 경로가 올바른지 확인하세요.

### Q3. 업데이트 후에도 언리얼에서 번역이 안 보임

1. 언리얼 에디터에서 **PO 임포트** 실행
2. **텍스트 컴파일** 실행
3. 에디터 재시작

### Q4. 검증에서 많은 오류가 나옴

**변수 누락 오류**:
- 번역문에 `{Value}` 같은 변수를 포함시키지 않음
- 원문의 변수를 그대로 번역문에 복사

**태그 불일치 오류**:
- `<Red>강력한</>`처럼 여는 태그와 닫는 태그 개수 일치시키기

**줄바꿈 불일치 경고**:
- `\r\n` 위치를 원문과 동일하게 유지 (UI 레이아웃)

### Q5. 기존 GUI 스크립트를 계속 사용하고 싶음

기존 스크립트 파일은 그대로 유지됩니다:
- `po_extract_untranslated.py`
- `po_update_from_tsv.py`
- `po_merge_to_csv.py`

또는 `--gui` 옵션 사용:

```bash
python ds_l10n.py extract --gui
```

### Q6. 로그 파일이 너무 많이 쌓임

```bash
python ds_l10n.py cleanup
```

또는 `config.yaml`에서 자동 삭제 기간 조정:

```yaml
cleanup:
  delete_old_logs_days: 7  # 7일로 단축
```

---

## 고급 사용법

### Dry-run 모드로 안전하게 테스트

```bash
# 실제 파일 수정 없이 시뮬레이션
python ds_l10n.py update --dry-run
```

### 커스텀 설정 파일 사용

```bash
python ds_l10n.py --config my_config.yaml extract
```

### 배치 스크립트로 자동화

`update_translations.bat`:

```batch
@echo off
cd /d D:\Work\WorldStalker\DS_L10N

echo [1/4] 번역 검증 중...
python ds_l10n.py validate
if errorlevel 1 (
    echo 검증 실패! 번역을 확인하세요.
    pause
    exit /b 1
)

echo [2/4] PO 파일 업데이트 중...
python ds_l10n.py update
if errorlevel 1 (
    echo 업데이트 실패!
    pause
    exit /b 1
)

echo [3/4] CSV 병합 중...
python ds_l10n.py merge

echo [4/4] 파일 정리 중...
python ds_l10n.py cleanup

echo.
echo ========================================
echo 모든 작업 완료!
echo ========================================
pause
```

---

## 로그 파일

모든 작업의 상세 로그는 `logs/` 폴더에 저장됩니다:

- `logs/workflow_YYYYMMDD_HHMMSS.log`

문제 발생 시 로그 파일을 확인하세요.

---

## 지원

문제가 발생하면:
1. 로그 파일 확인 (`logs/` 폴더)
2. `config.yaml` 설정 확인
3. 이 가이드의 "문제 해결" 섹션 참조

---

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