Cerlancism/chatgpt-subtitle-translator

Efficient translation tool based on ChatGPT or any OpenAI compatible LLM chat completion API

ChatGPT API SRT 자막 번역기

무엇인가요 – OpenAI ChatGPT(또는 호환되는) API를 호출하여 SRT 자막 파일 또는 일반 텍스트를 한 줄씩 번역하는 Node.js 유틸리티입니다. 각 자막 줄과 번역 사이의 일대일 대응을 유지하면서 토큰 낭비를 최소화하도록 설계되었습니다.

왜 중요한가요 – 자막은 종종 타임스탬프가 붙은 짧은 줄들의 대량입니다. 각 줄을 별도의 요청으로 보내면 토큰 사용량이 폭발적으로 증가하고, 레이트 제한에 도달할 수 있습니다. 이 도구는 SRT의 오버헤드를 제거하고, 지능적으로 줄을 배치하며, OpenAI의 구조화된 출력 및 프롬프트 캐싱 기능을 사용하여 컴팩트하고 결정론적인 번역을 얻을 수 있습니다.

핵심 기능 (README에 설명됨)

웹 UI + CLI – 브라우저 기반 인터페이스와 명령줄 프로그램 (cli/translator.mjs)이 있습니다.
구조화된 출력 – JSON 배열, 객체, 또는 타임스탬프 인식 형식으로, 모델이 정확히 번역된 줄을 반환하도록 강제합니다.
프롬프트 캐싱 지원 – 최근 번역 기록(--context)을 선택적으로 포함하여 캐시된 프롬프트 조각을 재사용할 수 있습니다.
배치 단위의 줄 처리 – 여러 자막 줄을 하나의 요청으로 그룹화하여 줄당 토큰 오버헤드를 줄입니다.
OpenAI 모더레이션 체크 – 모델이 거부할 가능성이 있는 입력을 사전에 필터링할 수 있습니다 (--use-moderator).
스트리밍 진행 상황 – 모델이 응답을 스트리밍하는 동안 실시간 터미널 피드백을 제공합니다.
레이트 제한 처리 – OpenAI RPM 제한을 존중하며, 중단된 작업을 재시작할 수 있습니다.
에이전트 모드 – 먼저 파일 개요를 생성하고, 개선된 번역 지시를 계획한 후 번역하는 다단계 워크플로우입니다. 긴 또는 복잡한 자막에 유용합니다.
모든 OpenAI 호환 엔드포인트와 작동 – 예: 로컬 Ollama 서버.

빠른 시작 (README에서)

# 복제 및 설치
git clone https://github.com/Cerlancism/chatgpt-subtitle-translator
cd chatgpt-subtitle-translator
npm install
chmod +x cli/translator.mjs

# API 키 설정
cp .env.example .env   # 이후 .env를 편집하고 OpenAI 키를 붙여넣기

파일 번역하기

cli/translator.mjs --input mymovie.srt --from Japanese --to English

도구는 번역된 텍스트를 포함하는 새 *.srt 파일을 생성합니다.

일회성 일반 텍스트 번역

cli/translator.mjs --plain-text "안녕하세요"

출력: Hello.

내부 동작 방식

SRT 메타데이터 제거 – 인덱스와 타임스탬프는 모델에 전송하기 전에 제거됩니다 (또는 타임스탬프 모드에서는 압축됨).
배치 생성 – --batch-sizes 또는 --context 토큰 예산에 따라 자동으로 결정된 크기에 따라 줄을 그룹화합니다.
프롬프트 구성 – Translate to English (약 3 토큰)과 같은 최소한의 시스템 지시문에 더해, 배치 줄을 포함하는 JSON 페이로드를 생성합니다.
모델 호출 – 구조화된 출력 (json_schema)을 사용하면 응답이 번역된 줄의 배열/객체임이 보장됩니다.
재구성 – 반환된 번역을 원래 SRT 형식에 다시 삽입하여 타임스탬프를 유지합니다 (또는 타임스탬프 모드에서는 항목을 병합).
재시도 로직 – 모델이 다른 줄 수를 반환하면 배치 크기를 줄이고 요청을 다시 시도하여 낭비된 토큰을 방지합니다.

주목할 만한 옵션 (선택)

-r, --structured <mode> – array (기본값), object, timestamp, agent, none 중 하나를 선택합니다.
-c, --context <tokens> – 프롬프트 캐싱을 위해 이전 번역 기록에서 몇 토큰을 포함할지 지정합니다.
-b, --batch-sizes <sizes> – 명시적인 배치 크기 목록을 지정합니다. 예: 100,50,20.
--use-moderator – 배치 전에 OpenAI 모더레이션 엔드포인트를 실행합니다.
-m, --model <model> – 기본값은 gpt-4o-mini; 엔드포인트가 지원하는 모든 모델을 사용할 수 있습니다.
-t, --temperature <value> – 결정론적 번역을 위해 0으로 설정합니다.
--no-prefix-number / --no-line-matching – 엄격한 줄 대 줄 강제를 완화합니다.

제한 사항 및 고려 사항 (README에서)

도구는 OpenAI API(또는 호환 서비스)에 의존합니다. 유효한 API 키가 필요하며 토큰 비용이 발생합니다.
결정론적 출력은 temperature=0으로 설정하여 권장되지만, 특히 모호한 텍스트에서는 모델이 여전히 변동할 수 있습니다.
구조화된 출력 모드는 모델이 제공된 JSON 스키마를 이해해야 하므로, 오래된 또는 비-ChatGPT 모델은 지원하지 않을 수 있습니다.
timestamp 모드에서는 출력 줄 수가 입력과 다를 수 있습니다 (항목이 병합될 수 있음), 따라서 진행 상황 재시작이 비활성화됩니다.
큰 자막 파일은 배치 크기가 모델의 컨텍스트 창에 너무 적합하지 않을 경우 여러 번의 재시도를 유발할 수 있습니다.

누가 사용할 수 있나요

콘텐츠 제작자 – 전용 번역 서비스에 지불하지 않고도 영화나 비디오 자막을 빠르고 고품질로 번역하고 싶은 사람.
개발자 – 자막을 입력받는 파이프라인을 구축하고 프로그래머블, API 기반 번역 단계가 필요한 사람.
연구자 – LLM 기반 번역 품질을 줄 구조 데이터에서 실험하고 싶은 사람.

링크

웹 UI – https://cerlancism.github.io/chatgpt-subtitle-translator
마이그레이션 가이드 – docs/CHANGELOG.md#300-2026-03-01
OpenAI API 문서 – README 전체에 가격, 레이트 제한, 구조화된 출력에 대한 참조가 포함되어 있습니다.