388 lines
9.5 KiB
Markdown
388 lines
9.5 KiB
Markdown
# 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 # 미번역 추출
|
||
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) 업데이트 지원**
|
||
- ✅ **줄바꿈 이스케이프 자동 처리**
|
||
|
||
---
|
||
|
||
## 🔧 설치 및 설정
|
||
|
||
### 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: # 번역 대상 언어 (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단계 자동 실행:
|
||
|
||
```bash
|
||
python ds_l10n.py validate && python ds_l10n.py update && python ds_l10n.py merge && python ds_l10n.py cleanup
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 명령어 상세
|
||
|
||
### 1. extract - 미번역 항목 추출
|
||
|
||
```bash
|
||
python ds_l10n.py extract
|
||
```
|
||
|
||
**기능**:
|
||
- 원본 언어(ko) PO 파일에서 msgstr이 비어있는 항목 추출
|
||
- TSV 형식으로 저장 (msgctxt, SourceLocation, msgid)
|
||
|
||
**출력**: `output/untranslated_YYYYMMDD_HHMMSS.tsv`
|
||
|
||
---
|
||
|
||
### 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 사용 권장
|
||
|
||
---
|
||
|
||
## 📁 프로젝트 구조
|
||
|
||
```
|
||
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.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
|