Korean IME Fix for VSCode

macOS VSCode에서 한글 입력 시 자모 분리 문제를 완전히 해결하는 확장 프로그램

![한글 입력 문제 해결]

해결 효과
설치 방법
사용 방법
설정 옵션
명령어 사용법
문제 해결
기술적 원리
지원 환경
라이선스

🚨 문제 상황

macOS의 VSCode에서 한글을 입력할 때 다음과 같은 문제가 발생합니다:

입력하고 싶은 내용

한글

실제 VSCode에 표시되는 내용

하ㄴ글
한ㅡㄹ

자모가 분리되어 표시되는 심각한 문제 입니다.

✅ 해결 효과

Before (문제 상황)

입력: "한글테스트"
결과: "하ㄴ글테ㅅ트" ❌

After (확장 프로그램 설치 후)

입력: "한글테스트"  
결과: "한글테스트" ✅

📦 설치 방법

방법 1: 직접 설치 (권장)

확장 프로그램 파일 다운로드

# 릴리즈 페이지에서 .vsix 파일 다운로드
curl -L -O https://github.com/jongsik-code/korean-ime-fix-pjs/releases/latest/download/korean-ime-fix-pjs-0.9.0.vsix

VSCode에 설치

code --install-extension korean-ime-fix-pjs-0.9.0.vsix

VSCode 재시작

# macOS에서 VSCode 완전 종료
pkill -f "Visual Studio Code"

# VSCode 재시작
code

방법 2: VSCode 마켓플레이스

VSCode 열기
확장 프로그램 패널 열기 (Cmd + Shift + X)
"Korean IME Fix" 검색
"설치" 클릭
VSCode 재시작

🎯 사용 방법

자동 활성화

확장 프로그램 설치 후 자동으로 활성화됩니다
별도 설정 없이 즉시 한글 입력이 개선됩니다

수동 제어

Command Palette (Cmd + Shift + P)에서 다음 명령어 사용:

명령어	기능
`Korean IME Fix: 한글 IME 수정 활성화`	확장 기능 활성화
`Korean IME Fix: 한글 IME 수정 비활성화`	확장 기능 비활성화
`Korean IME Fix: 상태 확인`	현재 활성화 상태 확인

⚙️ 설정 옵션

설정 파일에서 직접 수정

설정 파일 열기: Cmd + Shift + P → Preferences: Open Settings (JSON)

{
  "korean-ime-fix.enabled": true,
  "korean-ime-fix.debugMode": false
}

설정 항목 설명

설정	기본값	설명
`korean-ime-fix.enabled`	`true`	확장 프로그램 활성화/비활성화
`korean-ime-fix.debugMode`	`false`	디버그 모드 (개발자용 로그 출력)

UI에서 설정 변경

설정 열기: Cmd + ,
검색: "Korean IME Fix"
원하는 옵션 체크/해제

📋 명령어 사용법

1. 확장 기능 활성화

Cmd + Shift + P → Korean IME Fix: 한글 IME 수정 활성화

결과: ✅ 한글 IME 수정이 활성화되었습니다.

2. 확장 기능 비활성화

Cmd + Shift + P → Korean IME Fix: 한글 IME 수정 비활성화

결과: ❌ 한글 IME 수정이 비활성화되었습니다.

3. 상태 확인

Cmd + Shift + P → Korean IME Fix: 상태 확인

결과: Korean IME Fix 상태: 활성화됨 ✅

🧪 정상 작동 테스트

테스트 방법

새 파일 생성: Cmd + N

한글 입력 테스트:

안녕하세요
한글 입력이 정상적으로 됩니다
자모 분리 문제가 해결되었습니다

결과 확인: 자모가 분리되지 않고 완성된 글자로 표시

문제 지속 시 체크리스트

[ ] VSCode 완전 재시작 했는가?
[ ] 확장 프로그램이 활성화되어 있는가?
[ ] macOS 키보드 설정이 "한국어 - 2-Set Korean"인가?
[ ] VSCode 버전이 1.100.0 이상인가?

🔧 문제 해결

Q: 여전히 자모가 분리됩니다

A: 다음 단계를 순서대로 실행하세요:

VSCode 완전 재시작
```
pkill -f "Visual Studio Code"
code
```

확장 상태 확인

Cmd + Shift + P → Korean IME Fix: 상태 확인

수동으로 다시 활성화

Cmd + Shift + P → Korean IME Fix: 한글 IME 수정 활성화

Q: 확장 프로그램을 찾을 수 없습니다

A: 설치 상태 확인:

