DS_L10N/사용가이드.md

DS_L10N 사용 가이드

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

목차

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

---

설치

1. 필요 라이브러리 설치

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

설치되는 라이브러리:

• polib: PO 파일 안정적 처리
• PyYAML: 설정 파일 관리
• pandas: 데이터 처리 (기존 스크립트 호환)

2. 설정 파일 확인

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

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

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

---

설정

config.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을 수정하여 사용하세요.

---

기본 사용법

명령어 구조

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	파일 정리 (신규)	-

도움말 보기

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 - 미번역 항목 추출

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

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

출력:

• output/untranslated_YYYYMMDD_HHMMSS.tsv
• msgctxt, SourceLocation, msgid 컬럼

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

---

2. validate - 번역 검증 ✨ 신규

# 기본 입력 파일 (번역업데이트.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 파일 업데이트

# 기본 입력 파일 (번역업데이트.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 병합

python ds_l10n.py merge

출력:

• LocalExport/merged_po_entries_YYYYMMDD_HHMMSS.csv
• 모든 언어의 번역을 하나의 CSV로 통합

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

---

5. cleanup - 파일 정리 ✨ 신규

python ds_l10n.py cleanup

정리 항목:

• 📦 오래된 CSV 파일 → archive/YYYYMM/ 폴더로 이동
• 📦 오래된 미번역 TSV 파일 보관
• 🗑️ 7일 이상 된 백업 파일 삭제
• 🗑️ 30일 이상 된 로그 파일 삭제

설정 (config.yaml):

cleanup:
  keep_recent_files: 5           # 최근 5개만 유지
  keep_backups_days: 7           # 백업 보관 기간
  delete_old_logs_days: 30       # 로그 보관 기간

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

---

문제 해결

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

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

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

config.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 옵션 사용:

python ds_l10n.py extract --gui

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

python ds_l10n.py cleanup

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

cleanup:
  delete_old_logs_days: 7  # 7일로 단축

---

고급 사용법

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

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

커스텀 설정 파일 사용

python ds_l10n.py --config my_config.yaml extract

배치 스크립트로 자동화

update_translations.bat:

@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