localization-packager – 지역화 패키지 도구

localization-packager — 에이전트 스킬

목적

다국어화 작업은 번역을 중심으로 한 패키징 문제입니다. 모든 언어는 동일한 4개 파일을 제공해야 하며, 반환된 파일은 존재 여부, 제목 길이, 자막 파싱 가능성, 큐 개수, 큐 타이밍 드리프트 등을 검사해야 합니다. 이 도구는 하나의 프로젝트 JSON 파일로부터 계획, 인계 시트, 구조적 검증을 생성합니다. 순수 Python 표준 라이브러리로 작성되었으며 로컬에서만 동작합니다.

이 도구의 핵심 원칙: 번역을 수행하지 않으며 번역 품질을 평가하지 않습니다. check는 구조(파일 존재 여부, 파싱 가능성, 길이, 타이밍)를 검증합니다. COMPLETE 패키지라고 해도 번역이 잘못되었을 수 있습니다. 해당 언어를 읽을 수 있는 사람만이 이를 판단할 수 있습니다. COMPLETE 결과를 "번역이 좋음" 또는 "게시 준비 완료"라고 보고하지 마십시오. 이는 "구조적으로 완료되어 인간의 품질 검토를 받을 준비가 됨"을 의미합니다.

사용 시기 / 사용하지 말아야 할 시기

다음과 같은 경우 사용합니다:

• 영상이나 앱을 추가 언어로 출시할 때 번역자에게 작업을 전달하는 경우: manifest로 계획 수립, sheet로 인계, check로 반환된 작업을 게이트합니다.
• 파이프라인에서 언어별 성공 여부가 필요한 경우: check exit 0 = 모든 언어가 구조적으로 완료됨; exit 1 = 출력이 각 미완료 언어와 정확한 문제를 명시합니다.

다음과 같은 경우 사용하지 마십시오:

• 번역 자체가 필요한 경우 — 이 도구는 번역 API를 호출하지 않으며 번역된 텍스트를 생성하지 않습니다. 빈 대상 열은 인간 번역자를 위한 것입니다.
• 번역 품질 보증이 필요한 경우 — 맞춤법 검사, 역번역 또는 품질 점수 기능이 없습니다.
• 채널 수준 에셋(배너, 엔드 스크린)이나 앱 스토어 메타데이터가 필요한 경우 — 4개 패키지 파일을 벗어나므로 의도적으로 범위 밖입니다.

명령어

모든 명령어는 프로젝트 파일을 위치 인자로 받으며 --json을 지원합니다.

# 언어별 전달 계획
python3 src/localization_packager.py manifest PROJECT.json

# 번역자 인계 시트 (기본 Markdown 또는 CSV, 단일 언어 또는 전체 대상)
python3 src/localization_packager.py sheet PROJECT.json \
    [--format md|csv] [--language CODE]

# 작성된 패키지 검증 (언어가 하나라도 미완료면 exit 1)
# --root는 폴더가 다른 위치에 있을 때 사용
python3 src/localization_packager.py check PROJECT.json \
    [--root DIR]

프로젝트 필드: project (이름), source_language, source_title, source_description, source_thumbnail_text, source_subtitles (소스 SRT 경로, 프로젝트 파일 기준 상대 경로), targets — {"language", "name", "translator"?} 리스트; 언어 코드는 고유해야 합니다. 파일은 읽을 때마다 검증되며, 구조적 문제(필드 누락, 중복 언어, 소스 SRT 누락 또는 파싱 불가)는 문제를 명시하는 exit-2 오류를 발생시킵니다.

패키지 레이아웃: 언어 코드당 하나의 폴더에 title.txt, description.txt, subtitles.srt, thumbnail.txt 파일이 포함됩니다.

검사 규칙 (정확)

언어별로 파일 순서대로 검사합니다:

