b3rys-translate

b3rys translate

웹페이지 원문을 유지하면서 바로 아래에 번역을 표시하는 Chrome 확장 프로그램. YouTube 이중자막(원문 + 번역)도 지원합니다.

b3rys translate 크롬 웹스토어 가기

A bilingual translation Chrome extension — keeps the original text and shows the translation right below it, paragraph by paragraph. Works on web pages and YouTube subtitles.

License: Apache 2.0 Manifest V3 TypeScript

📋 TODO · 🤝 기여 가이드

웹페이지 번역

원문 아래에 번역이 문단 단위로 삽입됩니다. (우하단 둥둥이 버튼으로 번역 시작 — 화살표 표시)

단어 선택 번역

단어를 드래그하면 번역 + 예문이 팝업으로 표시됩니다.

YouTube 이중자막

원문 위에 번역이 함께 표시됩니다. (플레이어 하단 A가 자막 버튼으로 켜기 — 화살표 표시)

YouTube 이중자막

주요 기능

설치

두 가지 방법이 있습니다. Claude Code를 쓴다면 방법 A가 가장 빠릅니다.

⚡ 방법 A — Claude Code 스킬 (/b3translate)

Claude Code 사용자는 대화만으로 설치 → API 키 설정 → 사용법까지 안내받을 수 있습니다. git 지식 없이 아래 중 하나로 스킬을 깔면 됩니다.

① 스킬 설치 (둘 중 택1)

터미널 한 줄 (git 불필요):

curl -fsSL https://raw.githubusercontent.com/b3rys/b3rys-translate/main/install-skill.sh | bash

또는 Claude Code 채팅에 붙여넣기:

github.com/b3rys/b3rys-translate 이 번역 확장 스킬 설치해줘

② 실행

/reload-skills      # 스킬 로드 (설치 직후 1회)
/b3translate        # 실행 (또는 자연어 "번역 확장 설치해줘")

/b3translate을 실행하면 스킬이 GitHub Release의 빌드된 zip을 받아 Chrome 로드 → 엔진·API 키 설정 → 첫 번역 시연까지 대화로 안내합니다. (Node.js 불필요)

스킬은 ~/.claude/skills/b3translate/에 설치되는 개인 스킬이라 명령이 /b3translate로 깔끔합니다. 스킬 소스: skills/b3translate · 설치 스크립트: install-skill.sh

🔧 방법 B — 직접 설치 (수동)

소스에서 빌드해 개발자 모드로 로드합니다. (Chrome 웹스토어 등록 준비 중)

1. 소스 받기

git clone https://github.com/b3rys/b3rys-translate.git
cd b3rys-translate

2. 빌드

npm install
npm run build

dist/chrome-mv3 폴더에 확장 프로그램이 생성됩니다.

3. Chrome에 확장 로드 (크롬 확장 설치가 처음이어도 OK)

웹스토어 등록 전이라, 빌드된 폴더를 “압축해제된 확장”으로 직접 로드합니다.

  1. 확장 관리 페이지 열기 — 크롬 주소창에 아래를 그대로 입력하고 Enter:

    chrome://extensions

    (또는 우측 상단 ⋮ 메뉴 → 확장 프로그램 → 확장 프로그램 관리)

  2. 개발자 모드 켜기 — 페이지 우측 상단의 개발자 모드(Developer mode) 토글을 ON. 켜면 위쪽에 버튼 몇 개가 새로 나타납니다.

  3. 압축해제된 확장 프로그램을 로드합니다(Load unpacked) 버튼을 클릭.

  4. 폴더 선택 — 파일 선택창에서 방금 빌드한 dist/chrome-mv3 폴더를 고릅니다. (폴더 안으로 들어가지 말고 폴더 자체를 선택)
    • 경로 예: ~/b3rys-translate/dist/chrome-mv3

  5. 목록에 “b3rys translate” 카드가 뜨면 완료. (빨간 오류가 뜨면 폴더가 잘못된 것 — manifest.json이 들어있는 폴더를 골랐는지 확인.)

  6. 툴바에 고정(편하게 쓰려면) — 주소창 오른쪽 🧩 퍼즐 아이콘 클릭 → “b3rys translate” 옆 📌 핀 클릭 → 아이콘이 툴바에 항상 보입니다.

⚠️ 로드한 dist/chrome-mv3 폴더를 지우거나 옮기면 확장이 깨집니다 — 그대로 두세요. 코드 업데이트 후에는 chrome://extensions에서 이 확장의 새로고침(↻) 버튼을 누르면 반영됩니다.

4. API 키 설정

Chrome 툴바에서 확장 프로그램 아이콘 클릭 → 팝업에서 모델 선택 및 API 키 입력. (Model 라벨 옆 ⓘ에 마우스를 올리면 모델별 입력/출력 가격이 표시됩니다.)

모델 키 발급 위치 가격 (USD / 1M tokens, input/output)
Gemini 3.1 Flash Lite Google AI Studio $0.25 / $1.50
GPT-5.4 Nano OpenAI Platform $0.20 / $1.25
GPT-5.6 Luna OpenAI Platform $1.00 / $6.00
Claude Haiku 4.5 Anthropic Console $1.00 / $5.00

API 키는 제공사별로 독립 저장되므로 같은 제공사의 모델은 하나의 키를 공유합니다. API 키는 브라우저의 chrome.storage.local에만 저장되며 외부로 동기화되지 않습니다 (번역 요청은 사용자가 선택한 제공사 API로 직접 전송).

사용법

설치 방법과 무관하게 기능은 동일합니다.

웹페이지 번역

선택 번역

YouTube 자막 번역

비용 추적

개발

npm run dev          # 개발 모드 (HMR, Chrome 자동 로드)
npm run build        # 프로덕션 빌드
npm run test         # 전체 테스트 실행
npm run typecheck    # 타입 체크
npm run lint         # ESLint 검사
npm run format       # Prettier 포맷 적용
npm run zip          # 배포용 zip 생성

코드 수정 후 Chrome에서 확인하려면:

  1. npm run build 실행
  2. chrome://extensions에서 확장 프로그램 리로드 (↻)
  3. 대상 페이지 새로고침

기술 스택

기술 문서

코드 수정 전에 해당 영역의 문서를 먼저 읽으면 전체 구조를 빠르게 파악할 수 있습니다.

문서 내용
docs/pipeline.md 번역 파이프라인 (텍스트 감지 3단계, 필터 체인, 주입 4경로, 사이트 룰, 배치 처리)
docs/ui-guide.md UI 동작 가이드 (FAB 상태, 모드 전환, 주입 경로별 before/after, YouTube 오버레이)
docs/safety.md 안전 장치 & 상태 머신 (circuit breaker, rate limiter, 경쟁 조건 보호, Observer 룰)
TODO.md 작업 트래커

기여

버그 리포트, 기능 제안, PR 모두 환영합니다. 기여 가이드를 참고해 주세요.

라이선스

Apache License 2.0 © 2026 b3rys

재배포하거나 2차 저작물을 만들 때는 NOTICE와 LICENSE를 함께 포함하고, 원저작자(b3rys / 이 저장소)를 표기해 주세요. (Apache License §4)

This site is open source. Improve this page.