jinilkim/DS_L10N
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
17 Commits 1 Branch 0 Tags
main
Go to file
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

DS_L10N

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

📑 목차

  1. 빠른 시작
  2. 주요 기능
  3. 설치 및 설정
  4. 워크플로우
  5. 명령어 상세
  6. 문제 해결
  7. 프로젝트 구조

🚀 빠른 시작

1. 라이브러리 설치 (최초 1회)

cd D:\Work\WorldStalker\DS_L10N
pip install -r requirements.txt

설치되는 라이브러리:

  • polib: PO 파일 안정적 처리
  • PyYAML: 설정 파일 관리
  • pandas: 데이터 처리

2. 명령어 실행

python ds_l10n.py extract                    # 미번역 추출 (en만)
python ds_l10n.py extract --all-languages    # 미번역 추출 (모든 언어)
python ds_l10n.py extract --include-fuzzy    # fuzzy 항목 포함
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) 업데이트 지원
  • ✅ 줄바꿈 이스케이프 자동 처리
  • ✅ 스마트 미번역 감지 (msgstr 빈 값, ko 원본 변경 감지)
  • ✅ fuzzy 항목 추출 (리뷰 필요한 번역 감지)
  • ✅ 유연한 언어 검사 (en만 또는 전체 언어)

🔧 설치 및 설정

config.yaml 설정

config.yaml 파일에서 경로와 동작 설정 (상대 경로 사용):

paths:
  unreal_localization: ../WorldStalker/Content/Localization/LocalExport
  output_dir: ./output
  logs_dir: ./logs
  archive_dir: ./archive

languages:
  source: ko  # 원본 언어
  targets:    # 번역 대상 언어 (17개)
    - en
    - ja
    - zh-Hans
    - zh-Hant
    # ... 기타 언어

extract:
  check_all_languages: false  # 모든 언어 검사 (기본: en만)
  include_fuzzy: true         # fuzzy 항목 포함 (리뷰 필요)
  separate_files: true        # 언어별 개별 파일 생성

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              # en만 검사 (기본)
   python ds_l10n.py extract --all-languages  # 모든 언어 검사
   └─ 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 - 미번역 항목 추출

# 기본 사용 (en만 검사)
python ds_l10n.py extract

# 모든 언어 검사
python ds_l10n.py extract --all-languages

# fuzzy 항목 포함 (원본 변경으로 리뷰 필요한 항목)
python ds_l10n.py extract --include-fuzzy

# 옵션 조합
python ds_l10n.py extract --all-languages --include-fuzzy

# GUI 모드 (파일 선택)
python ds_l10n.py extract --gui

기능:

  • 기본 동작: en PO 파일에서 msgstr이 비어있는 항목 추출
  • --all-languages: 모든 대상 언어(17개) 검사
  • --include-fuzzy: fuzzy 플래그 항목도 추출 (ko 원본 변경 감지)
  • msgstr이 비어있는 항목을 정확히 감지
  • TSV 형식으로 저장 (msgctxt, SourceLocation, msgid)

출력:

  • 기본: output/untranslated_YYYYMMDD_HHMMSS.tsv
  • 전체 언어: output/untranslated_{lang}_YYYYMMDD_HHMMSS.tsv (언어별 17개 파일)

사용 시나리오:

  1. 일반적인 경우: python ds_l10n.py extract (en만 빠르게 검사)
  2. ko 원본이 변경된 경우: python ds_l10n.py extract --include-fuzzy
  3. 전체 언어 점검: python ds_l10n.py extract --all-languages

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. 업데이트 후에도 언리얼에서 번역이 안 보임

  1. 언리얼 에디터에서 PO 임포트 실행
  2. 텍스트 컴파일 실행
  3. 에디터 재시작

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 사용 권장

Q8. 미번역이 있는데 추출되지 않음

상황: PO 파일에 msgstr이 비어있는데 extract 명령으로 감지되지 않음

원인: 기본적으로 en만 검사하기 때문

해결:

# 모든 언어 검사
python ds_l10n.py extract --all-languages

Q9. ko 원본이 변경되었는데 번역이 그대로임

상황: ko 원본 텍스트가 수정되었지만 번역문이 예전 원본 기준임

원인: fuzzy 플래그가 있는 항목은 기본 extract에서 제외됨

해결:

# fuzzy 항목도 추출 (리뷰 필요한 번역)
python ds_l10n.py extract --include-fuzzy

# 또는 전체 언어 + fuzzy
python ds_l10n.py extract --all-languages --include-fuzzy

📁 프로젝트 구조

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.2 (2025-10-30)

  • ✨ 미번역 추출 기능 대폭 개선
    • 기본적으로 en만 검사 (빠른 실행)
    • --all-languages 옵션으로 전체 언어 검사
    • --include-fuzzy 옵션으로 리뷰 필요 항목 추출
    • msgstr 빈 값 정확히 감지 (ko 원본 변경 케이스)
  • ✨ config.yaml에 extract 설정 섹션 추가
  • 📝 README에 새 기능 상세 설명 추가
  • 📝 문제 해결 섹션에 Q8, Q9 추가

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.2 최종 수정: 2025-10-30 작성자: DS_L10N Team

Description
던전스토커즈 다국어 번역관련 툴
Readme 28 MiB
Languages
Python 100%