확장 프로그램 패널 열기: Cmd + Shift + X
"Korean IME Fix" 검색
설치되어 있는지 확인
비활성화되어 있다면 "활성화" 클릭

Q: 다른 에디터에서는 정상인데 VSCode에서만 문제입니다

A: 이는 VSCode의 Monaco Editor와 macOS IME 간의 호환성 문제입니다. 이 확장 프로그램이 정확히 그 문제를 해결합니다.

Q: 자동완성이 작동하지 않습니다

A: 한글 입력 최적화를 위해 일부 자동완성 기능이 조정되었습니다. 필요시 수동으로 설정을 변경할 수 있습니다:

{
  "editor.quickSuggestions": {
    "other": true,
    "comments": true,
    "strings": true
  }
}

🔬 기술적 원리

문제의 원인

VSCode의 Monaco Editor와 macOS의 IME(입력기) 간의 호환성 문제입니다.
에디터가 한글 조합 중 발생하는 composition 이벤트를 올바르게 처리하지 못해, 완성된 글자가 아닌 자모 단위로 분리되어 입력되는 현상이 발생합니다.

해결 방법

이 확장 프로그램은 VSCode의 핵심 설정을 최적화하여 이 문제를 근본적으로 해결합니다.

editor.accessibilitySupport: 'on' 설정 강제 적용
- 이 설정은 VSCode 에디터가 스크린 리더와 같은 보조 기술을 지원하도록 내부 동작을 변경합니다.
- 이 과정에서 IME 이벤트 처리 방식 또한 변경되어, 한글 조합이 정상적으로 이루어지도록 만듭니다. 이것이 문제 해결의 가장 핵심적인 원리입니다.
자동완성 기능 최적화
- 한글을 입력하는 도중, VSCode의 자동완성 및 코드 제안 기능이 나타나면서 조합 상태를 방해하는 경우가 많습니다.
- 이 확장 프로그램은 quickSuggestions, suggestOnTriggerCharacters 등 관련 기능들을 비활성화하여, 오직 한글 입력에만 집중할 수 있는 환경을 제공합니다.
유니코드 하이라이트 조정
- ㅎ ㅏ ㄴ 과 같은 한글 자모가 입력될 때, VSCode가 이를 비정상적인 문자로 간주하여 노란색으로 강조 표시하는 것을 방지합니다.

🖥 지원 환경

운영체제

✅ macOS 12.0 이상 (Monterey, Ventura, Sonoma, Sequoia)
❌ Windows (해당 문제 없음)
❌ Linux (해당 문제 없음)

VSCode 버전

✅ VSCode 1.100.0 이상
✅ VSCode Insiders
✅ Cursor (VSCode 기반 에디터)

한글 입력기

✅ macOS 기본 한글 입력기
✅ 구름 입력기
✅ 세벌식 입력기

📊 성능 영향

리소스 사용량

메모리: +2~3MB (미미한 증가)
CPU: 0% (백그라운드 동작)
배터리: 영향 없음

다른 기능에 미치는 영향

자동완성: 일부 조정됨 (필요시 수동 설정 가능)
파일 편집: 영향 없음
확장 프로그램: 영향 없음
Git 연동: 영향 없음

🤝 기여하기

버그 리포트

문제가 발생하면 다음 정보와 함께 이슈를 등록해주세요:

macOS 버전: sw_vers
VSCode 버전: code --version
문제 상황: 스크린샷 또는 동영상
재현 단계: 상세한 재현 방법

개발 참여

# 저장소 클론
git clone https://github.com/jongsik-code/korean-ime-fix-pjs.git
cd korean-ime-fix

# 의존성 설치
npm install

# 개발 모드 실행
npm run watch

# 테스트
F5 키로 Extension Development Host 실행

📄 라이선스

GPL 3.0

Copyright (c) 2025 Korean IME Fix by PJS Contributors

🔗 관련 링크

GitHub 저장소: https://github.com/jongsik-code/korean-ime-fix-pjs
VSCode 마켓플레이스: https://marketplace.visualstudio.com/items?itemName=Jongsik.korean-ime-fix-pjs
이슈 트래커: https://github.com/jongsik-code/korean-ime-fix-pjs/issues
릴리즈 노트: https://github.com/jongsik-code/korean-ime-fix-pjs/releases

📞 지원

이슈: GitHub Issues
토론: GitHub Discussions
이메일: support@korean-ime-fix.dev

⭐ 이 확장 프로그램이 도움이 되었다면 GitHub에서 Star를 눌러주세요!

설치 완료 → VSCode 재시작 → 한글 입력 테스트 → 완료! ✅

한글씹힘패치(Korean IME Fix by PJS)

Jongsik