한영 타자 변환기 (Ko-Typo Converter)

🎯 이게 뭐하는 확장이에요?

키보드가 영문 상태인데 한글을 치면, 화면엔 dkssud 처럼 알 수 없는 영어가 찍히죠?

이 확장을 설치하면, 그걸 신경 쓸 필요가 없어집니다.

dkssud라고 치면 → 가만히 있어도 자동으로 안녕으로 바뀝니다. 키보드를 한/영 전환하지 않고 그냥 편하게 타이핑만 하면, 나머지는 이 확장이 알아서 처리해줍니다.

이게 이 확장의 핵심 기능이자 유일하게 중요한 기능입니다. 아래에서 자세히 설명할게요.

🚀 설치 방법

VS Code를 엽니다.
왼쪽 사이드바에서 Extensions(조각 4개 모양 아이콘)를 클릭합니다.
검색창에 "한영 타자 변환기" 또는 **"ko-typo-converter"**를 입력합니다.
Install 버튼을 클릭합니다.

이게 끝입니다. 별도 설정 없이 바로 작동합니다.

✨ 자동 변환, 이렇게 작동해요

설치하고 나면 아무것도 안 해도 됩니다. 그냥 코드를 치면서 주석이나 문자열 안에 한글을 (영문 키보드 상태로) 입력하면:

스페이스바나 엔터를 누르는 순간 → 바로 변환됩니다. (dkssud + 스페이스 → 안녕)
다 쳤는데 스페이스를 안 눌러도 → 손을 멈추면 약 0.5초 뒤에 자동으로 변환됩니다. (dkssudgktpdy라고 치고 잠깐 멈추면 → 안녕하세요)
그래도 놓쳤다면 → 파일을 저장(Ctrl+S)하는 순간 한 번 더 확인해서 변환해줍니다.

즉, 스페이스든 엔터든 저장이든, 어떻게 하든 결국엔 변환됩니다. 신경 쓰지 않고 타이핑만 하시면 됩니다.

변환까지 기다리는 시간(기본 0.5초)이 너무 빠르거나 느리게 느껴지면, 아래 설정에서 ko-typo.autoConvertDelayMs 값을 바꿀 수 있습니다.

🔁 반대 방향도 잡아줘요

반대로, 한/영 전환을 깜빡해서 코드 안의 함수 이름이나 const, console 같은 프로그래밍 용어가 한글로 잘못 쳐진 경우도 자동으로 원래 영어로 되돌려줍니다. 이 파일 안에서 이미 쓰고 있는 함수/변수 이름도 알아서 인식합니다. (주석이나 문자열 안의 한글 문장은 진짜 한글일 가능성이 높으므로 건드리지 않고, 코드 자리에서만 동작합니다.)

⚠️ 자동으로 안 바뀌는 경우도 있어요

function, error, test처럼 진짜 흔한 영단어는 일부러 변환하지 않습니다 (실수로 바뀌는 걸 막기 위해서예요).
완성되지 않은 한글 자모(예: ㅇ만 있고 아직 안 끝난 경우)는 변환 후보로 인식하지 않습니다.
반대 방향(한글 → 영어)은 이미 알려진 프로그래밍 용어이거나 이 파일에서 이미 쓰인 이름과 정확히 일치할 때만 되돌립니다. 아주 짧은 영어 단어는 한글로 조합되는 과정에서 원래 철자 일부가 사라질 수 있어서, 모든 경우를 다 잡아주지는 못합니다.

🎛️ 설정 바꾸기 (선택 사항)

기본값 그대로 써도 충분하지만, 원하면 바꿀 수 있어요.

VS Code에서 Ctrl+, (설정 열기)
검색창에 "한영 변환" 입력
아래 항목들을 원하는 대로 조정

{
  "ko-typo.autoConvert": true,           // 자동 변환 켜기/끄기
  "ko-typo.autoConvertDelayMs": 500,     // 타이핑 멈춘 후 몇 ms 뒤에 변환할지
  "ko-typo.confidenceThreshold": 50,     // 제안 표시 기준 점수
  "ko-typo.showDiagnostics": true,       // 진단(밑줄) 표시 여부
  "ko-typo.excludePatterns": [           // 변환 안 할 파일 종류
    "*.md",
    "*.txt",
    "package.json"
  ],
  "ko-typo.reverseConvert": true         // 한글 → 영어 반대 방향 자동 변환 켜기/끄기
}

