jubyuhanna-create/arabic-ready

Arabic-ready 출력

목표: 모든 출력 형식에서 첫 시도에 아랍어가 올바르게 렌더링되고, 읽히고, 자연스럽게 느껴지도록 합니다.

1. 작성 전 세 가지 결정하기

결정	기본값	변경해야 하는 경우
대상 로케일	ar + 알려진 지역 (ar-SA, ar-EG, ar-AE, ar-MA...)	사용자가 국가/도시/시장을 지정한 경우
숫자	UI, 가격, 전화번호, 코드, 차트에는 서양식 0-9. 이집트, 사우디아라비아, 이라크, 레반트, 수단, 예멘을 대상으로 하는 공식/편집 텍스트에는 아랍-인디아 ٠-٩	사용자가 요청하거나 브랜드/지역에서 명확히 ٠-٩를 사용하는 경우. 마그레브(MA/DZ/TN)는 항상 0-9를 사용
레지스터	현대 표준 아랍어(فصحى), 명확하고 현대적이며 고전적이지 않음	사용자가 방언(이집트어, 걸프어, 레반트어...)을 요청하거나 채널이 캐주얼한 경우(WhatsApp 프로모션, 소셜 게시물): references/writing.md 참조

하나의 출력물에서 숫자 체계를 혼합하지 마십시오.

2. 핵심 규칙 (모든 출력 유형에 적용)

1. 방향은 루트에서 한 번만 선언하세요. 그런 다음 모든 요소가 상속하도록 하십시오. ❌ <html> + 요소에 style="direction:rtl" 산발적으로 적용 ✅ <html lang="ar" dir="rtl"> · docx <w:bidi/> + <w:rtl/> · pptx rtl="1" · Flutter Directionality(textDirection: TextDirection.rtl) / locale: Locale('ar')
2. 논리적 방향을 사용하고, 절대 left/right를 사용하지 마십시오. 아랍어에서 "시작"은 오른쪽입니다. ❌ margin-left, ml-4, text-left, left: 0, EdgeInsets.only(left:) ✅ margin-inline-start, ms-4, text-start, inset-inline-start: 0, EdgeInsetsDirectional.only(start:)
3. LTR 섬을 분리하세요 (전화번호, 이메일, URL, 코드, 숫자 옆의 영어 이름, 음수). ❌ اتصل على +966 50 123 4567. → 4567 123 50 966+로 렌더링됨 ✅ اتصل على <bdi dir="ltr">+966 50 123 4567</bdi>. · 일반 텍스트: LRI…PDI(⁦…⁩)로 감싸거나 음수 -5 앞에 LRM ‎ 배치
4. 전화, 이메일, URL, 코드, IBAN, 비밀번호 입력 필드는 RTL 양식 내에서도 dir="ltr" 을 유지하십시오 (text-end로 정렬).
5. 방향성이 있는 아이콘만 미러링하십시오. 뒤로/앞으로 화살표, 셰브론, 보내기, 답장, 실행 취소/다시 실행, 진행 방향은 뒤집습니다. 재생/일시 정지, 미디어 컨트롤, 체크 표시, 시계, 검색, 로고, 브랜드 마크 및 숫자는 뒤집지 않습니다.
6. 타이포그래피: 아랍어 전용 글꼴을 사용하고 (references/typography.md 목록 참조), 본문 텍스트의 행간은 ≥ 1.6으로 설정하며, tashkeel(움라임)을 위해 위아래 여유 공간을 남겨두십시오. 아랍어 텍스트에 절대 letter-spacing/tracking-*, uppercase, italic 또는 좁은 overflow:hidden 높이를 적용하지 마십시오.
7. 조형: 원시 텍스트는 조형 렌더러에, 조형된 텍스트는 나머지에 전달하십시오. 절대 둘 다 하지 마십시오. 브라우저, Word, LibreOffice, PowerPoint, WeasyPrint, Chromium PDF, matplotlib ≥ 3.11, Pillow with libraqm, fpdf2 with set_text_shaping() 은 아랍어를 자체적으로 조형하므로 원시 문자열을 전달하십시오. reportlab, PyMuPDF insert_text, OpenCV, matplotlib ≤ 3.10, 라큠이 없는 Pillow는 글리프 단위로 그리므로 scripts/shape_text.py의 prepare(text)를 전달하십시오. 이미 조형하는 렌더러에 텍스트를 다시 조형하면 텍스트가 다시 역전됩니다(matplotlib 3.11 및 Pillow+raqm에서 확인됨).
8. 아랍어 문장 부호: ، 쉼표, ؛ 세미콜론, ؟ 물음표, «» 따옴표. . 및 !는 유지하십시오. 문장 부호 앞에는 공백을 두지 말고 뒤에는 한 칸의 공백을 두십시오.
9. 아랍어를 모국어처럼 작성하고, 단어 단위로 번역하지 마십시오. 버튼에는 명령형 동사(أرسل(보내기), احفظ(저장), ابدأ الآن(지금 시작하기))를 사용하고, 영어 어순을 따르지 마십시오. references/writing.md를 참조하십시오.
10. 숫자/날짜/통화를 문자열 연결이 아닌 로케일로 형식화하십시오. Intl.NumberFormat('ar-SA', ...) / Intl.DateTimeFormat('ar-EG-u-nu-latn', ...)을 사용하고, 항상 nu(숫자)와 ca(달력)를 명시적으로 설정하십시오.

