번역툴 2.0 업데이트
This commit is contained in:
Gnill82
419
사용가이드.md
Normal file
419
사용가이드.md
Normal file
@ -0,0 +1,419 @@
|
||||
# DS_L10N 사용 가이드
|
||||
|
||||
던전 스토커즈 현지화 통합 툴
|
||||
|
||||
## 목차
|
||||
|
||||
1. [설치](#설치)
|
||||
2. [설정](#설정)
|
||||
3. [기본 사용법](#기본-사용법)
|
||||
4. [개선된 워크플로우](#개선된-워크플로우)
|
||||
5. [명령어 상세](#명령어-상세)
|
||||
6. [문제 해결](#문제-해결)
|
||||
|
||||
---
|
||||
|
||||
## 설치
|
||||
|
||||
### 1. 필요 라이브러리 설치
|
||||
|
||||
```bash
|
||||
cd D:\Work\WorldStalker\DS_L10N
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
설치되는 라이브러리:
|
||||
- `polib`: PO 파일 안정적 처리
|
||||
- `PyYAML`: 설정 파일 관리
|
||||
- `pandas`: 데이터 처리 (기존 스크립트 호환)
|
||||
|
||||
### 2. 설정 파일 확인
|
||||
|
||||
`config.yaml` 파일에서 경로와 설정 확인:
|
||||
|
||||
```yaml
|
||||
paths:
|
||||
unreal_localization: ../WorldStalker/Content/Localization/LocalExport
|
||||
output_dir: ./output
|
||||
logs_dir: ./logs
|
||||
...
|
||||
```
|
||||
|
||||
모든 경로는 상대 경로로 설정되어 있으며, `DS_L10N` 폴더 기준입니다.
|
||||
|
||||
---
|
||||
|
||||
## 설정
|
||||
|
||||
### config.yaml 주요 설정
|
||||
|
||||
```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`을 수정하여 사용하세요.
|
||||
|
||||
---
|
||||
|
||||
## 기본 사용법
|
||||
|
||||
### 명령어 구조
|
||||
|
||||
```bash
|
||||
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` | 파일 정리 (신규) | - |
|
||||
|
||||
### 도움말 보기
|
||||
|
||||
```bash
|
||||
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 - 미번역 항목 추출
|
||||
|
||||
```bash
|
||||
# CLI 모드 (자동 경로)
|
||||
python ds_l10n.py extract
|
||||
|
||||
# GUI 모드 (파일 선택)
|
||||
python ds_l10n.py extract --gui
|
||||
```
|
||||
|
||||
**출력**:
|
||||
- `output/untranslated_YYYYMMDD_HHMMSS.tsv`
|
||||
- msgctxt, SourceLocation, msgid 컬럼
|
||||
|
||||
**사용 시기**: 언리얼에서 텍스트 익스포트 후
|
||||
|
||||
---
|
||||
|
||||
### 2. validate - 번역 검증 ✨ 신규
|
||||
|
||||
```bash
|
||||
# 기본 입력 파일 (번역업데이트.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 파일 업데이트
|
||||
|
||||
```bash
|
||||
# 기본 입력 파일 (번역업데이트.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 병합
|
||||
|
||||
```bash
|
||||
python ds_l10n.py merge
|
||||
```
|
||||
|
||||
**출력**:
|
||||
- `LocalExport/merged_po_entries_YYYYMMDD_HHMMSS.csv`
|
||||
- 모든 언어의 번역을 하나의 CSV로 통합
|
||||
|
||||
**사용 시기**: PO 임포트/컴파일 후, 엑셀에서 관리할 때
|
||||
|
||||
---
|
||||
|
||||
### 5. cleanup - 파일 정리 ✨ 신규
|
||||
|
||||
```bash
|
||||
python ds_l10n.py cleanup
|
||||
```
|
||||
|
||||
**정리 항목**:
|
||||
- 📦 오래된 CSV 파일 → `archive/YYYYMM/` 폴더로 이동
|
||||
- 📦 오래된 미번역 TSV 파일 보관
|
||||
- 🗑️ 7일 이상 된 백업 파일 삭제
|
||||
- 🗑️ 30일 이상 된 로그 파일 삭제
|
||||
|
||||
**설정** (`config.yaml`):
|
||||
```yaml
|
||||
cleanup:
|
||||
keep_recent_files: 5 # 최근 5개만 유지
|
||||
keep_backups_days: 7 # 백업 보관 기간
|
||||
delete_old_logs_days: 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}` 같은 변수를 포함시키지 않음
|
||||
- 원문의 변수를 그대로 번역문에 복사
|
||||
|
||||
**태그 불일치 오류**:
|
||||
- `<Red>강력한</>`처럼 여는 태그와 닫는 태그 개수 일치시키기
|
||||
|
||||
**줄바꿈 불일치 경고**:
|
||||
- `\r\n` 위치를 원문과 동일하게 유지 (UI 레이아웃)
|
||||
|
||||
### Q5. 기존 GUI 스크립트를 계속 사용하고 싶음
|
||||
|
||||
기존 스크립트 파일은 그대로 유지됩니다:
|
||||
- `po_extract_untranslated.py`
|
||||
- `po_update_from_tsv.py`
|
||||
- `po_merge_to_csv.py`
|
||||
|
||||
또는 `--gui` 옵션 사용:
|
||||
|
||||
```bash
|
||||
python ds_l10n.py extract --gui
|
||||
```
|
||||
|
||||
### Q6. 로그 파일이 너무 많이 쌓임
|
||||
|
||||
```bash
|
||||
python ds_l10n.py cleanup
|
||||
```
|
||||
|
||||
또는 `config.yaml`에서 자동 삭제 기간 조정:
|
||||
|
||||
```yaml
|
||||
cleanup:
|
||||
delete_old_logs_days: 7 # 7일로 단축
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 고급 사용법
|
||||
|
||||
### Dry-run 모드로 안전하게 테스트
|
||||
|
||||
```bash
|
||||
# 실제 파일 수정 없이 시뮬레이션
|
||||
python ds_l10n.py update --dry-run
|
||||
```
|
||||
|
||||
### 커스텀 설정 파일 사용
|
||||
|
||||
```bash
|
||||
python ds_l10n.py --config my_config.yaml extract
|
||||
```
|
||||
|
||||
### 배치 스크립트로 자동화
|
||||
|
||||
`update_translations.bat`:
|
||||
|
||||
```batch
|
||||
@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
|
||||
Reference in New Issue
Block a user