🔧 그 밖의 기능 (몰라도 됩니다)

자동 변환이 핵심이고, 아래 기능들은 특수한 상황에서만 필요한 보조 기능이에요.

명령 팔레트 스캔: Ctrl+Shift+P → "한영 변환: 문서 전체 스캔"을 실행하면 파일 전체를 한번에 훑어서 놓친 오타를 찾아줍니다.
수동 단축키: 이미 쳐놓은 텍스트를 드래그로 선택한 다음 Ctrl+Shift+K (Mac은 Cmd+Shift+K)를 누르면 그 부분만 변환됩니다. 자동 변환이 대부분 알아서 처리해주기 때문에 평소에는 거의 쓸 일이 없는 기능입니다.

🧠 어떻게 이게 가능한가요? (관심 있는 분만)

2벌식 키보드 배열 기준으로, 영문 자판을 한글 자모로 재조합해서 정확한 한글 음절을 만들어냅니다.
문자열(", ', `)/주석/HTML·JSX 태그 사이 텍스트/안전하게 좁힌 괄호 안쪽처럼 "한글이 나올 만한 위치"를 구분해서 인식합니다. (자세한 조건은 아래 "최근 수정" 참고)
파일 종류(languageId)에 따라 주석 스타일도 다르게 인식합니다: JS/TS/HTML/JSX 등은 //, /* */, Python/YAML/쉘 등은 #, SQL/Lua는 --(SQL은 #, /* */도 함께), HTML/XML/마크다운은 .
점수를 쌓아 임계값을 넘기는 방식이 아니라, 실제 한글 입력기처럼 "이 자모 조합이 문법적으로 완성된 음절을 이루는가"를 기준으로 판단하기 때문에, 완성되는 즉시 바로 변환됩니다.
코드에서 자주 쓰이는 실무 한글 단어 90개 이상을 따로 학습시켜 인식률을 높였습니다.

🆕 최근 수정 (2026-09-30)

점검해보니 태그(<div>텍스트</div>)와 괄호 감지 로직이 contextDetector.js에 구현만 되어 있고 실제 변환 파이프라인에는 연결되어 있지 않았습니다(죽은 코드). 아래처럼 실제로 동작하도록 고쳤습니다.

태그 내부 텍스트 연결: HTML/XML/Vue/Svelte/Markdown/JSX/TSX 파일에서 <div>안녕하세요</div>처럼 여는 태그와 닫는 태그(</) 사이의 텍스트를 실제로 인식하고 변환합니다. 비교 연산자(a > b ... c < d)를 태그로 오인하지 않도록, 뒤에 </가 바로 오는 경우만 인정합니다. 일반 .js/.ts 파일에서는 켜지 않습니다.
괄호는 안전하게 좁혀서 연결: 소괄호 () 중에서도 (1) 여는 괄호 바로 앞이 함수/변수 이름, 닫는 괄호, 대입·비교·산술 연산자 등 "코드에 붙어있다"는 신호가 아니고, (2) 괄호 안에 쉼표·연산자 등 코드처럼 보이는 구조가 전혀 없는 "순수 텍스트 괄호"만 변환 대상으로 인정합니다. login(dkssud) 같은 함수 호출, if (a > b) { dkssud } 같은 블록문/객체 리터럴은 절대 건드리지 않습니다. 중괄호 {}와 대괄호 []는 코드와 안전하게 구분할 방법을 찾지 못해 이번에는 제외했습니다.
언어별 주석 스타일 추가: 이 확장은 VS Code에서 열린 모든 파일에 동작하는데, 지금까지는 JS 스타일(//, /* */) 주석만 인식하고 있었습니다. Python/YAML/쉘 등의 #, SQL/Lua의 --(SQL은 #와 /* */도 함께), HTML/XML/마크다운의 까지 languageId 기준으로 인식하도록 확장했습니다. (Python의 //는 정수 나눗셈이라 주석으로 취급하지 않습니다.)
반대 방향(한글 → 영어) 변환도 이 새 존(태그/안전한 괄호) 안쪽은 "진짜 한글일 수 있는 자리"로 보고 똑같이 건드리지 않도록 맞췄습니다.

참고: 이 확장 자체는 VS Code 확장이라 VS Code 안에서 파일을 열었을 때만 동작합니다 - Python 코드를 PyCharm이나 MySQL을 Workbench/터미널에서 직접 작업할 때는 동작하지 않고, 그 파일들을 VS Code로 열어야 위 언어별 주석 인식이 적용됩니다.

📁 프로젝트 구조

ko-typo-converter/
├── extension.js                 # VS Code 확장 메인 파일 (자동 변환 로직 포함)
├── hangulAssembler.js          # 2벌식 한글 조합 엔진
├── zoneDetector.js             # 주석/문자열/태그 내부 텍스트/안전한 괄호 "존" 감지 (순수 로직)
├── contextDetector.js          # 코드 컨텍스트 감지 (참고용 - 실제 존 감지는 zoneDetector.js)
├── confidenceCalculator.js     # 신뢰도 계산 로직
├── practicalWords.js           # 실무 한글 단어 목록
├── commonEnglishWords.js       # 진짜 영단어 블록리스트 (오탐 방지)
├── reverseMapper.js            # 한글 → 영어 반대 방향 조회 표 생성
├── programmingTerms.js         # 반대 방향에서 사용하는 프로그래밍 용어 사전
├── test.js                     # 순수 로직 단위 테스트 (zoneDetector 포함)
├── test/
│   ├── extension.save.test.js     # 저장 시점 안전망 테스트
│   ├── extension.debounce.test.js # 타이핑 멈춤 자동변환 테스트
│   ├── extension.reverse.test.js  # 한글 → 영어 반대 방향 변환 테스트
│   └── extension.zones.test.js    # 태그/괄호/언어별 주석 스타일 저장 파이프라인 테스트
├── package.json
├── .vscodeignore
├── LICENSE.md
└── README.md

🔧 기술 스택

Runtime: Node.js 14+
Platform: VS Code 1.60.0+
Language: JavaScript (ES6+)
Encoding: UTF-8

🧪 테스트 (개발자용)

npm test

순수 로직 테스트 37개(태그/괄호/언어별 주석 안전장치 포함) + 저장 안전망 테스트 3개 + 디바운스 자동변환 테스트 3개 + 반대 방향(한글→영어) 변환 테스트 6개 + 태그·괄호·언어별 주석이 실제 저장 파이프라인까지 이어지는지 확인하는 테스트 12개, 총 61개가 함께 실행됩니다.

🐛 알려진 제한사항

❌ 자동 완성(IntelliSense) 목록이 떠 있는 동안에는 작동하지 않을 수 있습니다.
❌ 매우 큰 파일(10MB+)에서는 느릴 수 있습니다.
❌ 단어를 치다가 중간에 잠깐 멈추는 습관이 있으면, 아직 다 안 친 단어가 먼저 변환될 수 있습니다. 이럴 땐 설정에서 ko-typo.autoConvertDelayMs 값을 늘려주세요.
❌ 괄호 인식은 소괄호 ()만 지원합니다. 중괄호 {}와 대괄호 []는 블록문/객체 리터럴/배열 등 실제 코드와 안전하게 구분할 방법이 마땅치 않아 이번 수정에서도 제외했습니다.
❌ 태그 내부 텍스트 인식은 HTML/XML/Vue/Svelte/Markdown/JSX/TSX 파일에서만 켜집니다. 일반 .js/.ts 파일에서 <, >는 대부분 비교 연산자라 오탐 위험이 커서 켜지 않습니다.
❌ VS Code 확장이므로 VS Code 밖(다른 에디터/IDE, 터미널, DB 클라이언트 등)에서 직접 파일을 편집할 때는 동작하지 않습니다. Python/SQL 등도 그 파일을 VS Code로 열었을 때만 언어별 주석 인식이 적용됩니다.

💬 피드백 & 버그 리포트

GitHub Issues 에 등록해주세요.

📜 라이선스

MIT License - 자유롭게 사용, 수정, 배포 가능

🎓 제작

작가: 장주영 (Jang Juyoung)
전공: 국악(사물놀이/풍물) → 개발자 전환

Version: 0.0.4 (베타)

🚀 향후 계획

[ ] 3벌식 한글 지원
[ ] 더 많은 도메인 단어 추가
[ ] 학습 기반 신뢰도 개선 (ML)
[ ] 다국어 지원

한영타자 변환기 (Ko-Typo Converter)

장주영