PKC 해례 Haerye - 11개 언어를 지원하는 한국어 학습 PWA 오픈소스 프로젝트

 

안녕하세요, PKC입니다! 👋

오늘은 약 한 달간의 개발 끝에 완성한 **한국어 학습 웹앱 "Haerye(해례)"**를 소개하려고 합니다. GitHub에 오픈소스로 공개했으며, 누구나 무료로 사용하실 수 있습니다.

🎯 프로젝트 개요

Haerye는 외국인 학습자들을 위한 올인원 한국어 학습 플랫폼입니다. 초급부터 중급 초반까지의 체계적인 학습 경로를 제공하며, PWA(Progressive Web App) 기술을 활용해 앱처럼 사용할 수 있습니다.

• 웹사이트: https://www.haerye.com/
• GitHub: https://github.com/PKC0412/Haerye
• 라이선스: GPLv3 (비상업적 용도 무료)

✨ 주요 기능

1. 체계적인 학습 모듈

• 한글 학습: 자음 19개, 모음 21개, 받침 학습
• 어휘 학습: 15개 카테고리, 300개 이상의 단어
  • 인사, 음식, 사람, 장소, 학교, 시간, 교통, 숫자, 색상, 신체, 자연, 형용사, 동사 등
• 문법 학습: 11개 카테고리로 체계적으로 구성
  • 조사, 시제, 부정, 비교, 조건, 연결, 어미, 인용, 태, 문장 구조
• 플래시카드: 간격 반복 학습 시스템 (Spaced Repetition)
• 학습 통계: 일일/주간 트렌드, 숙련도 분석, 개인화된 추천

2. 11개 언어 지원 🌍

전체 UI와 학습 콘텐츠가 11개 언어로 번역되어 있습니다:

🇬🇧 English | 🇩🇪 Deutsch | 🇪🇸 Español | 🇫🇷 Français | 🇮🇹 Italiano
🇯🇵 日本語 | 🇳🇱 Nederlands | 🇵🇹 Português | 🇷🇺 Русский | 🇹🇭 ไทย | 🇨🇳 中文

3. PWA 기능

• ✅ 부분 오프라인 지원 (Service Worker)
• ✅ 홈 화면에 설치 가능
• ✅ 빠른 로딩 속도
• ✅ 자동 라이트/다크 모드
• ✅ TTS 발음 지원 (Web Speech API)
• ✅ 반응형 디자인 (PC/모바일 최적화)

🛠 기술 스택

프레임워크를 사용하지 않고 순수 Vanilla JavaScript로 개발했습니다:

 

text

- Frontend: Vanilla JavaScript (ES6+) - Styling: CSS3 (CSS Variables, Grid, Flexbox) - PWA: Service Worker, Web App Manifest - API: Web Speech API (TTS) - Storage: LocalStorage - Hosting: GitHub Pages

왜 Vanilla JS인가?

1. 가벼운 용량: 프레임워크 오버헤드 없이 빠른 로딩
2. 긴 수명: 프레임워크 업데이트에 종속되지 않음
3. 학습 목적: 브라우저 네이티브 API 깊이 있게 활용
4. 완전한 제어: 모든 코드에 대한 완벽한 이해와 제어

📁 프로젝트 구조

모듈형 아키텍처로 관심사를 명확히 분리했습니다:

 

 

js/
│
├─ core/              (핵심 시스템)
│  ├─ app.js          (앱 초기화)
│  ├─ ui-manager.js   (UI 컨트롤러)
│  ├─ settings.js     (설정 관리)
│  ├─ theme.js        (테마 전환)
│  └─ ...
│
├─ renderers/         (UI 렌더링)
│  ├─ header-renderer.view.js
│  ├─ nav-renderer.js
│  ├─ stats-renderer.js
│  └─ ...
│
└─ features/          (학습 기능)
   ├─ hangul-learning.js
   ├─ vocabulary-learning.js
   ├─ grammar-view.js
   ├─ flashcard.js
   └─ ...

 

총 파일 통계:

• JavaScript: 27개 모듈
• CSS: 15개 파일
• 번역 파일: 187개 (11개 언어 × 17개 파일)

🎨 개발 과정에서 중요하게 생각한 점

1. 모듈화와 유지보수성

