클로드 코드로 만드는 실시간 AI 통역기

 

AI HANDS-ON GUIDE

클로드 코드로 만드는 실시간 AI 통역기
— 제미나이 3.5 라이브 트랜슬레이트 API 활용 가이드

코드를 직접 짜는 대신, AI 코딩 에이전트인 클로드 코드(Claude Code)에게 제미나이 Live API 통역기 구현을 맡기는 실전 워크플로를 단계별로 정리했습니다.

 

목차

• 1무엇을 만들고, 누가 무엇을 맡나
• 2사전 준비물 체크
• 31단계 — 설치와 API 키 설정
• 42단계 — 클로드 코드에 줄 작업 지시문
• 53단계 — 생성되는 코드의 핵심 구조 이해
• 64단계 — 실행·테스트와 반복 개선
• 7트러블슈팅 — 자주 막히는 지점
• 8한 단계 더 — CLAUDE.md와 확장 아이디어
• 9참고 링크

1. 무엇을 만들고, 누가 무엇을 맡나

목표는 "마이크에 대고 말하면 한국어 통역 음성이 실시간으로 나오는 프로그램"을 내 컴퓨터에서 직접 돌려보는 것입니다. 통역 엔진은 구글의 제미나이 3.5 라이브 트랜슬레이트(Gemini Live API의 gemini-3.5-live-translate-preview 모델)가 맡고, 코드 작성·실행·디버깅은 클로드 코드(Claude Code)가 맡습니다.

클로드 코드는 터미널(명령창)에서 동작하는 AI 코딩 에이전트입니다. 한국어로 요구사항을 적어 주면 프로젝트 폴더 안에서 직접 파일을 만들고, 라이브러리를 설치하고, 실행하고, 오류가 나면 스스로 고칩니다. 즉 이 가이드에서 사람이 직접 작성하는 코드는 사실상 없고, 좋은 지시문을 쓰는 것이 작업의 핵심입니다.

구성 요소	역할	비유하자면
제미나이 Live API	음성을 받아 번역 음성을 돌려주는 통역 엔진	통역사
클로드 코드	통역 엔진에 연결되는 프로그램을 작성·실행·수정하는 코딩 에이전트	개발자 직원
파이썬 + pyaudio	내 컴퓨터에서 마이크·스피커를 다루는 실행 환경	작업장과 장비
사용자(나)	요구사항 지시, 테스트, 피드백	발주자 겸 검수자

STEP 1

환경 준비

설치 + API 키 2개

→

STEP 2

작업 지시

클로드 코드에 프롬프트

→

STEP 3

코드 생성

통역기 자동 구현

→

STEP 4

실행·개선

테스트 후 피드백 반복

2. 사전 준비물 체크

준비물	내용
클로드 코드 이용 자격	Claude 유료 플랜 계정 또는 Anthropic API 과금 계정이 필요합니다 (무료 플랜에는 클로드 코드가 포함되지 않음). 자세한 플랜 조건은 공식 문서 확인
Node.js 18 이상	npm 방식으로 클로드 코드를 설치할 때 필요. 운영체제별 네이티브 설치 프로그램을 쓰면 Node.js 없이도 설치 가능 (공식 설치 문서 참고)
Gemini API 키	Google AI Studio(aistudio.google.com/apikey)에서 구글 계정으로 발급. 통역 모델은 현재 퍼블릭 프리뷰 단계
Python 3.10 이상	구현 언어. 공식 SDK인 google-genai와 마이크·스피커 입출력용 pyaudio를 사용
마이크 + 이어폰	이어폰은 필수에 가깝습니다 — 스피커로 통역 음성을 틀면 그 소리가 마이크로 재유입(루프)되어 통역이 꼬입니다

필요한 API 키는 두 개입니다. 클로드 코드용 인증(Anthropic 계정 로그인)과 통역 엔진용 Gemini API 키 — 역할이 다른 별개의 자격증명이라는 점만 구분하면 준비는 끝입니다.

3. 1단계 — 설치와 API 키 설정

(1) 클로드 코드 설치와 실행

터미널 명령 — 설치와 첫 실행 # 1) 클로드 코드 설치 (npm 방식 — Node.js 18 이상 필요) npm install -g @anthropic-ai/claude-code # 2) 작업 폴더를 만들고, 그 폴더 안에서 클로드 코드 실행 mkdir live-translator cd live-translator claude

