문서 작업 가이드

재현 가능한 텍스트 픽스처와 장식 샘플을 안전하게 준비하기

Unicode 안전 구조 변환을 선택하고 seed와 출력 상한을 기록하며, 부분 표준·장식 텍스트를 접근 가능한 운영 본문과 분리합니다.

작성 및 검수 게시일: 검토일:

이 작업 흐름을 검증한 방법

텍스트 변환 워크벤치에서 “다국어 단어 셔플 픽스처를 안정적으로 만들기” 픽스처를 임의로 고치거나 단순화하지 않고 실행했습니다. “원문을 보존하고 민감 정보를 제거합니다”에서 “생성 조건과 증가 상한을 고정합니다”로 이어지는 결과를 대조했습니다. 비성공 경로 검토에는 “변환 결과만 저장하기”, “Unicode를 코드 유닛으로 뒤집기” 조건을 사용했습니다.

저장한 fixture는 seed 42의 정확한 shuffle 결과와 mode·locale·원문 version·byte 수·browser 날짜를 묶고, 구두점 slot과 줄바꿈 두 개를 보존했습니다.

문제 상황

텍스트 픽스처는 흔히 채움 문구를 만들고, 라벨을 뒤집고, 단어를 섞고, 표식을 반복하고, 점자를 보여주거나 강한 장식을 넣어 달라는 짧은 요청에서 시작합니다. 하지만 그 요청에는 재현성과 안전성을 결정하는 선택이 빠져 있습니다. JavaScript 코드 유닛은 표시 그래핌을 찢을 수 있고, 단어 작업은 구두점과 줄 끝을 없앨 수 있으며, seed 없는 난수는 스크린샷과 버그 보고를 매번 바꿉니다. 반복과 결합 부호는 예상보다 크게 늘고, FIGlet은 인쇄 가능한 ASCII만 받으며, 영어 1급 점자 부분집합은 번역이나 접근 가능한 촉각 배치가 아닙니다. 미러·거꾸로·Zalgo는 읽지 못하거나 복원하지 못할 수 있습니다. 계약을 적지 않으면 폐기용 시각 샘플이 운영 본문으로 섞이거나 기능과 무관한 텍스트 차이 때문에 테스트가 실패합니다.

이럴 때 사용하세요

  • 스크린샷, 시각 회귀 테스트, 컴포넌트 스토리 또는 목업에 정확히 다시 만들 수 있는 자리표시문이 필요할 때
  • 다국어 테스트에서 구두점과 공백을 정규화하지 않고 그래핌·단어·줄을 뒤집거나 섞어야 할 때
  • 터미널 예시나 README에 짧은 FIGlet 제목이 필요하고 접근성용 일반 제목도 유지할 때
  • 번역이나 인증이라고 주장하지 않고 문서화된 영어 1급 점자 부분집합을 학습 예제로 확인할 때
  • 평문 원본과 명시한 상한을 유지하며 미러·거꾸로·반복·Zalgo 장식 실험을 만들 때

