문서 작업 가이드
가져오기 전 텍스트 파일 인코딩 감지하기
CSV·로그·소스·내보내기 파일의 decoder를 고르기 전에 BOM, 엄격한 UTF-8, NUL 배치, 제어 바이트와 모호성을 검사합니다.
작성 및 검수 SimpleWebUtils게시일: 검토일:
이 작업 흐름을 검증한 방법
바이트 증거로 텍스트 파일 인코딩 감지에서 “UTF-32LE 내보내기를 UTF-16LE 접두사와 구분” 픽스처를 임의로 고치거나 단순화하지 않고 실행했습니다. “정확한 바이트를 수동 검사”에서 “모호한 결과를 그대로 유지”로 이어지는 결과를 대조했습니다. 비성공 경로 검토에는 “ASCII 호환을 ASCII 원본으로 해석”, “Continuation 형태만 보고 UTF-8 허용” 조건을 사용했습니다.
4바이트 FF FE 00 00 표식과 code unit 구조로 UTF-32LE를 판별했고, 더 짧은 UTF-16LE 접두사만 보고 검사를 끝내지 않았습니다.
문제 상황
가져오기 프로그램은 column, delimiter, record를 해석하기 전에 바이트를 문자로 바꿔야 합니다. 이 decoder가 원본과 다르면 화면에 name으로 보이는 header 앞에 숨은 U+FEFF가 붙거나 Zürich가 Zürich로 변하고, 한글·일본어·중국어가 무관한 기호 조합으로 깨질 수 있습니다. .csv나 .txt 확장자는 신뢰할 문자셋 정보를 담지 않으며, 편집기에서 파일을 여는 순간 자동으로 디코딩하고 저장하면서 원본 증거가 바뀔 수도 있습니다. 감지에도 한계가 있습니다. BOM은 강한 서명이지만 이후 모든 code unit이 유효함을 보장하지 않고, 표시 가능한 ASCII 바이트는 UTF-8과 여러 레거시 인코딩이 공유하며, 비슷한 단일 바이트 문자셋은 예상 텍스트나 생성 프로그램 정보 없이는 구분할 수 없습니다. 따라서 안전한 가져오기는 원본 보존, 정확한 바이트 기록, 확정과 추정 분리, 목적지의 소량 검증 순서로 진행해야 합니다.
공식 출처와 표준
다음 공식 문서는 이 작업 흐름에서 다루는 형식과 보안 경계의 기준입니다. 도구별 실행 검증은 위에 별도로 기록합니다.
- Encoding Standard
WHATWG
이럴 때 사용하세요
- 스프레드시트, 데이터베이스, ETL 가져오기 뒤 CSV header, 고객 이름, accent, symbol, CJK field가 바뀔 때 사용합니다.
- 수신 시스템이 UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE 또는 BOM 없는 stream을 요구할 때 필요합니다.
- 소스나 번역 저장소를 UTF-8로 통일하기 전에 기존 파일을 감사할 때 적용합니다.
- 파일 종류가 불명확한 첨부물을 디코딩하기 전에 텍스트 가능성과 바이너리 의심으로 나눌 때 사용합니다.
- 편집기의 인코딩 label이 아니라 공급자나 데이터 pipeline 장애에 재현 가능한 바이트 보고서가 필요할 때 적합합니다.
단계
- 1단계
손대지 않은 원본과 목적지 요구사항 보존
파일을 열거나 저장하기 전에 byte-for-byte 복사본을 만듭니다. 가져오기 프로그램이 허용하는 정확한 인코딩 이름, BOM 필수·금지 여부, 정상 디코딩에서 복원돼야 할 값 하나 이상을 기록합니다.
- 2단계
정확한 바이트를 수동 검사
문자셋 감지기에서 원본 파일을 선택하고 검사를 실행합니다. 확장자와 MIME label은 증거로 쓰지 않으며 보고서의 바이트 수와 선두 24바이트 16진수부터 확인합니다.
- 3단계
서명, 구조, 추정 분리
0번 바이트의 EF BB BF, FE FF, FF FE, 00 00 FE FF, FF FE 00 00은 확정 BOM 증거로 봅니다. 완전한 서명 뒤에도 잘못된 데이터가 있을 수 있으므로 엄격한 UTF-8과 UTF-16·UTF-32 구조 결과를 별도로 읽습니다.
- 4단계
모호한 결과를 그대로 유지
ASCII 호환은 같은 바이트를 여러 인코딩이 만들 수 있다는 뜻입니다. 레거시·단일 바이트 후보는 강한 바이너리 증거 없이 엄격한 UTF-8이 실패했다는 뜻일 뿐 Windows-1252, ISO-8859-1, Shift_JIS를 확정하지 않습니다.
- 5단계
통제된 decoder 후보 비교
바이트 증거와 생성 시스템 정보가 지지하는 decoder부터 시도합니다. 알려진 header, accent, 이름, delimiter, replacement character를 비교하고 대안을 시험하는 동안 원본을 덮어쓰지 않습니다.
- 6단계
목적지에서 소량 가져오기
ASCII, accent, CJK, emoji, 빈 field, 따옴표 delimiter가 포함된 대표 row 몇 개를 가져옵니다. 전체 작업 전에 보이는 텍스트와 첫 field 이름을 모두 검증합니다.
- 7단계
검증 후 한 번만 변환
원본 decoder와 목적지 계약이 확인되면 출력 인코딩을 명시해 한 번 변환합니다. 결과 바이트를 다시 검사하고 rollback을 위해 원본과 변환 기록을 보관합니다.
예시
UTF-32LE 내보내기를 UTF-16LE 접두사와 구분
입력
customers.bin
선두 바이트: FF FE 00 00 69 00 00 00 64 00 00 00
예상 첫 field: id출력
분류: UTF-32 LE
증거: 4바이트 BOM 확정, UTF-32 구조 유효
FF FE만 보고 UTF-16LE로 분류하지 않음
다음 단계: UTF-32LE decoder로 id header를 소량 검증흔한 실수
확장자나 MIME type 신뢰
.csv와 text/plain은 형식 의도일 뿐 바이트와 문자의 대응을 정하지 않습니다. stream과 생성 계약을 확인해야 합니다.
ASCII 호환을 ASCII 원본으로 해석
표시 가능한 ASCII 바이트는 유효한 UTF-8이며 여러 레거시 문자셋과 겹치므로 원래 label은 알 수 없습니다.
Continuation 형태만 보고 UTF-8 허용
Overlong sequence, surrogate 표현, 잘린 sequence, U+10FFFF 초과 값은 일부 continuation byte가 그럴듯해도 유효하지 않습니다.
바이너리에 텍스트 디코딩 강제
신뢰할 Unicode lane을 만들지 않는 NUL과 제어 바이트는 바이너리일 수 있습니다. 디코딩 전에 파일 종류를 확인하세요.
목적지 표본 검증 생략
로컬 preview가 그럴듯해도 스프레드시트, 데이터베이스, ETL이 같은 decoder와 BOM 규칙을 쓴다는 보장은 없습니다.
자주 묻는 질문
BOM은 확정인데 구조는 왜 유효하지 않을 수 있나요?
서명 바이트는 의도한 Unicode 인코딩 방식을 식별합니다. 뒤의 잘림, 짝이 없는 UTF-16 surrogate, 잘못된 UTF-32 scalar를 막지는 못합니다.
영문 텍스트는 왜 ASCII 호환으로 남나요?
같은 바이트가 ASCII, UTF-8, Windows-1252, ISO-8859 계열과 다른 ASCII 호환 인코딩에서 같은 문자를 나타내므로 원래 label을 복원할 수 없습니다.
NUL 바이트가 UTF-16이나 UTF-32를 증명하나요?
아니요. 길이가 충분하고 ASCII 비중이 높은 텍스트에서 endian별 NUL lane과 유효한 code unit 구조가 함께 있으면 추정 근거가 되지만 바이너리에도 NUL은 있습니다.
유효한 UTF-8 파일은 모두 변환해야 하나요?
아니요. 목적지가 현재 파일의 BOM 정책과 내용을 받아들이면 변환은 이득 없이 위험만 늘릴 수 있습니다.
검사를 위해 원본 파일을 업로드하나요?
아니요. 정상 검사는 브라우저에서 파일을 읽으며 집계 event에는 파일명과 내용이 들어가지 않습니다.
가져오기 장애 기록에는 어떤 증거를 남겨야 하나요?
민감한 row를 노출하지 말고 source hash, 바이트 수, 선두 hex, BOM, 엄격한 UTF-8 결과, 선택한 decoder, 목적지 설정과 검증된 표본 결과를 기록하세요.