3. 출력 유형별 참조 문서 로드하기

작업에 필요한 것만 읽으십시오:

출력	참조 문서
HTML, CSS, Tailwind, React, Next.js, Vue, React Native, Flutter, 이메일 HTML	references/web.md + references/bidi.md
아랍어 + 영어/숫자 혼합 위치 (마크다운, 일반 텍스트, SMS, JSON 문자열 포함)	references/bidi.md
글꼴, 행간, tashkeel, 두께, 양끝 정렬	references/typography.md
Word (.docx), PowerPoint (.pptx), PDF	references/documents.md
matplotlib, Pillow, SVG, canvas, OpenCV, Plotly, 텍스트가 포함된 모든 이미지	references/charts-images.md
카피라이팅, 번역, 방언, 숫자, 날짜, 통화, 이름, 히즈리	references/writing.md

4. RTL에서 뒤집히는 것과 그렇지 않은 것

뒤집힘 (레이아웃 미러링)	동일하게 유지됨
읽기 순서, 텍스트 정렬, 탐색 순서, 사이드바 위치	전화번호, 신용카드, IBAN(항상 LTR)
이동 경로, 페이지네이션, 스테퍼: "다음"은 왼쪽을 가리킴. 텍스트 › > (는 자동으로 미러링되지만 → 및 SVG 아이콘은 미러링되지 않음	코드 블록, 터미널 출력, URL, 이메일
뒤로/다음 화살표, 셰브론, 캐러셀/슬라이더 스와이프 방향	시계열 차트 x축(시간은 왼쪽→오른쪽으로 흐름). 범주 축은 뒤집힐 수 있음
테이블 열 순서 (첫 번째 열이 오른쪽에 위치)	미디어 컨트롤(재생 ▶, 빨리 감기), 시계, 체크 표시
진행률 표시줄 및 범위 슬라이더가 오른쪽에서 채워짐	로고, 브랜드 마크, 사진, 지도
양식 레이블은 오른쪽에, 닫기 버튼 ×은 대화상자 왼쪽에 위치	수학 표현식 및 숫자 자체(1,234.5는 1,234.5로 유지)
토스트/드로어 슬라이드인 방향, 아바타 뱃지, 목록 글머리 기호	키보드 단축키(Ctrl+S)

5. 마무리 전 확인 사항

1. 린터 실행 (Python 표준 라이브러리만 필요): python <skill-dir>/scripts/rtl_check.py <file-or-folder> 모든 error를 수정하십시오. 의도적인 경우가 아니라면 warning도 수정하고, 의도적인 경고에는 rtl-ok 주석을 표시하십시오.
2. 가능하면 렌더링하여 확인하고, 글자가 연결되어 있는지, 첫 단어가 오른쪽에 있는지, 문장 부호가 왼쪽 끝에 있는지, 숫자가 올바른 순서로 읽히는지 확인하십시오:
   • HTML: python -m playwright screenshot --full-page file://$PWD/index.html shot.png (또는 npx playwright screenshot …). 브라우저를 사용할 수 없으면 weasyprint index.html out.pdf로 정적 렌더링을 얻을 수 있습니다.
   • docx/pptx: soffice --headless --convert-to pdf file.docx, 그런 다음 PDF를 래스터화합니다.
   • PDF → PNG: python -c "import pymupdf; pymupdf.open('f.pdf')[0].get_pixmap(dpi=110).save('f.png')"
   • 이미지/차트: 작성한 PNG를 엽니다.
3. 스크립트를 실행할 수 없는 경우 (Python, 셸 없음), 다음 체크리스트를 수동으로 확인하십시오:
   • 루트 dir="rtl" + lang="ar…" (또는 해당 형식의 동등한 속성)
   • 간격, 위치 지정 또는 정렬에 left/right가 사용되지 않음
   • 전화/이메일/URL/코드가 격리되어 LTR로 설정됨
   • 방향성 아이콘이 미러링되고, 다른 아이콘은 그대로 유지됨
   • 아랍어 글꼴 로드됨, 행간 ≥ 1.6, letter-spacing, italic 또는 uppercase 없음
   • 이미지/PDF 텍스트: 조형 경로가 렌더러와 일치함 (규칙 7)
   • ، ؛ ؟ 사용됨, 하나의 숫자 체계 사용, 자연스러운 현대 표준 아랍어(또는 요청된 방언) 사용

스크립트

• scripts/rtl_check.py <path>: RTL 버그에 대해 HTML/CSS/Tailwind/JSX/TSX/Vue/Svelte/React Native/Flutter를 린트합니다. 파일:줄, 문제 및 정확한 수정 사항을 출력합니다. 오류 시 종료 코드 1. 표준 라이브러리만 사용.
• scripts/shape_text.py: prepare(text, target) - 아랍어를 조형하지 않는 렌더러를 위한 함수입니다. matplotlib/Pillow 네이티브 지원을 감지하고 조형이 필요하지 않은 경우 텍스트를 변경하지 않고 반환합니다. arabic-reshaper + python-bidi(필요시 pip 설치)를 사용하거나 내장 표준 라이브러리 조형기로 대체됩니다. python shape_text.py --check는 이 시스템에 필요한 사항을 보고합니다.