단계

  1. 1단계

    변환 전에 산출물의 역할을 분류합니다

    결과가 테스트 픽스처, 문서 예시, 터미널 장식, 학습 샘플 또는 운영 사용자에게 보이는 본문인지 적습니다. 소비 환경과 실패 비용을 명시합니다. 운영 본문은 보통 평문으로 유지해야 합니다. 효과·글꼴·결합 부호·배치가 사라져도 지시, 이름, 안전 정보, 제어 상태 또는 유일한 접근 가능 라벨이 숨지 않을 때만 장식을 사용합니다.

  2. 2단계

    원문을 보존하고 민감 정보를 제거합니다

    수정하지 않은 원문을 안정된 픽스처 이름이나 버전과 함께 보관합니다. 테스트에 필요 없는 비밀, 고객 데이터, 운영 식별자, 저작권 자료를 제거합니다. 로컬 브라우저 처리는 워크벤치가 원문을 업로드하지 않는다는 뜻이지만 클립보드 기록, 다운로드 파일, 스크린샷, 확장 프로그램, 저장소와 테스트 보고서는 여전히 내용을 노출할 수 있습니다. 보이지 않는 문자가 테스트 증거인지 판단하기 전 정규화하거나 제거하지 마십시오.

  3. 3단계

    구조 단위와 로케일을 명시합니다

    결합 부호와 연결 이모지가 함께 움직여야 하면 Intl.Segmenter 그래핌을 선택합니다. 구두점, 반복 공백과 줄바꿈 위치가 유지되어야 하면 단어 슬롯을 선택하고 영어·한국어·일본어 분절을 기록합니다. CRLF·LF·CR 슬롯이 중요하면 논리 줄을 사용합니다. 전체 단위를 뒤집는지, 각 단어 내부만 뒤집는지, 구분자를 고정한 채 값을 섞는지 분명히 적습니다.

  4. 4단계

    생성 조건과 증가 상한을 고정합니다

    Lorem, Shuffle, Zalgo에서는 결과를 보기 전에 부호 없는 32비트 seed와 모든 옵션을 기록합니다. seed는 같은 배포 알고리즘의 재현성을 주지만 보안 난수가 아닙니다. 반복은 횟수와 구분자 의도를 계산하고 2 MiB 출력 선검사를 지킵니다. 사용자 구분자는 UTF-8 256바이트, Lorem 수량 100, 반복 10,000회, Zalgo 원문 32,768 코드 포인트, 혼돈 수준 1~10 이내로 둡니다.

  5. 5단계

    형식별 지원 범위를 적용합니다

    FIGlet은 인쇄 가능한 ASCII 96자와 3줄 안으로 두고 평문 제목을 함께 유지합니다. 점자는 대문자·숫자·1급·일반 구두점 기호를 가진 제한된 영어 1급 비축약 부분집합으로 취급하며 언어 번역, 축약 점자, 촉각 배치, 수학·음악 점자 또는 인증에 쓰지 않습니다. 미러와 거꾸로 표는 글꼴 의존 근사로 보고, Zalgo는 접근성 스트레스 샘플로만 사용해 테스트에 필요한 방향만 선택합니다.

  6. 6단계

    전체 결과와 계약을 함께 검증·보관합니다

    전용 Worker를 실행하고 입출력 UTF-8 바이트, Unicode 코드 포인트, 모드별 개수, 미지원 문자 알림, seed와 접근성 경고를 확인합니다. 화면 미리보기는 50,000 코드 포인트에서 멈추므로 전체 제한 결과는 복사하거나 내려받습니다. 정확한 안정성이 중요하면 같은 계약을 다시 실행하고 Diff Checker로 비교한 뒤 원문, 모드, 옵션, seed, 브라우저 날짜, 기대 결과와 평문 대체 내용을 함께 저장합니다.

예시

다국어 단어 셔플 픽스처를 안정적으로 만들기

입력

목적: 카드가 구두점과 줄바꿈 2개를 보존하는지 테스트. 원문: ‘one,  two!
안녕 세계
東京 テスト’. 계약: 단어 슬롯 셔플, 한국어 분절, seed 42, 수정하지 않은 원문 보관, 운영 데이터 없음.

출력

정확한 셔플 결과를 seed 42, 모드, 로케일, 원문 버전, UTF-8 바이트 수, 브라우저 날짜, 기대 구두점·줄바꿈 슬롯과 함께 저장합니다. 단어는 슬롯을 바꿀 수 있지만 쉼표, 두 칸 공백, 느낌표와 두 줄바꿈은 원래 구조 위치를 유지합니다.

흔한 실수

seed를 안전한 난수라고 부르기

결정적 의사난수는 반복 가능한 픽스처에는 유용하지만 비밀번호, 토큰, 식별자, 추첨, 통계 보장이 필요한 표본 또는 보안 결정에는 맞지 않습니다. 그런 목적에는 검증된 암호학적 API와 별도 검토 절차를 사용합니다.

변환 결과만 저장하기

