DS_L10N/README.md

DS_L10N

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

🚀 빠른 시작

1. 라이브러리 설치

pip install -r requirements.txt

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

더블클릭으로 실행:

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

3. 명령어로 실행

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 참조

✨ 주요 개선사항

기존 문제점

• ❌ 매번 파일/폴더 선택이 번거로움
• ❌ 번역 오류 사전 검증 불가
• ❌ 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 파일에서 경로와 동작 설정:

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단계: 미번역 추출

python ds_l10n.py extract

3단계: 외부 번역

• Google AI Studio 번역 앱 사용
• 결과를 번역업데이트.tsv에 저장

4단계: 번역 검증

python ds_l10n.py validate

5단계: PO 업데이트

python ds_l10n.py update

6단계: 언리얼 에디터

• PO 파일 임포트
• 텍스트 컴파일

7단계: 사후 관리

python ds_l10n.py merge    # CSV로 백업
python ds_l10n.py cleanup  # 파일 정리

또는 4~7단계 자동 실행:

전체워크플로우.bat

💡 팁

GUI 모드 사용

python ds_l10n.py extract --gui

시뮬레이션 모드

python ds_l10n.py update --dry-run

특정 파일 검증

python ds_l10n.py validate output/untranslated_20251029_123456.tsv

🐛 문제 해결

"모듈을 찾을 수 없습니다"

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