DS_L10N
던전스토커즈 다국어 번역 통합 툴
📑 목차
🚀 빠른 시작
1. 라이브러리 설치 (최초 1회)
cd D:\Work\WorldStalker\DS_L10N
pip install -r requirements.txt
설치되는 라이브러리:
polib: PO 파일 안정적 처리PyYAML: 설정 파일 관리pandas: 데이터 처리
2. 명령어 실행
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 # 파일 정리
3. 도움말
python ds_l10n.py --help
python ds_l10n.py extract --help
✨ 주요 기능
- ✅ 자동 경로 인식 (
config.yaml기반) - ✅ 번역 검증 (변수, 태그, 줄바꿈 확인)
- ✅ 안정적 업데이트 (polib 라이브러리 사용)
- ✅ 컬러 로그 (오류 원인 명확히 표시)
- ✅ 자동 백업 (업데이트 전 자동 생성)
- ✅ 자동 파일 정리 (오래된 파일 보관)
- ✅ 원본 언어(ko) 업데이트 지원
- ✅ 줄바꿈 이스케이프 자동 처리
🔧 설치 및 설정
config.yaml 설정
config.yaml 파일에서 경로와 동작 설정 (상대 경로 사용):
paths:
unreal_localization: ../WorldStalker/Content/Localization/LocalExport
output_dir: ./output
logs_dir: ./logs
archive_dir: ./archive
languages:
source: ko # 원본 언어
targets: # 번역 대상 언어 (18개)
- en
- ja
- zh-Hans
- zh-Hant
# ... 기타 언어
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
└─ 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단계 자동 실행:
python ds_l10n.py validate && python ds_l10n.py update && python ds_l10n.py merge && python ds_l10n.py cleanup
📝 명령어 상세
1. extract - 미번역 항목 추출
python ds_l10n.py extract
기능:
- 원본 언어(ko) PO 파일에서 msgstr이 비어있는 항목 추출
- TSV 형식으로 저장 (msgctxt, SourceLocation, msgid)
출력: output/untranslated_YYYYMMDD_HHMMSS.tsv
2. validate - 번역 검증
python ds_l10n.py validate [TSV파일]
검증 항목:
- ❌ 오류 (ERROR): 변수 누락/추가, 태그 불일치
- ⚠️ 경고 (WARNING): 줄바꿈 불일치 (UI 레이아웃 영향)
- ℹ️ 정보 (INFO): 길이 초과
특징:
- ko는 원본 언어로 검증에서 자동 제외
- msgid 컬럼이 없으면 ko 컬럼을 원본으로 사용
- 오류 발견 시 상세한 원인과 위치 표시
3. update - PO 파일 업데이트
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 병합
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 - 파일 정리
python ds_l10n.py cleanup
정리 항목:
- 📦 오래된 CSV/TSV 파일 →
archive/YYYYMM/폴더로 이동 - 🗑️ 7일 이상 된 백업 파일 삭제
- 🗑️ 30일 이상 된 로그 파일 삭제
🐛 문제 해결
Q1. "모듈을 찾을 수 없습니다" 오류
pip install -r requirements.txt
Q2. "PO 파일을 찾을 수 없습니다" 오류
config.yaml의 경로가 올바른지 확인:
paths:
unreal_localization: ../WorldStalker/Content/Localization/LocalExport
Q3. 업데이트 후에도 언리얼에서 번역이 안 보임
- 언리얼 에디터에서 PO 임포트 실행
- 텍스트 컴파일 실행
- 에디터 재시작
Q4. 검증에서 오류가 발생함
변수 누락 오류: 원문의 {Value} 같은 변수를 번역문에 그대로 복사
태그 불일치 오류: 모든 <TagName>에 대응하는 </>가 있는지 확인
줄바꿈 불일치 경고: \r\n 위치를 원문과 동일하게 유지 (UI 레이아웃)
Q5. 원본 언어(ko)를 수정하고 싶음
번역업데이트.tsv의 ko 컬럼에 수정된 원본을 입력하고:
python ds_l10n.py update # ko 포함 모든 언어 업데이트
Q6. 코드 수정 후 반영이 안 됨
Python 캐시 문제일 수 있습니다:
# 방법 1: 캐시 삭제
find . -type d -name "__pycache__" -exec rm -rf {} +
# 방법 2: 캐시 무시 옵션
python -B ds_l10n.py merge
Q7. Unicode/이모지 표시 오류
Windows 콘솔에서 이모지가 깨지는 경우:
- 로그 파일(
logs/)에서는 정상적으로 표시됨 - Windows Terminal 사용 권장
📁 프로젝트 구조
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 모드
python ds_l10n.py update --dry-run
실행 결과를 미리 확인 후 실제 업데이트 진행
커스텀 설정 파일
python ds_l10n.py --config my_config.yaml extract
여러 프로젝트 관리 시 유용
Jenkins/CI 통합
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.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.1 최종 수정: 2025-10-29 작성자: DS_L10N Team