v2.0.1 업데이트
This commit is contained in:
Gnill82
444
README.md
444
README.md
@ -2,26 +2,35 @@
|
||||
|
||||
던전스토커즈 다국어 번역 통합 툴
|
||||
|
||||
---
|
||||
|
||||
## 📑 목차
|
||||
|
||||
1. [빠른 시작](#-빠른-시작)
|
||||
2. [주요 기능](#-주요-기능)
|
||||
3. [설치 및 설정](#-설치-및-설정)
|
||||
4. [워크플로우](#-워크플로우)
|
||||
5. [명령어 상세](#-명령어-상세)
|
||||
6. [문제 해결](#-문제-해결)
|
||||
7. [프로젝트 구조](#-프로젝트-구조)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 빠른 시작
|
||||
|
||||
### 1. 라이브러리 설치
|
||||
### 1. 라이브러리 설치 (최초 1회)
|
||||
|
||||
```bash
|
||||
cd D:\Work\WorldStalker\DS_L10N
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2. 배치 파일로 실행 (권장)
|
||||
**설치되는 라이브러리**:
|
||||
- `polib`: PO 파일 안정적 처리
|
||||
- `PyYAML`: 설정 파일 관리
|
||||
- `pandas`: 데이터 처리
|
||||
|
||||
더블클릭으로 실행:
|
||||
|
||||
- `1_미번역추출.bat` - 미번역 항목 추출
|
||||
- `2_번역검증.bat` - 번역 검증 (신규)
|
||||
- `3_PO업데이트.bat` - PO 파일 업데이트
|
||||
- `4_CSV병합.bat` - CSV 병합
|
||||
- `5_파일정리.bat` - 파일 정리 (신규)
|
||||
- `전체워크플로우.bat` - 2~5 자동 실행
|
||||
|
||||
### 3. 명령어로 실행
|
||||
### 2. 명령어 실행
|
||||
|
||||
```bash
|
||||
python ds_l10n.py extract # 미번역 추출
|
||||
@ -31,25 +40,256 @@ python ds_l10n.py merge # CSV 병합
|
||||
python ds_l10n.py cleanup # 파일 정리
|
||||
```
|
||||
|
||||
## 📚 상세 가이드
|
||||
### 3. 도움말
|
||||
|
||||
자세한 사용법은 [`사용가이드.md`](사용가이드.md) 참조
|
||||
```bash
|
||||
python ds_l10n.py --help
|
||||
python ds_l10n.py extract --help
|
||||
```
|
||||
|
||||
## ✨ 주요 개선사항
|
||||
---
|
||||
|
||||
### 기존 문제점
|
||||
- ❌ 매번 파일/폴더 선택이 번거로움
|
||||
- ❌ 번역 오류 사전 검증 불가
|
||||
- ❌ po_update_from_tsv.py 가끔 오류 발생
|
||||
- ❌ 결과물 파일이 너무 많이 쌓임
|
||||
## ✨ 주요 기능
|
||||
|
||||
### 개선된 기능
|
||||
- ✅ **자동 경로 인식** (config.yaml)
|
||||
- ✅ **번역 검증 기능** (변수, 태그, 줄바꿈 확인)
|
||||
- ✅ **polib 기반 안정적 업데이트**
|
||||
- ✅ **자동 경로 인식** (`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 사용 권장
|
||||
|
||||
---
|
||||
|
||||
## 📁 프로젝트 구조
|
||||
|
||||
@ -59,14 +299,7 @@ DS_L10N/
|
||||
├── config.yaml # 설정 파일
|
||||
├── 번역업데이트.tsv # 번역 입력 파일
|
||||
├── requirements.txt # 필요 라이브러리
|
||||
├── 사용가이드.md # 상세 매뉴얼
|
||||
│
|
||||
├── 1_미번역추출.bat # 배치 스크립트
|
||||
├── 2_번역검증.bat
|
||||
├── 3_PO업데이트.bat
|
||||
├── 4_CSV병합.bat
|
||||
├── 5_파일정리.bat
|
||||
├── 전체워크플로우.bat
|
||||
├── README.md # 이 문서
|
||||
│
|
||||
├── lib/ # 라이브러리 모듈
|
||||
│ ├── config_loader.py # 설정 로더
|
||||
@ -79,116 +312,69 @@ DS_L10N/
|
||||
├── logs/ # 로그 파일 (자동 생성)
|
||||
├── archive/ # 보관 파일 (자동 생성)
|
||||
│
|
||||
├── po_extract_untranslated.py # 기존 스크립트 (호환성 유지)
|
||||
├── po_update_from_tsv.py # 기존 스크립트 (호환성 유지)
|
||||
└── po_merge_to_csv.py # 기존 스크립트 (호환성 유지)
|
||||
├── DS_Context.txt # 번역 문맥 가이드
|
||||
├── DS_Terminology_DB.txt # 용어 데이터베이스
|
||||
└── DS_Terminology_Guide.txt # 용어집 가이드
|
||||
```
|
||||
|
||||
## 🔧 설정
|
||||
---
|
||||
|
||||
`config.yaml` 파일에서 경로와 동작 설정:
|
||||
## 💡 고급 사용법
|
||||
|
||||
```yaml
|
||||
paths:
|
||||
unreal_localization: ../WorldStalker/Content/Localization/LocalExport
|
||||
output_dir: ./output
|
||||
logs_dir: ./logs
|
||||
### Dry-run 모드
|
||||
|
||||
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단계: 미번역 추출
|
||||
```bash
|
||||
python ds_l10n.py extract
|
||||
```
|
||||
|
||||
### 3단계: 외부 번역
|
||||
- Google AI Studio 번역 앱 사용
|
||||
- 결과를 `번역업데이트.tsv`에 저장
|
||||
|
||||
### 4단계: 번역 검증
|
||||
```bash
|
||||
python ds_l10n.py validate
|
||||
```
|
||||
|
||||
### 5단계: PO 업데이트
|
||||
```bash
|
||||
python ds_l10n.py update
|
||||
```
|
||||
|
||||
### 6단계: 언리얼 에디터
|
||||
- PO 파일 임포트
|
||||
- 텍스트 컴파일
|
||||
|
||||
### 7단계: 사후 관리
|
||||
```bash
|
||||
python ds_l10n.py merge # CSV로 백업
|
||||
python ds_l10n.py cleanup # 파일 정리
|
||||
```
|
||||
|
||||
또는 **4~7단계 자동 실행**:
|
||||
```bash
|
||||
전체워크플로우.bat
|
||||
```
|
||||
|
||||
## 💡 팁
|
||||
|
||||
### GUI 모드 사용
|
||||
```bash
|
||||
python ds_l10n.py extract --gui
|
||||
```
|
||||
|
||||
### 시뮬레이션 모드
|
||||
```bash
|
||||
python ds_l10n.py update --dry-run
|
||||
```
|
||||
|
||||
### 특정 파일 검증
|
||||
실행 결과를 미리 확인 후 실제 업데이트 진행
|
||||
|
||||
### 커스텀 설정 파일
|
||||
|
||||
```bash
|
||||
python ds_l10n.py validate output/untranslated_20251029_123456.tsv
|
||||
python ds_l10n.py --config my_config.yaml extract
|
||||
```
|
||||
|
||||
## 🐛 문제 해결
|
||||
여러 프로젝트 관리 시 유용
|
||||
|
||||
### Jenkins/CI 통합
|
||||
|
||||
### "모듈을 찾을 수 없습니다"
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
cd DS_L10N
|
||||
python ds_l10n.py validate || exit 1
|
||||
python ds_l10n.py update || exit 1
|
||||
```
|
||||
|
||||
### "PO 파일을 찾을 수 없습니다"
|
||||
- `config.yaml`의 경로 확인
|
||||
- 언리얼에서 텍스트 익스포트 완료 확인
|
||||
---
|
||||
|
||||
### 업데이트 실패
|
||||
- `logs/` 폴더의 최신 로그 파일 확인
|
||||
- 실패 원인과 msgctxt 확인
|
||||
## 🔗 관련 문서
|
||||
|
||||
- **번역 문맥 가이드**: `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/이모지 인코딩 문제 해결
|
||||
|
||||
---
|
||||
|
||||
## 📄 라이선스
|
||||
|
||||
@ -196,6 +382,6 @@ Copyright © 2025 OneUniverse. All rights reserved.
|
||||
|
||||
---
|
||||
|
||||
**버전**: 2.0
|
||||
**최종 수정**: 2025-01-29
|
||||
**작성자**: Claude Code + DS_L10N Team
|
||||
**버전**: 2.0.1
|
||||
**최종 수정**: 2025-10-29
|
||||
**작성자**: DS_L10N Team
|
||||
|
||||
Reference in New Issue
Block a user