• title.txt — 누락 또는 비어 있으면 문제; strip된 텍스트가 100자를 초과하면 문제 (100자 통과, 101자 플래그). 문자는 유니코드 코드 포인트 기준입니다.
• description.txt — 누락 또는 비어 있으면 문제.
• subtitles.srt — 누락 또는 비어 있으면 문제; SRT로 파싱되지 않으면 문제 (파싱 오류 인용); 소스 큐 개수와의 차이가 소스 개수의 **25%**를 초과하면 문제 (정확히 25% 차이는 통과, 더 작은 차이는 기록만 하고 플래그 없음); 위치별 시작 시간 드리프트가 2000ms를 초과하면 문제 (큐와 드리프트 명시, 정확히 2000ms 통과, 2100ms는 "2.1s"로 플래그). 드리프트는 min(소스 큐, 대상 큐) 개수의 첫 번째 큐부터 위치별로 쌍을 이루며, 시작 시간만 비교합니다.
• thumbnail.txt — 누락 또는 비어 있으면 문제.

판정: 문제가 없는 언어는 COMPLETE, 그렇지 않으면 INCOMPLETE와 문제 개수를 반환합니다. check는 모든 언어가 COMPLETE일 때만 exit 0을 반환합니다.

출력 JSON 스키마 (--json)

공통 필드: tool ("localization-packager"), version, command, project_file (파일 이름), project.

manifest: source_language, source_title, source_cues, languages — 각 {language, name, translator, folder, files}로, files는 4개의 필수 파일이며 각각 {file, what, source_fact}입니다.

check: source_cues, root, languages — 각 {language, name, translator, status ("complete" | "incomplete"), items, problems}로, items는 파일별 결과 4개 {file, ok, detail}, problems는 실패한 세부 사항 목록입니다. 또한 complete, total, all_complete 필드와 검사가 구조적임을 재확인하는 note를 포함합니다.

sheet: sheets — 대상 언어당 하나씩, 각 {language, name, translator, rows}; rows는 {n, item, timing, source, target} — 문자열 행 3개(제목, 설명, 썸네일)와 소스 큐당 행 1개(item = "cue N", timing = SRT "start --> end"); target은 항상 ""입니다 — 번역자가 채울 빈 열입니다.

오류 발생 시 stdout은 단일 객체 {"error": "<message>"}와 함께 exit 코드 2를 반환합니다. --json 모드에서 argparse 사용법 오류도 포함합니다. 일반 텍스트나 traceback은 출력하지 않습니다.

종료 코드

• 0 — 명령어 성공; check의 경우 모든 언어가 COMPLETE입니다.
• 1 — 결과 발견: check가 하나 이상의 미완료 언어를 발견했습니다. 충돌이 아닙니다 — 문제 목록은 번역자에게 보낼 수정 목록입니다.
• 2 — 오류: 프로젝트 파일 누락 또는 유효하지 않은 JSON, 필수 필드 누락, 중복 대상 언어, 소스 자막 누락 또는 파싱 불가, 알 수 없는 --language, 유효하지 않은 플래그. 실패한 실행의 출력 정보는 인용해서는 안 됩니다.

에이전트가 반드시 지켜야 할 제한 및 정직 규칙

• COMPLETE는 구조적 완료를 의미합니다 — 그 이상도 이하도 아닙니다. 이를 "번역이 정확함", "좋음" 또는 "게시 가능"으로 격상시키지 마십시오. 출시에는 여전히 해당 언어를 읽을 수 있는 사람이 필요합니다. COMPLETE 패키지를 보고할 때 이를 명시하십시오.
• INCOMPLETE는 수정 목록이지 번역자의 실패가 아닙니다. 정확한 문제(파일, 큐 번호, 드리프트, 문자 수)를 보고하십시오 — 그대로 전달할 수 있도록 작성되어 있습니다.
• 이 도구는 번역된 텍스트를 생성하지 않습니다. 시트의 대상 열은 의도적으로 비어 있습니다. 기계 번역으로 채우고 이 도구의 출력으로 제시하지 마십시오. 언어 패키지가 존재한다고 주장하려면 해당 4개 파일이 실제로 디스크에 있고 check가 실행되어야 합니다.
• 드리프트 플래그는 위치 기반입니다. 번역자가 하나의 큐를 둘로 나누면 이후 큐의 위치가 이동하여 플래그가 발생할 수 있습니다. 출력의 큐 개수 메모가 맥락을 제공합니다. 플래그만이 아니라 두 사실을 모두 보고하십시오.
• 로컬 전용: 이 도구는 프로젝트 파일, 소스 SRT, 명령줄에 지정된 패키지 폴더만 읽으며 어떤 데이터도 외부로 전송하지 않습니다.