한국어와 모국어가 함께 열린다 — 이중언어 낱말카드 포털 완전 정복

🌏 다문화 가정 및 한글 미해득 학생을 위한 개별 맞춤 지도. 교사가 캔바(Canva)로 제작한 그림 카드와 함께, 한국어와 학생의 모국어(베트남어, 러시아어 등) 단어·음성을 한 장에 담은 이중언어 플래시 카드 포털을 3분 만에 생성합니다.

핵심 기술은 2중 음성 재생(TTS) — 한국어와 모국어 음성을 localService 로컬 음성으로만 연속 재생(외부 전송 0). 해당 언어 로컬 음성이 없을 때는 시각 발음 기호로 대체하는 폴백(fallback) 설계까지 갖췄습니다.

📖 한 줄 정의

심기 모드(데이터 임베딩): API 데이터를 미리 받아 HTML 파일 안 상수로 박아두는 방식(앱 실행 중 외부 통신 0).

학내망 원칙: 학교 배포 웹앱은 개인정보 수집·저장·전송 없음(외부 CDN·API 호출 0, 단일 파일) — 학생은 학내망에서 교사 PC 서버에 접속.

1. 3대 핵심 분석 비교표

무엇이 바뀌었나요? / 영역	초보자를 위한 쉬운 설명	이렇게 한번 써보세요!
3분 맞춤 제작	시판 이중언어 교구는 언어가 맞지 않거나 어휘가 어렵습니다. 교사가 캔바로 그림을 고르고 단어 5개만 상수에 넣으면 우리 아이 맞춤형 포털 완성.	교과 어휘 5단어 심기 → 개별 지도.
2중 음성 재생	카드를 누르면 '사과' 한국어 발음 → 0.6초 후 'Táo' 베트남어 발음이 연속으로 나옵니다. 로컬 음성만 골라 쓰므로 학생 정보가 나가지 않습니다.	'두 언어로 듣기' 버튼.
음성 부재 대처 (폴백)	학교 컴퓨터에 베트남어 음성이 없을 수 있습니다. 그럴 땐 앱이 스스로 감지해 시각 발음 기호(로마자)를 크게 표시합니다 — 음성이 없어도 카드는 끊기지 않습니다.	speak → '음성 없음' → 발음 기호 표시.
가정 학습 연계	단일 HTML 파일을 USB나 학급 공유 폴더로 집에 보내면, 부모님과 함께 카드를 넘기며 학습할 수 있습니다. 외부 링크·로그인·앱 설치가 전혀 없습니다.	공유 폴더 파일 배포.
원칙·정합	단일 HTML·외부 통신 0. 학생 개인 데이터는 일절 취급하지 않습니다(카드 자체만). 모국어 표기는 화자 가정 확인 루틴으로 오류를 잡습니다.	EMBED_CARDS 이중언어 상수.

2. 핵심 아키텍처 해설

① 이중언어 카드 상수

const CARDS = [
  { ko: "물", vi: "nước", lang: "vi" },
  { ko: "학교", vi: "trường học", lang: "vi" }
];

② 2중 음성 재생 (localService 로컬 음성 전용)

function speak(word, lang) {
  const voices = speechSynthesis.getVoices()
    .filter(function (v) { return v.localService; });
  const v = voices.find(function (x) {
    return x.lang.indexOf(lang) === 0;
  });
  if (!v) { showNoVoice(); return; }
  const u = new SpeechSynthesisUtterance(word);
  u.voice = v;
  speechSynthesis.speak(u);
}

localService 필터가 학내망 원칙의 심장 — 단어가 외부 서버로 절대 나가지 않습니다.

③ 음성 없을 때 폴백(fallback)

function showNoVoice() {
  label.textContent = card.ko + " / " + card.vi;   // 시각 발음 기호로 대체
  sound("soft");
}

기기에 모국어 음성이 없어도 카드는 사라지지 않고 시각 정보로 계속됩니다.

④ 그림 심기 (Base64)

const CARD_IMG = {
  "물": "iVBORw0KGgo...",
  "학교": "iVBORw0KGgo..."
};