각 기능을 독립적인 모듈로 분리해 유지보수와 확장을 쉽게 만들었습니다. 예를 들어:

• learning-progress.model.js: 데이터 모델
• learning-progress.storage.js: 저장소 로직
• learning-progress.runtime.js: 런타임 로직

2. 국제화(i18n) 시스템

11개 언어를 지원하기 위해 자체 i18n 시스템을 구축했습니다. 모든 텍스트는 JSON 파일로 관리되며, 언어 전환 시 즉시 반영됩니다.

 

 

// locales/en/en.json
{
  "home.title": "Learn Korean Easily",
  "vocabulary.greeting": "Greetings",
  ...
}

3. 학습 통계 시스템

LocalStorage를 활용해 사용자의 학습 데이터를 추적하고, 다음을 제공합니다:

• 📊 일일/주간 학습 트렌드 그래프
• 📈 카테고리별 단어 숙련도
• 🔥 문법 학습 히트맵
• 💡 개인화된 학습 추천

4. TTS 발음 지원

Web Speech API를 활용해 브라우저 내장 한국어 TTS를 사용합니다. 다만 iOS Safari에서는 제약이 있어, 사용자 가이드를 상세히 작성했습니다.

🚀 로컬에서 실행하기

 

 

# 저장소 클론
git clone https://github.com/PKC0412/Haerye.git
cd Haerye

# Python 서버 실행
python -m http.server 8000

# 또는 Node.js
npx http-server -p 8000

# 브라우저에서 접속
# http://localhost:8000

📱 PWA 설치 방법

Android (Chrome)

1. 웹사이트 접속 후 메뉴(⋮) → "홈 화면에 추가"
2. 홈 화면에서 앱처럼 실행

iOS (Safari)

1. Safari에서 접속
2. 공유 버튼(⬆️) → "홈 화면에 추가"

Desktop (Chrome/Edge)

1. 주소창의 "설치" 버튼 클릭
2. 독/작업 표시줄에 앱 아이콘 추가

🔮 향후 계획

현재 기획 중인 기능들입니다:

• 받아쓰기 학습 (Dictation)
• 발음 평가 시스템 (Web Speech API 활용)
• 상황별 회화 시나리오
• 단어 확장 (300개 → 1,200개+)
• 퀴즈 시스템 강화
• 오디오 예문 추가

💡 개발하면서 배운 점

1. PWA의 강력함

네이티브 앱 개발 없이도 앱과 유사한 경험을 제공할 수 있다는 점이 인상적이었습니다. Service Worker를 통한 오프라인 지원, 홈 화면 설치 등 PWA의 가능성을 실감했습니다.

2. Vanilla JS의 충분함

프레임워크 없이도 대규모 웹앱을 충분히 개발할 수 있습니다. 오히려 브라우저 네이티브 API를 깊이 이해하게 되어 더 효율적인 코드를 작성할 수 있었습니다.

3. 국제화의 중요성

초기부터 i18n을 염두에 두고 설계하니, 11개 언어 지원이 생각보다 어렵지 않았습니다. 다국어 지원은 글로벌 사용자 확보에 필수적입니다.

🐛 알려진 이슈

• 언어 전환 버그: 간혹 언어 전환이 작동하지 않을 수 있습니다 → 새로고침(F5)으로 해결
• iOS TTS 제한: Safari의 autoplay 정책으로 첫 발음이 재생되지 않을 수 있습니다 → 두 번 탭하면 작동

📜 라이선스

Dual License Policy를 따릅니다:

• 비상업적/오픈소스 용도: GPLv3 (무료 사용, 포크, 재배포 가능)
• 상업적 용도: 별도 라이선스 필요

문의: pkc0412@gmail.com

🙏 마치며

약 한 달간의 개발 끝에 첫 버전을 공개하게 되었습니다. 완벽하지는 않지만, 외국인 학습자들이 한국어를 체계적으로 배울 수 있는 좋은 출발점이 되었으면 합니다.

프로젝트에 관심 있으신 분들은 GitHub에서 ⭐ 스타를 눌러주시거나, 이슈나 PR을 통해 기여해주시면 감사하겠습니다!

프로젝트 링크:

• 웹사이트: https://www.haerye.com/
• GitHub: https://github.com/PKC0412/Haerye

질문이나 제안사항이 있으시면 언제든지 연락 주세요! 😊