첫 실행 시 브라우저가 열리며 Anthropic 계정 로그인을 안내한다. Node.js 없이 설치하는 운영체제별 네이티브 설치 방법은 공식 설치 문서(참고 링크) 참조. 설치 확인은 claude --version.

(2) Gemini API 키 발급과 환경변수 등록

aistudio.google.com/apikey에서 키를 발급받은 뒤, 코드에 직접 적지 말고(하드코딩 금지) 환경변수로 등록합니다. 구글 공식 SDK는 GEMINI_API_KEY라는 이름의 환경변수를 자동으로 읽기 때문에, 이렇게 해 두면 코드 어디에도 키가 노출되지 않습니다.

환경변수 등록 # macOS / Linux — 현재 터미널에 적용 # (영구 적용하려면 같은 줄을 ~/.zshrc 또는 ~/.bashrc 에 추가) export GEMINI_API_KEY="여기에_발급받은_키" # Windows (PowerShell) — 시스템에 영구 등록 # (등록 후 반드시 '새 터미널'을 열어야 적용됨) setx GEMINI_API_KEY "여기에_발급받은_키"

키가 GitHub 등에 올라가는 사고의 대부분은 하드코딩에서 시작된다. 환경변수 등록은 보안의 최소 기본값이다.

4. 2단계 — 클로드 코드에 줄 작업 지시문

이 단계가 전체 작업의 품질을 결정합니다. 클로드 코드에 "통역기 만들어 줘"라고만 하면 모델명·오디오 규격을 추측하게 되므로, 공식 문서의 스펙을 요구사항으로 명시해 줍니다. 아래 지시문을 claude 실행 화면에 그대로 붙여 넣으면 됩니다.

클로드 코드 프롬프트 — 그대로 복사해서 사용 제미나이 3.5 라이브 트랜슬레이트로 실시간 음성 통역기를 만들어 줘. [요구사항] 1. Python 3.10 이상, google-genai SDK, pyaudio 사용 2. 모델: gemini-3.5-live-translate-preview (Gemini Live API) 3. 마이크 입력을 16kHz·16비트·모노 PCM으로 캡처해서 100ms(0.1초) 조각 단위로 스트리밍 전송 4. translationConfig 설정: targetLanguageCode는 "ko", echoTargetLanguage는 false 5. 번역 음성(24kHz)은 스피커로 즉시 재생하고, 입력 자막과 번역 자막을 터미널에 함께 출력 6. API 키는 GEMINI_API_KEY 환경변수에서만 읽을 것 (하드코딩 금지) 7. 마이크 권한 오류, 네트워크 끊김, Ctrl+C 종료를 안전하게 처리 8. 모든 코드에 한국어 줄 주석을 달 것 9. 실행 방법과 의존성 설치 명령을 README.md로 정리할 것 [참고 문서] — 코드를 쓰기 전에 먼저 읽고 최신 스펙을 반영할 것 https://ai.google.dev/gemini-api/docs/live-api/live-translate

공식 문서 URL을 지시문에 포함하는 것이 요령이다. 클로드 코드가 문서를 직접 읽고 프리뷰 모델의 최신 스펙을 반영하므로, 학습 시점 차이로 인한 오류가 줄어든다.

▶ 지시문 작성 3원칙

(1) 모델명·규격 등 숫자로 확정할 수 있는 것은 모두 명시한다. (2) 보안 규칙(키는 환경변수)과 예외 처리(권한·네트워크·종료)를 요구사항에 포함한다. (3) 나중에 직접 고칠 수 있도록 한국어 줄 주석과 README를 함께 요청한다.

5. 3단계 — 생성되는 코드의 핵심 구조 이해

클로드 코드가 만들어 주더라도 뼈대는 이해하고 있어야 검수와 수정 요청이 가능합니다. 통역기의 핵심은 "보내는 일과 받는 일을 동시에" 하는 구조입니다. 아래는 공식 문서의 파이썬 예제를 바탕으로 한 핵심 골격입니다 (마이크·스피커 입출력 세부 구현은 클로드 코드가 채우는 영역).

※ 동작 환경: Python 3.10+ / 의존성 google-genai, pyaudio / macOS·Windows·Linux. pyaudio는 시스템에 PortAudio 라이브러리가 없으면 설치가 실패할 수 있습니다(7번 트러블슈팅 참조).

