영어 친구 — 영어 왕초보용 AI 회화 앱

AI 친구와 영어로 수다 떨며 듣기 → 따라 말하기 → 읽기 → 쓰기를 연습하는 웹 앱입니다. 완전 초보(A1)부터 원어민 수준(C2)까지 6단계 교육과정을 따라 AI의 말투와 도움의 양이 바뀝니다. React + Vite + TypeScript로 만들었고, AI는 Gemini API(무료 키)를 브라우저에서 바로 부릅니다. 서버는 없습니다.

바로 쓰기 (Vercel)

1. 이 코드가 main 브랜치에 있어야 정식 주소가 로그인 없이 열립니다. (다른 브랜치는 무료 플랜에서 미리보기 주소라 Vercel 로그인이 필요합니다.)
2. vercel.com에서 Add New → Project → grapevine26/vvv Import.
3. Framework Preset이 Vite로 자동 선택되는지 확인하고 Deploy. Root Directory 등 다른 설정은 그대로 둡니다.
4. 생긴 https://○○.vercel.app 주소를 열고 키 넣고 시작하기를 누릅니다. 화면 안내대로 Gemini 키를 받아 붙여 넣고 저장하고 시작하기를 누르면, 키가 맞는지 먼저 확인한 뒤 바로 첫 대화가 시작됩니다.

Gemini 키는 Google AI Studio에서 무료로 받습니다. 복사할 때 따옴표나 공백이 같이 붙어도 앱이 알아서 떼어 냅니다. Vercel 환경 변수(Environment Variables)에 키를 넣지 마세요. 이 앱은 서버가 없어서 쓰이지도 않고, 페이지에 끼워 넣으면 누구나 키를 보게 됩니다.

내 컴퓨터에서 돌리기 (Windows)

Node.js 22 이상이 필요합니다. PowerShell에서:

npm install
npm run dev

브라우저에서 http://localhost:5173을 엽니다. 코드를 고치면 화면이 자동으로 바뀌어서 다시 켤 필요가 없습니다.

테스트

npm test                          # 문장 나누기·비교, AI 응답 처리 등 로직 테스트
npx playwright install chromium   # 처음 한 번만
npm run test:e2e                  # 빌드한 앱으로 화면 흐름 테스트 179개 (AI·마이크·스피커는 가짜)
npm run lint                      # 코드 검사

쓰는 법

화면 아래 안내 줄이 지금 할 일을 알려 줍니다: 생각 중 → 친구가 말하는 중 → 내 차례.

