Cerlancism/chatgpt-subtitle-translator

ChatGPT API SRT 자막 번역 도구

개요 – SRT 자막 파일 또는 일반 텍스트를 번역하기 위해 OpenAI ChatGPT(또는 OpenAI 호환) API를 호출하는 Node.js 유틸리티입니다. 자막 타이밍을 유지하기 위해 1:1 줄 대응을 엄격하게 유지하도록 설계되었습니다.

중요한 이유 – 대규모 언어 모델로 자막을 번역하는 경우 각 줄에 SRT 오버헤드(인덱스, 타임스탬프)가 포함되어 비용이 많이 들 수 있습니다. 이 도구는 오버헤드를 제거하고 줄을 지능적으로 배치하며, 선택적으로 OpenAI의 구조화된 출력 및 프롬프트 캐싱 기능을 사용하여 줄 순서를 유지하면서 토큰 사용량을 최소화합니다.

주요 기능

• 웹 UI(https://cerlancism.github.io/chatgpt-subtitle-translator 에서 호스팅) 및 모든 기능을 갖춘 CLI.
• OpenAI 구조화된 응답(array, object, timestamp, agent, none)을 지원합니다.
• --context를 통한 프롬프트 캐싱 지원으로 번역 기록을 재사용합니다.
• 모든 OpenAI 호환 엔드포인트(예: 로컬 Ollama)에서 작동합니다.
• 모델 토큰 제한을 유지하고 낭비를 줄이기 위한 줄 기반 배치 처리.
• 허용되지 않는 콘텐츠 전송을 방지하기 위한 선택적 조정 검사.
• 스트리밍 진행 상황 출력, RPM 속도 제한 처리, 재개 가능한 CLI 실행.
• 다중 패스 워크플로우를 수행하는 "에이전트 모드": 언어 감지 → 계획 요약 → 개선된 번역 지침 → 최종 번역.

작동 방식

1. 전처리 – SRT 인덱스와 타임스탬프는 원시 텍스트만 전송되도록 제거되거나 압축(Toon 형식)됩니다.
2. 배치 처리 – 줄은 토큰 예산에 맞는 JSON 배열(또는 다른 스키마)로 그룹화됩니다. 기본 시스템 프롬프트는 Translate to <target>(약 3토큰)입니다.
3. API 호출 – 배치는 ChatGPT 모델(기본 gpt-4o-mini)로 전송됩니다. 구조화된 출력은 모델이 일치하는 JSON 구조를 반환하도록 강제하여 줄별 대응을 보장합니다.
4. 후처리 – JSON 응답은 원래 타임스탬프와 인덱스를 다시 삽입하여 SRT 파일로 재조립됩니다.
5. 에이전트 모드(선택 사항) – 원본 언어를 추론하고, 콘텐츠 개요를 생성하고, 실제 번역 패스 전에 개선된 지침을 생성하기 위한 빠른 스캔을 실행합니다.

일반적인 사용법

# 일본어 SRT를 영어로 번역(CLI)
cli/translator.mjs --input subtitles.srt --from Japanese --to English

# 일회성 일반 텍스트 번역
cli/translator.mjs --plain-text "你好" --to English

# 구조화된 출력을 객체로 사용
cli/translator.mjs -r object -i subtitles.srt -o out.srt

설정 – Node ≥ 20이 필요합니다. 클론 후 npm install을 실행하고, .env.example을 .env로 복사하고, OpenAI(또는 호환) API 키를 추가하고, CLI 스크립트를 실행 가능하게 만듭니다.

대상 – 불필요한 토큰 비용을 지불하지 않고 자막 파일을 빠르게 번역해야 하는 모든 사람. 취미 비디오 편집자부터 대규모 미디어 현지화 파이프라인을 구축하는 개발자까지.