| name | game-translate |
| description | Orchestrate a fail-closed Korean game-localization workflow across overall analysis, text analyze/translate/QA/review, conditional image analyze/translate/QA/review, integrated QA, and release. Review stages prepare emulator-ready handoffs by default and wait for user approval only when the project explicitly sets user-gate. Use when starting, resuming, or reconciling a NSW/SFC/PS1/PS2/Steam game translation project. |
game-translate — 게임 한글화 오케스트레이터
사용자가 합법적으로 보유한 게임의 개인 번역 패치를 지휘한다. 원본 게임 데이터·콘솔 키·
펌웨어는 작업·배포 산출물에 포함하지 않는다. 단계·상태·정리 규칙은
$GT_HOME/common/pipeline-contract.json과 pipeline-contract.md를 기준으로 한다.
0. 환경과 안전
| 변수 | 의미 |
|---|
GT_HOME | .codex-plugin/, skills/, common/이 함께 있는 설치 플러그인 루트 또는 Claude의 ${CLAUDE_PLUGIN_ROOT} |
GT_WORKSPACE | 게임 데이터·타이틀 작업장 루트 |
GT_TOOLS | 공용 도구 폴더. 게임 산출물은 만들지 않음 |
시작 전에 다음을 읽는다.
$GT_HOME/common/SAFETY.md$GT_HOME/common/project-structure.md$GT_HOME/common/workspace-boundary-contract.md$GT_HOME/common/preflight-checks.md$GT_HOME/common/pipeline-contract.md와 pipeline-contract.json- 플랫폼 어댑터
platforms/<platform>/PLATFORM.md와 현재 단계 문서
- 엔진을 식별한 뒤
engines/<engine>/ENGINE.md
타이틀 루트는 플랫폼 어댑터가 증명한 원본이 직접 있는 실제 폴더다(NSW는 .nsp/.xci,
Steam/PC는 실제 게임 EXE가 있는 설치 폴더). 작업물·임시 파일·staging·
런타임 증거는 그 폴더의 _work/<프로젝트 ID>/ 아래에만 둔다. GT_HOME, 저장소 루트,
OS 임시 폴더, 공용 MCP 디렉터리, 임의 title/output/temp 폴더를 출력 경로로 쓰지
않는다. 프로젝트·플랫폼·엔진·Title ID·정책을 확정하지 못하면 변경·삭제·런타임을 하지
않고 WARN/BLOCKED와 Handoff만 기록한다.
도구가 만드는 export·번역 중간물·테스트 산출물/스크립트는
$GT_HOME/common/artifact-layout-contract.md의 class별 managed root에 두고
90_tools/PROJECT_ARTIFACT_MANIFEST.tsv에 artifact key, producer, reproduce command,
lifecycle, status, SHA-256을 기록한다. 기존 프로젝트는 작업 전
npm run project:artifacts -- --project-root "<프로젝트 루트>" --init으로 하네스를 만든다.
managed root의 미등록 파일이나 hash drift가 있으면 해당 단계는 BLOCKED다.
모든 쓰기 명령 전에는 npm run project:boundary -- --project-root "<프로젝트 루트>" --stage <기능> --assert-output "<output/temp/cache>"로 각 경로를 검사한다. 하나라도 프로젝트
밖이거나 기능별 canonical root 밖이면 명령을 실행하지 않는다.
1. 실제 단계 흐름
| 순서 | 단계 | 스킬 | 완료 상태 |
|---|
| 1 | 공통 파일·엔진·언어 슬롯 분석 | gt-analyze | project_status=analyzed |
| 2 | 텍스트 대상·왕복 계약 분석 | gt-text-analyze | text analyzed |
| 3 | 텍스트 번역·용어집 누적 | gt-text-translate | text translated |
| 4 | 텍스트·폰트 기술 QA·후보 생성 | gt-text-qa | text qa_ready, font_status=verified |
| 5 | 텍스트 검수 handoff·에뮬레이터 준비 | gt-text-review | text review_ready |
| 6 | 이미지 대상·atlas 계약 분석 | gt-image-analyze | image analyzed |
| 7 | 이미지·텍스처 번역 | gt-image-translate | image translated |
| 8 | 이미지 기술 QA·주입 후보 생성 | gt-image-qa | image qa_ready |
| 9 | 이미지 비교·검수 handoff | gt-image-review | image review_ready |
| 10 | 텍스트·폰트·이미지 통합 빌드·실행 QA | gt-qa | qa_status=passed |
| 11 | 플랫폼 배포 패키징 | gt-release | release_status=released |
기본 실행 순서는 표와 같으며, 공통 분석 뒤 텍스트 브랜치를 먼저 끝내 이미지 안의
문자에 glossary·STYLE을 공급한다. 프로젝트가 읽기 전용 병렬 분석을 허용해도 같은
manifest·번역표·staging을 동시에 쓰지 않는다.
2. 검수·사용자 대기 정책
text-review와 image-review의 “검수”는 기술 QA 결과, 전체 시트, 비교 자료, hash,
canonical staging, handoff를 만들어 다음 단계가 실행 가능하게 준비하는 뜻이다.
- 기본
text_review_policy=prepare-only, image_review_policy=prepare-only: 산출물을
완성하고 review_ready로 자동 진행한다. 사용자 허락을 묻거나 대기하지 않는다.
- 프로젝트에
text_review_policy=user-gate 또는 image_review_policy=user-gate가
명시된 경우에만 해당 시트를 제출하고 사용자의 명시적 완료를 기다린다.
review_ready는 사용자 승인·PASS (runtime)·릴리스 완료가 아니다.- 사용자가 나중에 수정안을 제공하면 해당 행/이미지만 branch QA부터 다시 실행한다.
runtime_policy는 review policy와 별개다. static-first에서는 사용자의 명시적 실행
요청 전까지 bench와 PENDING_RUNTIME만 기록한다. 이 정책은 중간 실행 빈도만 조절하며,
릴리스 전 공식 배포용 릴리즈 에뮬레이터의 non-MCP 직접 실행을 생략하지 않는다.
3. 이미지 범위
image_scope=pending이면 이미지 단계를 생략하지 않는다.gt-image-analyze가 전수 inventory·시각/metadata 근거를 남긴 뒤 required 또는
N/A로 확정한다.required면 이미지 4단계를 모두 실행한다. N/A면 계획·가짜 이미지·검수 행을 만들지
않고 image_status=skipped, 0건 근거, 생략 사유를 기록한 뒤 gt-qa로 이동한다.N/A여도 통합 QA에서 원본 이미지·atlas가 정상 표시되는지는 확인한다.
4. 공통 preflight와 상태
각 단계를 직접 호출할 때도 PROJECT.md, WORK_LOG.md, HANDOFF.md, 입력 manifest·
출력 경로의 수정 시각/크기/SHA-256/git status를 읽는다. 정책 필수값은
batch_size, glossary_path, runtime_policy, runtime_authorization,
플랫폼별 basic_test_backend와 mcp_session_scope(NSW는 eden-mcp/one-per-title,
Steam/PC는 direct-native/none),
final_qa_runtime=official-distribution-release, final_qa_mcp_allowed=false,
target_language_slot, image_scope, image_model=provider-selected,
image_quality=provider-managed, image_input_fidelity=provider-managed,
text_review_policy, image_review_policy,
text_review_approval, image_review_approval, font_status, release_contract다.
행 상태, 브랜치 상태, QA 상태, 사용자 승인, 런타임 상태, 릴리스 상태를 한 값으로 합치지
않는다. qa_ready ≠ review_ready ≠ user-approved ≠ PASS (runtime) ≠ released다.
문서·manifest·세션·파일 해시가 충돌하면 추측하지 않는다. HANDOFF.md에 append-only로
관찰·영향·결정·증거·상태를 기록하고 현재 branch를 blocked로 유지한다.
5. 폰트와 런타임 안전 게이트
gt-text-qa는 $GT_HOME/common/font-atlas-contract.md에 따라 전체 가시 코드포인트,
실제 font consumer/fallback, glyph ID·atlas rect·UV 원점·padding·bearing·advance·
baseline·line metrics, 기존 glyph 보존, 왕복 추출, render probe를 증명한다. 이 증거가
없거나 font_status=verified가 아니면 text review-ready나 통합 QA로 진행하지 않는다.
gt-qa는 깨끗한 원본에서 한 번만 통합한다. NSW 기본 smoke는 Eden-MCP의 단일 title 세션을
재사용하고, Steam/PC는 설치 게임의 direct-native smoke를 사용하지만 어느 쪽도 그 결과를
최종 PASS로 쓰지 않는다. 최종 QA는 플랫폼 allowlist의 공식 배포 릴리즈/설치본을 MCP 없이
직접 실행하고 입력 경로·project/Title ID·active mod 전수 hash·
binary/build hash·화면 전이·로그/캡처를 RELEASE_RUNTIME_QA.json에 귀속한다. 로더 생존·
종료 코드·패치 적용 로그만으로 PASS하지 않는다.
이미지 branch는 $GT_HOME/common/image-translation-contract.md를 적용한다. 에이전트가
만든 raster 후보는 API 키 없는 $imagegen 내장 image_gen.imagegen을 같은 byte-exact
reference·prompt로 최소 3회 독립 호출한 schema 3 receipt(canvas-size-only 정규화 schema 4 또는
best-of-3 alpha mask composition schema 5 포함)와 정확히 하나의 합격 선택 후보가
있어야 하고,
IMAGE_GENERATION_MANIFEST.tsv에 대해 validate-image-translation.mjs가 source/reference
비덮어쓰기, 원문 완전 제거와 no-overlay, 원어의 서체 인상·색·외곽선·질감·재질·광원·
자간/baseline·분위기, anchor/atlas rect·canvas/format, 선언된 alpha policy, edit region 밖
decoded RGBA diff 0을 증명해야 한다. 내장 surface가 노출하지 않는 모델/quality를 주장하거나
API/CLI, Python/Pillow/OpenCV/임의 스크립트 raster 생성물, 검증기 Issues: 0이 없는 후보는
이미지 번역·QA 완료로 승격하지 않는다. 합격 후보가 없으면 hold-for-imagegen-review로 멈춘다.
6. 세션·중복 파일 방지
NSW 기본 smoke는 Eden-MCP다. Eden-MCP와 Ryubing-MCP는 프로젝트당
50_test/eden/SESSION.json과 ARTIFACT_MANIFEST.tsv 하나를 공유한다. 실행 전에 양쪽
capability와 같은 Title ID의 remote session 목록/status를 조회한다.
- 같은 session key면 새 세션을 만들지 않고 재사용한다.
- 양쪽을 합쳐 active/pending 세션이 둘 이상이면
BLOCKED다. Ryubing이나 두 번째 generation은
구체적 예외 사유와 이전 exact close 증거가 있을 때만 허용한다.
pending 상태에서 create를 재호출하지 않는다. remote를 재조회하고 BLOCKED로 조정한다.- 이전
last_session_id가 있으면 exact remote close와 local close 기록을 먼저 증명하고,
새 prepare에는 --previous-session-id <동일 ID>를 전달한다.
- 세션·런 폴더, timestamp/session/copy 파일, 다른 Title ID의 staging·로그를 만들지 않는다.
- create/launch 실패 후 status 재조회 전 재호출하지 않는다. 종료 시 현재 ID만 close한다.
- 동일
artifact_key·canonical path가 있으면 hash를 비교해 재사용/원자 교체하고 복사본을
만들지 않는다.
qa-session guard는 원격 MCP 세션을 직접 삭제하지 않는다. remote close 성공을 확인한 뒤에만
local --action close --remote-closed를 실행한다. 소유권을 증명할 수 없는 세션은 삭제하지
않고 BLOCKED다.
7. PDCA와 재개
- Plan: 단계 입력 범위·정책·완료 기준·artifact key를
PROJECT.md에 기록
- Do: 해당 스킬 실행. 번역 manifest는 단일 메인 에이전트가 직렬 갱신
- Check: 전수 구조·hash·왕복·폰트/이미지/런타임 증거를 완료 기준과 대조
- Act: 실패한 배치·행·폰트 asset·이미지만 깨끗한 원본에서 재작업하고 해당 branch부터 반복
- Handoff: 문서 drift·우회·미해결 제한·세션 문제를 즉시 append-only 기록
재개 시 PROJECT.md의 마지막 미완료 단계와 실제 manifest/hash를 다시 읽는다. 완료된
단계를 의도 없이 전체 재실행하거나, 이전 candidate·이전 세션을 새 산출물로 복제하지 않는다.
8. 작업장·타이틀 정리
정리는 tmp glob 삭제가 아니다. $GT_HOME/common/cleanup-contract.md와 다음 스킬을
사용한다.
gt-project-cleanup: 하나의 타이틀 _work/<ID>에 대해 Handoff·manifest·세션·참조를
추론하고 PROJECT_ARTIFACT_MANIFEST.tsv의 lifecycle을 대조해 CLEANUP_PLAN.json과
CLEANUP_INSTRUCTIONS.md 생성gt-workspace-cleanup: 작업장 루트의 타이틀 중복·미등록 폴더·세션 잔재를 Handoff와
프로젝트 상태로 대조해 외부 보고서/계획 생성
기본은 이동·삭제하지 않는다. approved=true인 exact 파일과 현재 plan SHA-256을 명시한
--apply --plan은 후보를 cleanup archive로 옮길 뿐 영구 삭제하지 않는다. 이어서 모든
아카이브 파일과 root/project·Handoff·세션·문서 해시를 다시 검사한
CLEANUP_ARCHIVE_REVIEW.md를 사용자에게 상세히 보고하고 그 turn을 종료한다.
휴지통 이동은 사용자가 보고 이후 별도 요청으로 명시적으로 승인한 경우에만
TRASH_PLAN.json의 보고·사용자·항목별 승인과 현재 SHA-256을 기록해
--trash --user-confirmed-trash로 아카이브 exact 파일에 수행한다. 운영체제 휴지통이
지원되지 않거나 실패하면 영구 삭제로 폴백하지 않고 BLOCKED로 중단한다. 보고 이후
상태가 바뀌면 --review-archive로 재검토하고 모든 승인을 초기화한다. active 세션·보존
anchor·link/reparse point·계획 밖 경로는 항상 거부한다.
canonical·evidence 아티팩트는 보존하고, hash가 일치하는 reproducible·disposable
exact 파일만 승인 후보로 삼는다. 미등록 managed-root 파일은 자동 삭제하지 않는다.
9. 신규 프로젝트·완료
신규 프로젝트는 플랫폼 어댑터가 지정한 생성 명령을 사용한다. NSW는 실제 NSP/XCI 보유
폴더 아래 project:new, Steam/PC는 실제 게임 EXE가 있는 설치 폴더 아래
project:new:steam으로 생성한다. 수동 generic title 폴더를 만들지 않는다.
완료는 gt-qa의 bench와 공식 배포 릴리즈 non-MCP runtime receipt, 별도 hardware 상태,
gt-release의 exact package 계약이 모두 충족될 때만 선언한다. 릴리스 후에도
gt-project-cleanup으로 정리 계획을
생성하고, Handoff·manifest·QA·release anchor를 보존한다.
10. 빌드·패치 생성 요청의 의미
사용자가 “빌드 생성” 또는 **“패치 생성”**이라고 요청하면 이를 중간 staging이나
진단 후보 생성으로 해석하지 않는다. 플랫폼 어댑터의 canonical 배포 패키지를 생성하는
요청으로 라우팅한다. NSW에서는 전담 gt-nsw-build와 platforms/nsw/release.md를 적용하여
40_build/layeredfs/<BASE_TITLE_ID>/romfs/의 검증된 패치 파일만 입력하고,
40_build/releases/<BASE_TITLE_ID>.zip 안에
<BASE_TITLE_ID>/romfs/<패치파일> 구조를 만든다. 별도 Python 적용기, *.gldelta,
버전/candidate 하위 폴더, 게임명 ZIP은 허용하지 않는다. 릴리스 완료 게이트가 아직
충족되지 않았다면 같은 canonical 형식의 review_candidate로 만들 수 있지만 경로·이름·
ZIP root 계약은 완화하지 않고 release_status도 released로 올리지 않는다. 정식 릴리스
요청이면 gt-nsw-build가 검증한 canonical ZIP을 gt-release로 인계해 나머지 QA·문서·
상태 게이트를 수행한다.
Steam/PC에서 같은 표현은 platforms/steam/release.md의 canonical package 생성으로
라우팅한다. 입력은 재배포 원장이 검증한 40_build/overlay/, 출력은
40_build/releases/<project-id>.zip, ZIP root는 patch/다. 다음 공용 명령을 사용하며 원본
게임 assembly/asset/archive/executable은 패키징하지 않는다.
npm run release:package:steam -- --project-root "<install-root>/_work/<steam-APP_ID|pc-slug>"
npm run release:validate:steam -- --project-root "<install-root>/_work/<steam-APP_ID|pc-slug>"