하는 일	방법
대답하기	눌러서 한국어로 말하기 버튼을 누르고 말해도 됩니다. AI가 쉬운 영어 문장으로 바꿔 줍니다. 다 말했으면 버튼을 한 번 더 누르면 바로 보내집니다.
잘못 눌렀을 때	듣는 중에 ✕ 취소를 누르면 보내지 않고 멈춥니다. 다른 언어 버튼을 누르면 그 언어로 바꿔 다시 듣습니다.
따라 말하기	노란 칸에 문장이 나오면 EN 버튼(파랗게 강조됨)을 누르고 따라 말합니다. 비슷하게 말하면 "잘 들렸어요 👍"가 붙습니다.
대답이 막힐 때	질문 아래 "이렇게 대답해도 돼요" 칩을 누르면 들립니다. 그대로 EN 버튼으로 말하면 됩니다. (칩을 읽은 것은 '따라 말하기'로 세고, 승급 기준의 '스스로 한 대답'에는 넣지 않습니다.)
말 멈추기·다시 듣기	친구가 말하는 중엔 ■ 그만, 말풍선의 🔊 다시 / 🐢 천천히
손 안 쓰고 하기	설정에서 친구 말이 끝나면 바로 듣기를 켜면 버튼을 안 눌러도 마이크가 켜집니다.
키보드	아래 입력칸에 한국어·영어 아무거나 써도 됩니다.
응답이 늦을 때	8초가 지나면 그만 기다리기 버튼이 나옵니다. 20초가 지나면 저절로 멈추고 다시 시도할 수 있습니다.
오류가 났을 때	오류 말풍선의 키 다시 넣기 / 모델 이름 고치기 / 다시 시도 버튼을 누르면 고칠 곳이 바로 열립니다.
마무리	끝내기(또는 휴대폰 뒤로 가기) → 오늘 문장 듣고 소리 내어 읽기 → 한국어 뜻 보고 영어로 써 보기 → 저장하고 끝내기
중간에 꺼졌을 때	대화는 15초마다 임시 저장됩니다. 다시 열면 이어서 하기 / 저장하고 닫기 / 버리기를 고릅니다.
복습	저장한 문장은 내 문장 노트에 모입니다. 시작 화면 오늘 할 일의 "하러 가기"로 듣고 따라 하는 복습을 하고, 오래된 문장은 다음 대화에서 AI가 다시 쓰게 합니다.
교육과정	시작 화면 카드에 오늘 단원과 다음 단계까지 남은 조건이 보입니다. 교육과정에서 단원을 고르거나 단계를 바꿉니다.
폰 ↔ PC	시작 화면 폰↔PC 옮기기 → 내보내기로 코드를 복사해 카톡 "나와의 채팅"으로 보내고, 다른 기기에서 가져오기에 붙여 넣습니다. 내 문장 노트·설정·진도가 합쳐집니다(Gemini 키와 목소리는 기기마다 따로).

더 연습하기 (시작 화면)

연습	하는 일	왜
대화 전 2분 연습	오늘 단원의 문장 틀 2~3개를 듣고, 따라 하고, 빈칸 단어를 바꿔 말해 봅니다 (AI 안 씀)	대화에서 "뭐라고 하지?"로 막히지 않게
5분 복습 퀴즈	내 문장 노트의 문장으로 듣고 뜻 고르기·뜻 보고 말하기·단어 순서 맞추기. 맞히면 다음 복습이 1→2→4→7→15일 뒤로 (AI 안 씀)	잊을 때쯤 다시 꺼내야 오래 기억에 남아서
듣고 따라 말하기	AI가 내 단계에 맞는 30초 이야기를 만들고, 한 문장씩 듣고 따라 말합니다. 마음에 드는 문장은 내 문장 노트에 저장	말하기만큼 듣기 양이 필요해서
이번 주 기록	7일 공부 시간 막대, 주별 '영어로 스스로 대답한 비율'	늘고 있는 걸 눈으로 보면 계속할 힘이 나서
발음 피드백	따라 말하기에서 덜 들린 단어를 빨간 밑줄로 표시	무엇을 다시 연습할지 바로 알게
기록 백업	폰↔PC 옮기기 화면에서 파일로 저장 / 파일에서 되살리기. 일주일 넘게 안 하면 시작 화면이 알려 줍니다	기록이 이 브라우저에만 있어서, 크롬 기록을 지우거나 폰을 바꾸면 사라지기 때문

카톡 안 화면에서는 파일이 저장되지 않으니 내보내기 코드를 카톡 "나와의 채팅"에 보내 두세요. 옮기기 코드와 백업 파일에는 퀴즈 복습 일정도 들어갑니다.

휴대폰에 앱처럼 깔기 (안드로이드)

크롬에서 주소를 열고 오른쪽 위 ⋮ → 홈 화면에 추가(또는 앱 설치) 를 누르면 아이콘이 생기고 주소창 없이 열립니다. 카카오톡에서 링크를 누르면 카톡 안 브라우저로 열리는데, 거기선 마이크가 잘 안 됩니다. 화면 위 크롬으로 열기를 누르세요. 크롬이 안 열리면 그 아래 다른 브라우저로 열기를 누르고, 삼성 인터넷이 열리면 오른쪽 아래 메뉴에서 크롬으로 엽니다(브라우저마다 저장이 따로라 한 곳만 쓰는 게 좋아요). 카톡 안에서 이미 쓰던 기록이 있으면 먼저 폰↔PC 옮기기 → 내보내기로 코드를 복사해 두라고 화면이 알려 줍니다. 대화 중에는 화면이 꺼지지 않게 해 둡니다.

