DS_L10N/README.md

# DS_L10N

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

---

## 📑 목차

1. [빠른 시작](#-빠른-시작)
2. [주요 기능](#-주요-기능)
3. [설치 및 설정](#-설치-및-설정)
4. [워크플로우](#-워크플로우)
5. [명령어 상세](#-명령어-상세)
6. [문제 해결](#-문제-해결)
7. [프로젝트 구조](#-프로젝트-구조)

---

## 🚀 빠른 시작

### 1. 라이브러리 설치 (최초 1회)

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

**설치되는 라이브러리**:
- `polib`: PO 파일 안정적 처리
- `PyYAML`: 설정 파일 관리
- `pandas`: 데이터 처리

### 2. 명령어 실행

```bash
python ds_l10n.py extract                    # 미번역 추출 (en만)
python ds_l10n.py extract --all-languages    # 미번역 추출 (모든 언어)
python ds_l10n.py extract --include-fuzzy    # fuzzy 항목 포함
python ds_l10n.py validate                   # 번역 검증
python ds_l10n.py update                     # PO 업데이트
python ds_l10n.py merge                      # CSV 병합
python ds_l10n.py cleanup                    # 파일 정리
```

### 3. 도움말

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

---

## ✨ 주요 기능

- ✅ **자동 경로 인식** (`config.yaml` 기반)
- ✅ **번역 검증** (변수, 태그, 줄바꿈 확인)
- ✅ **안정적 업데이트** (polib 라이브러리 사용)
- ✅ **컬러 로그** (오류 원인 명확히 표시)
- ✅ **자동 백업** (업데이트 전 자동 생성)
- ✅ **자동 파일 정리** (오래된 파일 보관)
- ✅ **원본 언어(ko) 업데이트 지원**
- ✅ **줄바꿈 이스케이프 자동 처리**
- ✅ **스마트 미번역 감지** (msgstr 빈 값, ko 원본 변경 감지)
- ✅ **fuzzy 항목 추출** (리뷰 필요한 번역 감지)
- ✅ **유연한 언어 검사** (en만 또는 전체 언어)

---

## 🔧 설치 및 설정

### config.yaml 설정

`config.yaml` 파일에서 경로와 동작 설정 (상대 경로 사용):

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

languages:
  source: ko  # 원본 언어
  targets:    # 번역 대상 언어 (17개)
    - en
    - ja
    - zh-Hans
    - zh-Hant
    # ... 기타 언어

extract:
  check_all_languages: false  # 모든 언어 검사 (기본: en만)
  include_fuzzy: true         # fuzzy 항목 포함 (리뷰 필요)
  separate_files: true        # 언어별 개별 파일 생성

validation:
  check_variables: true           # {Value} 변수 확인
  check_rich_text_tags: true      # <Red></> 태그 확인
  check_newlines: true            # \r\n 줄바꿈 확인
  check_empty_translations: true  # 빈 번역 확인

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

backup:
  auto_backup_before_update: true # 업데이트 전 자동 백업
  keep_backups_days: 7            # 백업 보관 기간
```

### 필요한 디렉토리 (자동 생성)

스크립트 실행 시 자동으로 생성됩니다:
- `output/` - 미번역 항목 TSV 파일
- `logs/` - 작업 로그 파일
- `archive/` - 오래된 파일 보관

---

## 📖 워크플로우

```
1️⃣ 언리얼 에디터
   └─ 현지화 대시보드 → 텍스트 수집 → 텍스트 익스포트

2️⃣ 미번역 추출
   python ds_l10n.py extract              # en만 검사 (기본)
   python ds_l10n.py extract --all-languages  # 모든 언어 검사
   └─ output/untranslated_YYYYMMDD_HHMMSS.tsv 생성

3️⃣ 외부 번역 수행
   └─ Google AI Studio 번역 앱 사용
   └─ 번역업데이트.tsv에 결과 저장

4️⃣ 번역 검증
   python ds_l10n.py validate
   └─ 변수, 태그, 줄바꿈 오류 확인

5️⃣ PO 파일 업데이트
   python ds_l10n.py update
   └─ 자동 백업 + 모든 언어 PO 파일 업데이트 (ko 포함)

6️⃣ 언리얼 에디터
   └─ 현지화 대시보드 → PO 파일 임포트 → 텍스트 컴파일

7️⃣ 사후 관리
   python ds_l10n.py merge    # CSV로 백업
   python ds_l10n.py cleanup  # 파일 정리
```

### 자동화 옵션

4~7단계 자동 실행:

```bash
python ds_l10n.py validate && python ds_l10n.py update && python ds_l10n.py merge && python ds_l10n.py cleanup
```

---

## 📝 명령어 상세

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

```bash
# 기본 사용 (en만 검사)
python ds_l10n.py extract

# 모든 언어 검사
python ds_l10n.py extract --all-languages

# fuzzy 항목 포함 (원본 변경으로 리뷰 필요한 항목)
python ds_l10n.py extract --include-fuzzy

# 옵션 조합
python ds_l10n.py extract --all-languages --include-fuzzy

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

**기능**:
- **기본 동작**: en PO 파일에서 msgstr이 비어있는 항목 추출
- **--all-languages**: 모든 대상 언어(17개) 검사
- **--include-fuzzy**: fuzzy 플래그 항목도 추출 (ko 원본 변경 감지)
- msgstr이 비어있는 항목을 정확히 감지
- TSV 형식으로 저장 (msgctxt, SourceLocation, msgid)

**출력**:
- 기본: `output/untranslated_YYYYMMDD_HHMMSS.tsv`
- 전체 언어: `output/untranslated_{lang}_YYYYMMDD_HHMMSS.tsv` (언어별 17개 파일)

**사용 시나리오**:
1. **일반적인 경우**: `python ds_l10n.py extract` (en만 빠르게 검사)
2. **ko 원본이 변경된 경우**: `python ds_l10n.py extract --include-fuzzy`
3. **전체 언어 점검**: `python ds_l10n.py extract --all-languages`

---

### 2. validate - 번역 검증

```bash
python ds_l10n.py validate [TSV파일]
```

**검증 항목**:
- ❌ **오류 (ERROR)**: 변수 누락/추가, 태그 불일치
- ⚠️ **경고 (WARNING)**: 줄바꿈 불일치 (UI 레이아웃 영향)
- ℹ️ **정보 (INFO)**: 길이 초과

**특징**:
- ko는 원본 언어로 검증에서 자동 제외
- msgid 컬럼이 없으면 ko 컬럼을 원본으로 사용
- 오류 발견 시 상세한 원인과 위치 표시

---

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

```bash
python ds_l10n.py update [TSV파일]
python ds_l10n.py update --dry-run  # 시뮬레이션 모드
```

**기능**:
- TSV 파일의 번역을 모든 언어의 PO 파일에 반영
- ko(원본 언어)도 함께 업데이트
- TSV의 `\r\n` 이스케이프 시퀀스를 자동으로 PO 형식으로 변환
- 업데이트 전 자동 백업 생성

**중요**: 원본 텍스트 수정 시 TSV의 ko 컬럼에 새 원본을 입력하면 자동으로 반영됩니다.

---

### 4. merge - CSV 병합

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

**기능**:
- 모든 언어의 PO 파일을 하나의 CSV로 병합
- Excel에서 편집 가능한 형식으로 저장

**출력**: `LocalExport/merged_po_entries_YYYYMMDD_HHMMSS.csv`

**CSV 구조**:
```
msgctxt | SourceLocation | ko | en | ja | zh-Hans | ...
```

**참고**: ko(원본 언어)가 en 앞에 위치하여 원본 확인이 용이합니다.

---

### 5. cleanup - 파일 정리

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

**정리 항목**:
- 📦 오래된 CSV/TSV 파일 → `archive/YYYYMM/` 폴더로 이동
- 🗑️ 7일 이상 된 백업 파일 삭제
- 🗑️ 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}` 같은 변수를 번역문에 그대로 복사

**태그 불일치 오류**: 모든 `<TagName>`에 대응하는 `</>`가 있는지 확인

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

### Q5. 원본 언어(ko)를 수정하고 싶음

`번역업데이트.tsv`의 ko 컬럼에 수정된 원본을 입력하고:

```bash
python ds_l10n.py update  # ko 포함 모든 언어 업데이트
```

### Q6. 코드 수정 후 반영이 안 됨

Python 캐시 문제일 수 있습니다:

```bash
# 방법 1: 캐시 삭제
find . -type d -name "__pycache__" -exec rm -rf {} +

# 방법 2: 캐시 무시 옵션
python -B ds_l10n.py merge
```

### Q7. Unicode/이모지 표시 오류

Windows 콘솔에서 이모지가 깨지는 경우:
- 로그 파일(`logs/`)에서는 정상적으로 표시됨
- Windows Terminal 사용 권장

### Q8. 미번역이 있는데 추출되지 않음

**상황**: PO 파일에 msgstr이 비어있는데 extract 명령으로 감지되지 않음

**원인**: 기본적으로 en만 검사하기 때문

**해결**:
```bash
# 모든 언어 검사
python ds_l10n.py extract --all-languages
```

### Q9. ko 원본이 변경되었는데 번역이 그대로임

**상황**: ko 원본 텍스트가 수정되었지만 번역문이 예전 원본 기준임

**원인**: fuzzy 플래그가 있는 항목은 기본 extract에서 제외됨

**해결**:
```bash
# fuzzy 항목도 추출 (리뷰 필요한 번역)
python ds_l10n.py extract --include-fuzzy

# 또는 전체 언어 + fuzzy
python ds_l10n.py extract --all-languages --include-fuzzy
```

---

## 📁 프로젝트 구조

```
DS_L10N/
├── ds_l10n.py                    # 메인 CLI 툴
├── config.yaml                   # 설정 파일
├── 번역업데이트.tsv               # 번역 입력 파일
├── requirements.txt              # 필요 라이브러리
├── README.md                     # 이 문서
│
├── lib/                          # 라이브러리 모듈
│   ├── config_loader.py          # 설정 로더
│   ├── logger.py                 # 컬러 로깅
│   ├── validator.py              # 번역 검증
│   ├── po_handler.py             # PO 파일 처리
│   └── file_manager.py           # 파일 관리
│
├── output/                       # 출력 파일 (자동 생성)
├── logs/                         # 로그 파일 (자동 생성)
├── archive/                      # 보관 파일 (자동 생성)
│
├── DS_Context.txt                # 번역 문맥 가이드
├── DS_Terminology_DB.txt         # 용어 데이터베이스
└── DS_Terminology_Guide.txt      # 용어집 가이드
```

---

## 💡 고급 사용법

### Dry-run 모드

```bash
python ds_l10n.py update --dry-run
```

실행 결과를 미리 확인 후 실제 업데이트 진행

### 커스텀 설정 파일

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

여러 프로젝트 관리 시 유용

### Jenkins/CI 통합

```bash
cd DS_L10N
python ds_l10n.py validate || exit 1
python ds_l10n.py update || exit 1
```

---

## 🔗 관련 문서

- **번역 문맥 가이드**: `DS_Context.txt`
- **용어 데이터베이스**: `DS_Terminology_DB.txt`
- **용어집 가이드**: `DS_Terminology_Guide.txt`

---

## 🆕 버전 히스토리

### v2.0.2 (2025-10-30)
- ✨ 미번역 추출 기능 대폭 개선
  - 기본적으로 en만 검사 (빠른 실행)
  - `--all-languages` 옵션으로 전체 언어 검사
  - `--include-fuzzy` 옵션으로 리뷰 필요 항목 추출
  - msgstr 빈 값 정확히 감지 (ko 원본 변경 케이스)
- ✨ config.yaml에 extract 설정 섹션 추가
- 📝 README에 새 기능 상세 설명 추가
- 📝 문제 해결 섹션에 Q8, Q9 추가

### v2.0.1 (2025-10-29)
- 🐛 줄바꿈 이스케이프 버그 수정 (TSV `\r\n` → PO 정확한 변환)
- 🐛 검증 로직 수정 (실제 escape sequence 검사)
- ✨ CSV 병합 시 msgid 컬럼 제거
- ✨ CSV에서 ko가 en 앞에 위치하도록 변경
- 📝 배치 파일 제거 (CLI만 사용)
- 📝 README 간소화 및 업데이트

### v2.0 (2025-01-29)
- ✨ 통합 CLI 툴 구현 (`ds_l10n.py`)
- ✨ 번역 검증 기능 추가
- ✨ 자동 파일 정리 기능
- ✨ 컬러 로깅 시스템
- ✨ ko(원본 언어) 업데이트 지원
- 🐛 polib 기반으로 안정성 향상
- 🐛 Unicode/이모지 인코딩 문제 해결

---

## 📄 라이선스

Copyright © 2025 OneUniverse. All rights reserved.

---

**버전**: 2.0.2
**최종 수정**: 2025-10-30
**작성자**: DS_L10N Team