학생이 직접 그린 그림을 스캔·내려받아 Base64(베이스64)로 심으면 외부 이미지 링크가 원천 금지됩니다.

⑤ 원칙·정합

단일 HTML·외부 통신 0. 학생 개인 데이터 일절 없음, 가정 연계는 외부 링크 대신 파일 배포(공유 폴더·USB), 모국어 표기는 화자 가정·협력자 확인 루틴으로 교정합니다.

3. 초보자를 위한 바이브 코딩 실전 사용 예시

프롬프트 복사 — 아래 '제미나이 전용 에러 제로 프롬프트' 전체를 복사해 Gemini에 붙여넣습니다.
역질문 답변 — Gemini의 질문 3가지(모국어 종류, 단어 선정, 그림 출처)에 답하면 설계가 확정됩니다.
HTML 파일 실행 — 완성 코드를 '이중언어카드.html'로 저장 후 더블클릭. USB로 가정 학습 연계.

제미나이 전용 에러 제로 프롬프트

[🚨 에러 방지 기본 안전장치]
1. 결과물은 외부 라이브러리·폰트·이미지 없이 단일 HTML 파일로 완성한다.
2. 사운드는 Web Audio API로 직접 합성한다: 카드 넘기기 부드러운 '사라라', 정답 맞힘 '딩동', 잘 들지 못했을 때 '삑'. 오디오 파일·CDN 금지.
3. 모바일 터치 대응: 뷰포트 메타 태그 필수, 카드 터치 영역 80px 이상, 360px 가로 스크롤 금지.
4. 파일 상단 CARDS 상수에 이중언어 데이터를 심는다: ko(한국어 단어), vi(모국어 단어), lang(모국어 코드). 외부 단어장 API는 절대 사용하지 않는다.
5. 음성은 speechSynthesis의 localService(로컬 음성)만 사용한다 — 온라인 음성·외부 전송 완전 금지.
6. 카드를 누르면 한국어 발음 → 0.6초 후 모국어 발음이 연속 재생되도록 만든다.
7. 모국어 로컬 음성이 기기에 없으면 스스로 감지해 시각 발음 기호(로마자)를 크게 표시하는 폴백(fallback)을 구현한다.
8. 학생 이름·정보 칸은 일절 만들지 않는다(카드 자체만 존재).
9. // TODO, /* 생략 */ 같은 미완성 코드는 절대 넣지 말고 끝까지 완성한다.

[❓ 역질문 유도]
코드를 바로 만들지 말고, 아래 3가지를 먼저 나에게 질문한 뒤 내 답변으로 설계를 확정한다.
Q1. 학생의 모국어는 무엇인가? (베트남어 / 러시아어 / 기타)
Q2. 첫 단어 세트는 어떤 주제로? (교실 낱말 / 식탁 위 낱말 / 학교 생활 낱말)
Q3. 그림은 어떻게 준비할까? (학생 직접 그린 그림 / 교사 캔바 제작)

🎯 에디터 한줄평

새 학생에게 가장 먼저 건네야 할 것은 환영이 아니라 '내 말이 교실에 등장했다'는 신호입니다. 그림 카드에 모국어가 함께 나오고, 그 모국어가 학생의 눈앞에서 소리로 되살아나는 순간, 한글 해득의 문이 열립니다. 음성이 없는 기기에서도 시각 발음 기호로 계속되는 폴백(fallback) 설계 — '모든 환경에서 포기하지 않는다'는 개별화 지도의 정신이 코드로 옮겨진 최고의 사례입니다.

📚 기술·교육 참고 링크

Canva 공식 사이트 : 그림 카드 디자인 도구 (디자인 제작 전용)
교육·행정 연계: 다문화 이해 교육·기초학력 지도 자료는 학내망 공개 자료 기준으로 활용

인문학과 바이브 코딩의 만남

2026년 9월 6일 일요일

[행정/연구 업무] 이중언어 낱말카드 포털 - 3분 만에 만드는 다문화·기초학력 개별 교구