교육과정

단계	목표	처음부터 보통 걸리는 시간*	다음 단계 조건 (최근 대화 5번 기준)
1 첫걸음 (A1)	짧은 표현으로 나에 대해 말하기	90~100시간	단원 10개 · 영어로 스스로 대답 50% · 평균 3단어
2 기초 대화 (A2)	어제 한 일과 계획을 여러 문장으로	180~200시간	단원 10개 · 80% · 평균 5단어
3 자립 대화 (B1)	막히지 않고 이야기 이어 가기, 상황극	350~400시간	단원 10개 · 95% · 평균 8단어
4 자신감 있는 대화 (B2)	의견을 근거와 함께 길게, 원어민 속도	500~600시간	단원 10개 · 95% · 평균 12단어
5 유창한 대화 (C1)	표현을 골라 쓰고 말투 바꾸기	700~800시간	단원 10개 · 95% · 평균 15단어
6 원어민 수준 (C2)	속어·유머·문화 맥락·뉘앙스	1,000~1,200시간	—

* Cambridge English의 CEFR 누적 수업 시간 안내치. 한국어 화자는 더 걸릴 수 있고, 앱 대화만으로는 부족합니다. 단계마다 **하루 루틴(약 1시간)**에 듣기·읽기를 넣어 두었습니다.

• 단계가 오를수록 AI 문장이 길어지고, 한국어 뜻·대답 예시·따라 말하기가 줄고, 고쳐 주기가 "되받아 말하기"에서 "💡 팁으로 바로 알려 주기"로 바뀝니다.
• 한 대화에서 5번 이상 주고받고(한국어 대답도 셈) 저장하고 끝내기를 누르면 그 단원을 마친 것으로 칩니다. 다음 단계로 올라가는 조건은 '영어로 스스로 한 대답' 비율과 길이로 따로 봅니다.
• 단계를 바꾸면 말 속도·뜻 보이기·따라 말하기 양이 그 단계에 맞춰집니다. 이미 실력이 있으면 교육과정에서 높은 단계로 바로 바꿔도 됩니다.
• 단계별 규칙과 단원은 src/lib/curriculum.ts 한 파일에 있습니다.

「AI 원어민 회화 친구 v0.2」 뼈대에서 바꾼 점

바꾼 것	이유
질문마다 쉬운 대답 예시 2개	왕초보는 영어 문장을 지어낼 수 없어서, 고르고 따라 하게 해야 입이 열린다
한국어 뜻과 모를 만한 단어를 항상 같이	뜻을 모르면 듣기가 그냥 소음이 된다
글자를 바로 보여 줌 (설정에서 "소리 먼저"로 바꿀 수 있음)	어른은 글자를 같이 볼 때 소리를 더 잘 잡는다
마이크 2개 (한 / EN)	브라우저 음성 인식은 한 번에 한 언어만 알아듣는다
한국어 신호와 영어를 다른 목소리로 나눠 읽기	한 목소리로 읽으면 영어 목소리가 한국어를 읽어 버린다
틀린 말은 지적 없이 맞는 문장으로 되받기	부담 없이 맞는 형태를 계속 듣게 된다
문법 대신 통째로 쓰는 틀 ("I'm ~", "I want ~")	문법을 몰라도 바로 쓸 수 있다
마무리에서 뜻 보고 써 보기 + 다음 대화에서 복습	떠올려 보고, 날을 바꿔 다시 쓸 때 기억에 남는다
모델 이름을 설정에서 바꿀 수 있게	모델은 자주 바뀐다. 코드에 박혀 있으면 몇 달 뒤 멈춘다

폴더 구조