핵심 골격 코드 (Python) — 줄 주석 포함 # 설치: pip install google-genai pyaudio import asyncio # 송신·수신 동시 처리를 위한 비동기 라이브러리 from google import genai # 제미나이 공식 SDK from google.genai import types # 설정 객체 모음 client = genai.Client() # GEMINI_API_KEY 환경변수를 자동으로 읽음 (키 하드코딩 금지) MODEL = "gemini-3.5-live-translate-preview" # 실시간 통역 전용 프리뷰 모델 config = types.LiveConnectConfig( response_modalities=["AUDIO"], # 응답을 '음성'으로 받음 input_audio_transcription=types.AudioTranscriptionConfig(), # 입력 음성 자막 켜기 output_audio_transcription=types.AudioTranscriptionConfig(), # 번역 음성 자막 켜기 translation_config=types.TranslationConfig( target_language_code="ko", # 목표 언어: 한국어 (입력 언어는 자동 감지) echo_target_language=False # 이미 한국어인 입력은 침묵 처리 ) ) async def main(): # 세션 열기 — 이 블록 안에서 주고받는 모든 것이 실시간 스트림 async with client.aio.live.connect(model=MODEL, config=config) as session: async def send_mic(): # [송신] 마이크의 16kHz·16비트·모노 PCM을 0.1초 조각으로 계속 전송 for chunk in capture_mic_chunks(): # ← 의사코드: pyaudio 캡처 부분 (클로드 코드가 구현) await session.send_realtime_input( audio=types.Blob(data=chunk, mime_type="audio/pcm;rate=16000")) async def receive_audio(): # [수신] 번역 음성(24kHz)과 자막을 받아 재생·출력 async for resp in session.receive(): sc = resp.server_content if sc and sc.input_transcription: print("[들은 내용]", sc.input_transcription.text) # 입력 받아쓰기 if sc and sc.output_transcription: print("[통역 자막]", sc.output_transcription.text) # 번역 자막 # sc.model_turn.parts 안의 inline_data가 번역 음성 조각 → 스피커 재생 await asyncio.gather(send_mic(), receive_audio()) # 송신과 수신을 '동시에' 실행 asyncio.run(main())

구글 공식 문서의 예제(Apache 2.0 라이선스)를 한국어 통역 시나리오로 각색·주석화한 골격이다. capture_mic_chunks()와 스피커 재생부는 pyaudio로 채워야 하는 부분으로, 2단계 지시문이 바로 이 부분을 클로드 코드에 맡기는 것이다.

검수 포인트는 네 가지입니다 — ① 모델명 철자, ② 입력 16kHz·출력 24kHz, ③ 100ms 청크 전송, ④ 키를 환경변수에서 읽는지. 이 네 가지만 맞으면 나머지는 동작하면서 다듬으면 됩니다.

6. 4단계 — 실행·테스트와 반복 개선

클로드 코드가 파일을 만들면 같은 화면에서 그대로 "의존성 설치하고 실행해 줘"라고 지시합니다. 직접 실행한다면 pip install google-genai pyaudio 후 python main.py 순서입니다. 이어폰을 끼고 외국어로 말해 보거나, 외국어 유튜브 영상을 틀어 두고 통역 자막·음성이 나오는지 확인합니다.

오류가 나면 해결을 시도하기 전에 오류 메시지를 통째로 복사해 클로드 코드에 붙여넣는 것이 가장 빠릅니다. 클로드 코드는 자기가 만든 코드의 맥락을 알고 있으므로 원인 추적과 수정까지 한 번에 처리합니다. 동작이 확인되면 다음과 같은 개선을 한 문장씩 추가 지시하면 됩니다.

• "목표 언어를 실행 시 인자로 선택할 수 있게 해 줘 (예: python main.py --lang en)"
• "입력 자막과 통역 자막을 시간과 함께 텍스트 파일로 저장해 줘"
• "통역 시작·종료를 단축키로 제어할 수 있게 해 줘"

7. 트러블슈팅 — 자주 막히는 지점

