typos 한국어 안내

대상 사용자: 소스 코드·주석·README의 영문 오타를 검사하려는 프로그래머. Windows x64용 공식 실행 파일을 기준으로 합니다. 한국어 문법·맞춤법 검사기나 코드 컴파일러는 아닙니다.

1. 다운로드 구성과 출처

게시물 첨부는 두 개입니다.

typos-v1.51.1-x86_64-pc-windows-msvc.zip: 공식 릴리스에서 받은 변경 없는 원본 ZIP. typos.exe, README, 문서, LICENSE-MIT·LICENSE-APACHE가 포함됩니다. 설치 마법사 없이 압축을 푸는 포터블 구성입니다.
typos-1.51.1-ko-guide-practice.zip: 이 한국어 설명서와 직접 작성한 작은 실습 파일, 검증 스크립트. 실행 파일은 첫 번째 공식 원본 ZIP에만 들어 있습니다.

공식 원본: https://github.com/crate-ci/typos/releases/tag/v1.51.1

Windows x64 직접 다운로드: https://github.com/crate-ci/typos/releases/download/v1.51.1/typos-v1.51.1-x86_64-pc-windows-msvc.zip

공식 저장소: https://github.com/crate-ci/typos

설정 문서(동일 버전): https://github.com/crate-ci/typos/blob/v1.51.1/docs/reference.md

기준일은 2026-10-23이며 본문은 v1.51.1에 맞췄습니다. 원본 SHA-256은 GitHub 릴리스 자산 메타데이터의 digest와 대조했습니다.

518f759fba43205f17a717656054c1d25bc883455a6296989e9d021c6edb7c59

라이선스는 MIT 또는 Apache-2.0 선택형입니다. 공식 ZIP 안의 저작권·라이선스·문서를 그대로 보존해 재배포합니다. 첨부는 제작사가 배포한 원본이며 사이트에서 다시 빌드한 파일이 아닙니다. 해시 일치는 원본 동일성 검사이며 제작사의 전자서명이나 보안 인증을 대신하지 않습니다.

2. 설치: 두 ZIP을 각각 압축 풀기

Windows 설정 → 시스템 → 정보에서 시스템 종류가 x64인지 확인합니다. 이 첨부는 x64용이며 ARM64·다른 운영체제는 공식 릴리스에서 맞는 자산을 선택합니다.
첫 ZIP을 원하는 작업 폴더의 tool 하위 폴더에 풉니다. tool/typos.exe와 두 LICENSE 파일을 함께 둡니다.
두 번째 ZIP은 같은 작업 폴더의 guide 하위 폴더에 풉니다. 그 안에 README-ko.md, examples, Test-Lab.ps1이 있어야 합니다.
그 작업 폴더에서 PowerShell을 열고 다음 명령을 실행합니다. typos-cli 1.51.1이 나오면 실행 파일 확인이 끝납니다. 관리자 권한이나 PATH 등록은 필요하지 않습니다.

Get-FileHash .\typos-v1.51.1-x86_64-pc-windows-msvc.zip -Algorithm SHA256
.\tool\typos.exe --version

실제 ZIP을 다른 위치에 보관했다면 첫 명령의 경로를 바꿉니다. 압축 폴더 안에서 바로 실행하지 말고 파일을 먼저 풉니다. 공백이 있는 경로는 & "C:\My Tools\typos.exe" --version처럼 호출 연산자와 따옴표를 씁니다.

3. 검사 → 차이 확인 → 복사본 수정

아래에서 before.txt에는 recieve the adress, corrected.txt에는 receive the address가 들어 있습니다. --isolated는 상위 폴더 설정의 영향을 줄여 실습 결과를 일정하게 만듭니다.

.\tool\typos.exe --isolated .\guide\examples\before.txt
$LASTEXITCODE
.\tool\typos.exe --isolated .\guide\examples\before.txt --diff
Copy-Item .\guide\examples\before.txt .\guide\examples\work.txt
.\tool\typos.exe --isolated .\guide\examples\work.txt --write-changes
Get-Content .\guide\examples\work.txt
.\tool\typos.exe --isolated .\guide\examples\work.txt
$LASTEXITCODE

첫 검사는 recieve → receive, adress → address 두 항목을 보고하고 종료 코드 2를 반환합니다. --diff는 파일을 바꾸지 않고 예상 차이를 보여 줍니다. 이 버전의 실습에서는 --diff가 0을 반환했으므로 이를 오타 유무 판정에 쓰지 않습니다. --write-changes만 복사본에 수정 내용을 기록하고, 마지막 일반 검사는 출력 없이 0을 반환합니다.