src/
  App.tsx              대화 흐름 (시작·주고받기·마무리·저장·임시 저장·뒤로 가기)
  components/          화면 조각 (시작 화면, 말풍선, 마이크 버튼, 설정·마무리·내 문장 노트·교육과정·옮기기 시트)
  hooks/               React 도우미
  lib/
    curriculum.ts      교육과정: 단계별 규칙·단원·승급 기준 ← 난이도는 여기서 고친다
    prompt.ts          AI에게 주는 지시문 (교육과정 단계·단원을 끼워 넣는다)
    gemini.ts          Gemini 호출, 오류 안내, 응답 다듬기
    speech.ts          말하기(음성 합성)·듣기(음성 인식)
    text.ts            한/영 나누기, 문장 비교
    session.ts         대화 한 번을 내 문장 노트·진도에 반영
    storage.ts         설정·내 문장 노트·진도·임시 저장 (브라우저, 여러 탭 안전)
    transfer.ts        다른 기기로 옮기기 코드 만들기·읽기
    config.ts          기본 설정값
public/                아이콘, 홈 화면 설치용 manifest
e2e/                   화면 흐름 테스트 (Playwright): 첫 실행·대화·세션·교육과정/내 문장 노트/옮기기·고친 문제 회귀, helpers.ts에 가짜 AI·마이크·스피커

어디에 무엇이 저장·전송되나

• 이 기기(브라우저): 설정, API 키, 내 문장 노트, 교육과정 진도, 하다 만 대화(임시 저장), 오늘 할 일 체크. 같은 브라우저를 쓰는 사람은 볼 수 있습니다. 기기마다 따로 저장되므로 휴대폰에서는 키를 한 번 더 넣습니다.
• 구글: 크롬 음성 인식은 소리를 구글 서버에서 글자로 바꿉니다. 대화 내용은 Gemini로 갑니다. 무료 키로 한 대화는 구글이 서비스 개선에 쓸 수 있으니 개인정보는 말하지 마세요.

잘 안 될 때

• 키를 넣었는데 "API 키가 맞지 않아요" → AI Studio에서 키 전체를 다시 복사합니다. 키는 보통 AIza로 시작합니다.
• "모델을 찾을 수 없어요" → 오류 말풍선의 모델 이름 고치기를 눌러 바꿉니다 (예: gemini-3.5-flash-lite, gemini-3.8-flash).
• 마이크가 안 됨 → 시작 화면의 마이크 안내를 따라 허용합니다. PC 크롬은 주소창 왼쪽 아이콘, 안드로이드는 크롬 설정 → 사이트 설정 → 마이크(홈 화면 앱이면 휴대폰 설정 → 애플리케이션 → Chrome → 권한)입니다. 카카오톡 안 브라우저라면 크롬으로 엽니다. 파이어폭스는 음성 인식을 지원하지 않습니다.
• 폰과 PC에서 동시에 열었음 → 기기마다 저장이 따로라 서로 덮어쓰지 않습니다. 끝나면 폰↔PC 옮기기로 합칩니다. 같은 기기의 탭 두 개는 서로 기록을 지키며, 다른 탭에서 대화 중이면 시작 화면에 알려 줍니다.
• "이 대화는 다른 탭에서 이어받았거나 저장했어요" → 오래 뒤에 둔 탭의 대화를 다른 탭에서 저장하거나 이어서 한 경우입니다. 기록은 한 번만 남아 있으니 그대로 새로 시작하면 됩니다.
• "무료 사용량을 다 썼거나…"(429) → 1분쯤 뒤 다시 하거나, 다음 날 씁니다.
• 목소리가 어색함 → 설정에서 목소리를 바꿉니다. 엣지에서는 이름에 "Natural"이 붙은 목소리가 자연스럽습니다.
• AI 말이 너무 어렵거나 길다 → 교육과정에서 단계를 낮추거나, src/lib/curriculum.ts의 그 단계 규칙을 고칩니다.