증상	원인과 해결
pyaudio 설치 실패	시스템에 PortAudio가 없는 경우가 대부분. macOS는 brew install portaudio 후 pip 재시도, Ubuntu·Debian은 sudo apt install portaudio19-dev 후 재시도. Windows는 보통 pip만으로 설치됨
인증 오류 (키를 못 읽음)	환경변수 등록 후 새 터미널을 열지 않은 경우가 흔함. macOS·Linux는 echo $GEMINI_API_KEY, PowerShell은 echo $env:GEMINI_API_KEY로 값이 보이는지 확인
통역이 꼬이거나 같은 말이 반복됨	스피커로 나온 번역 음성이 마이크로 재유입되는 루프 현상. 이어폰을 사용하면 해결
소리가 늘어지거나 끊김	재생 측 샘플레이트가 24kHz로 설정돼 있는지, 전송 청크가 100ms 단위인지 확인. 클로드 코드에 "출력 재생을 24kHz로 맞춰 줘"라고 지시
모델을 찾을 수 없다는 오류	모델명 철자 확인 (gemini-3.5-live-translate-preview). 프리뷰 모델은 이름·스펙이 바뀔 수 있으므로 오류 지속 시 공식 문서에서 현재 모델명 재확인
텍스트를 입력해도 반응 없음	정상 동작. 이 모델은 음성 입력 전용으로, 텍스트 입력은 지원하지 않음

8. 한 단계 더 — CLAUDE.md와 확장 아이디어

(1) CLAUDE.md — 프로젝트 규칙을 못 박아 두기

프로젝트 폴더에 CLAUDE.md 파일을 만들어 두면 클로드 코드가 매 세션 시작 시 자동으로 읽고 규칙으로 따릅니다. 통역기 프로젝트라면 다음 네 줄이면 충분합니다 — "API 키는 GEMINI_API_KEY 환경변수에서만 읽는다 / 모델명은 gemini-3.5-live-translate-preview로 고정한다 / 오디오 규격은 입력 16kHz·출력 24kHz·100ms 청크를 유지한다 / 모든 코드에 한국어 줄 주석을 단다." 이렇게 해 두면 며칠 뒤 다시 작업을 이어가도 같은 규칙이 유지됩니다.

(2) 확장 아이디어

• 양방향 통역기 : 한→영 세션과 영→한 세션을 동시에 열어 대면 상담용 양방향 통역 구성
• 회의 기록 연동 : 통역 자막을 시간순으로 저장해 회의록 초안으로 활용
• 웹 앱화 : 검증된 로직을 임시 토큰(ephemeral token) 방식의 웹 앱으로 확장 — 브라우저에서 키 노출 없이 서비스 가능

▶ 비용·운영 주의

Gemini Live API는 사용량 기반 과금이며 프리뷰 모델은 요금·스펙이 변경될 수 있습니다. 장시간 세션을 돌리기 전에 공식 요금 페이지에서 현재 단가를 확인하고, 테스트는 짧은 세션으로 시작하는 것을 권장합니다. 클로드 코드 역시 플랜별 사용 한도가 있으므로 대규모 작업 전에 플랜 조건을 확인해 두면 좋습니다.

실무 적용 관점 — 이 구성은 "통역기 완제품"이라기보다 조직 내부용 시제품(프로토타입)을 하루 만에 만들어 보는 방법입니다. 외국인 고객 상담 데스크, 해외 파트너 화상 미팅 보조 등 도입을 검토 중인 시나리오가 있다면, 본격 개발 전에 이 방식으로 통역 품질과 지연 시간을 직접 검증해 보는 용도로 적합합니다.

9. 참고 링크

• 통역 APIGoogle AI for Developers — Live translation with Gemini Live API (공식 가이드)
• 통역 APIGemini 3.5 Live Translate 모델 페이지
• 키 발급Google AI Studio — Gemini API 키 발급
• 요금Gemini API 공식 요금 페이지
• 예제 코드GitHub — Gemini Live API 공식 예제 저장소
• 클로드 코드Claude Code 공식 문서 (개요)
• 클로드 코드Claude Code 설치·시스템 요구사항 문서
• 클로드 코드npm 패키지 — @anthropic-ai/claude-code

※ 설치 명령·플랜 조건·모델 스펙은 공식 문서 기준으로 작성했으며(확인 기준일 : 2026-06-13), 프리뷰 단계 제품 특성상 변경될 수 있습니다. 막히면 위 공식 문서를 먼저 확인하세요.