실제 프로젝트에서는 먼저 일반 검사와 diff를 검토합니다. 공개 API 이름, 통신 프로토콜 문자열, 호환성이 필요한 필드를 일괄 변경하면 기능이 달라질 수 있으므로 수정 대상과 테스트 범위를 정한 뒤 적용합니다. typos는 알려진 영문 오타를 찾는 도구이므로 통과 결과가 모든 단어와 코드의 정확성을 보장하지 않습니다.

4. 자동 검사와 예외 단어

프로젝트 경로를 명시하면 현재 폴더를 잘못 검사하는 일을 줄일 수 있습니다. 아래는 사용자의 프로젝트에 맞게 경로를 바꾸는 예시입니다.

.\tool\typos.exe .\my-project --format json
$LASTEXITCODE

JSON 모드 출력은 한 개의 큰 배열이 아닌 줄 단위 JSON입니다. 일반 검사에서 0은 발견된 오타 없음, 2는 오타 발견이고 그 외 코드는 실행·설정 오류로 구분합니다. CI에서는 기본 검사 모드와 종료 코드를 사용하고, diff 출력을 오타 발견 여부 대신 사용하지 않습니다.

성씨나 프로젝트 고유어가 의도된 표기라면 _typos.toml에 단어를 그대로 등록할 수 있습니다. 예제는 teh를 의도한 표기로 허용합니다. 일반 영어 문장 전체에서 이 오타를 허용하려는 경우에는 적용하지 마세요.

[default.extend-words]
teh = "teh"

.\tool\typos.exe --isolated .\guide\examples\surname.txt
$LASTEXITCODE
.\tool\typos.exe --config .\guide\examples\_typos.toml .\guide\examples\surname.txt
$LASTEXITCODE

첫 검사는 2, 설정을 지정한 검사는 0입니다. _typos.toml 자동 탐색 또는 --config를 실제 운용에 사용하고, 실습의 --isolated를 그대로 넣어 프로젝트 설정을 무시하지 않도록 합니다.

5. 반복 검증 스크립트

Test-Lab.ps1은 예제 옆 practice-run 폴더에만 수정용 복사본을 만들고, 공식 실행 파일은 변경하지 않습니다. 실습 원본도 보존합니다.

.\guide\Test-Lab.ps1 -TyposPath .\tool\typos.exe

파일을 읽어 본 뒤 로컬 정책이 허용할 때 실행합니다. 조직 정책이 스크립트를 차단하면 정책을 우회하지 말고 위 수동 명령을 사용하세요. 검증 스크립트는 오타 2건 탐지, JSON 두 줄, diff의 원본 보존, 복사본 수정, 재검사, 예외 설정을 확인하고 PASS: 7 checks를 출력합니다.

6. 문제 해결

증상	확인할 내용
`typos`를 찾을 수 없음	PowerShell 현재 폴더 실행은 `typos` 대신 `.\tool\typos.exe` 등 명시 경로를 사용합니다.
실행 파일이 열리지 않음	x64 여부, 완전한 압축 해제, 보안 제품의 차단 사유를 확인합니다. 공식 출처와 SHA-256을 대조하고 무조건 차단을 해제하지 않습니다.
오타가 있어도 결과 없음	`typos 경로 --files`로 검사 대상 포함 여부를 봅니다. ignore 파일·제외 설정·숨김 파일 여부와 알려진 오타 사전의 한계를 확인합니다.
예외 단어가 계속 지적됨	`_typos.toml`의 TOML 문법·섹션·경로를 확인하고 `--config`로 파일을 지정합니다. `--dump-config -`로 유효 설정을 봅니다.
자동 검사에서 실패	일반 모드의 2는 오타 발견입니다. 0 외의 값을 모두 같은 실행 오류로 처리하지 말고 표준 오류와 코드별 의미를 확인합니다.
JSON 파서가 실패	JSON Lines이므로 줄마다 파싱합니다. 사람이 읽는 일반 출력과 섞지 않습니다.
한국어 문장이 교정되지 않음	이 도구는 한국어 맞춤법 검사 용도가 아닙니다. 코드·문서 속 알려진 영문 오타 검사에 사용합니다.

7. 확인 범위와 실습 파일 권리

이 안내는 Windows x64에서 공식 v1.51.1 실행 파일을 직접 실행해 버전, 오타 탐지, JSON, diff, 수정, 정상 재검사, 설정 예외를 확인했습니다. 실제 사용자의 저장소·CI에 적용한 결과는 아닙니다. 온라인 서비스 가입이나 소스 업로드 없이 로컬 파일을 검사할 수 있습니다.

직접 작성한 examples·Test-Lab.ps1·한국어 안내는 동봉한 LICENSE-JIOT.txt의 MIT 조건으로 재사용할 수 있습니다. 프로그램 자체의 권리는 공식 원본 안의 별도 라이선스를 따릅니다.