원문, 모드, 단위, 로케일, 옵션, seed, 알고리즘 버전과 기대 상한이 없으면 나중의 차이를 진단할 수 없습니다. 출력이 스스로 설명한다고 보지 말고 변환 계약을 픽스처 옆에 둡니다.

Unicode를 코드 유닛으로 뒤집기

UTF-16 split은 결합 악센트, surrogate pair, 연결 이모지를 분리할 수 있습니다. 표시 단위에는 그래핌 역순을 선택하고 결합 문자, 이모지, 한국어와 일본어 사례를 픽스처에 포함합니다.

부분 점자를 접근 가능한 변환이라고 제시하기

검증한 영어 1급 부분집합은 언어 번역, 축약, 배치, 모든 구두점 규칙, 수학·음악 점자 또는 독자 요구를 다루지 않습니다. 원문을 보관하고 중요한 점자는 실제 목표 표준과 자격 있는 독자가 확인해야 합니다.

장식이 의미를 대신하게 두기

FIGlet 간격, 미러 치환, 거꾸로 기호와 결합 부호는 다른 글꼴·화면 폭·검색·클립보드·보조 기술에서 무너질 수 있습니다. 같은 맥락에 일반 텍스트를 표시하고 유일한 명령·상태·안전 문구를 장식 안에 숨기지 않습니다.

자주 묻는 질문

스냅샷 테스트에서 실행할 때마다 Lorem seed를 바꿔야 하나요?

아닙니다. 단어 자체가 중요하지 않으면 seed 하나를 골라 기록하고, 다양성이 테스트 행렬에 필요하면 이름 붙인 seed 여러 개를 정의합니다. 매번 새 seed를 쓰면 무관한 스냅샷 변경이 생기고 의미 있는 레이아웃 회귀를 숨길 수 있습니다.

그래핌·단어·줄 셔플은 언제 각각 사용하나요?

개별 표시 군집이 테스트 단위일 때만 그래핌을 섞습니다. 구두점과 공백 슬롯을 유지하며 토큰 순서를 바꾸려면 단어를, 레코드나 행이 독립적이고 줄 끝 슬롯이 안정적이어야 하면 줄을 섞습니다. 의미나 문법을 보존해야 하면 셔플을 사용하지 않습니다.

여러 언어가 섞였는데 분절 로케일 하나를 왜 고르나요?

Intl.Segmenter에는 하나의 로케일 힌트가 필요하고 문자 체계별 규칙이 다릅니다. 지배적이거나 결정에 중요한 구간의 로케일을 고르고 혼합 문자 사례를 의도적으로 포함해 단어 슬롯을 확인합니다. 이 설정은 번역이나 모든 언어의 언어학적 토큰화를 보장하지 않습니다.

FIGlet 출력을 이미지 대체 텍스트나 제목으로 쓸 수 있나요?

아닙니다. 일반 제목을 의미 라벨로 사용하고 FIGlet은 선택적 preformatted 장식으로 취급합니다. 가까운 곳에 같은 평문이 있으면 보조 기술에서 중복을 숨기는 방식도 검토합니다. 배너는 줄이 바뀌거나 간격을 잃을 수 있으므로 좁은 화면과 복사를 테스트합니다.

영어 점자 부분집합으로 문서 접근성을 증명할 수 있나요?

아닙니다. 학습과 제한된 예시를 위한 매핑입니다. 접근성은 언어, 축약, 촉각 배치, 문서 구조, 목표 기술, 표준과 독자 테스트에 달려 있으며 이 변환기는 이를 수행하지 않습니다.

미리보기가 다운로드 결과보다 먼저 끝나는 이유는 무엇인가요?

줄 번호가 있는 큰 문자열 렌더링은 메모리를 낭비하고 페이지를 멈출 수 있습니다. 미리보기는 Unicode 코드 포인트 50,000개에서 멈추지만 엔진이 UTF-8 2 MiB 출력 상한을 지킨 뒤에는 복사와 다운로드가 전체 결과를 유지합니다.