Communitygithub.com

rtl-typography

Règles typographiques fondamentales pour les interfaces web en persan (farsi) et arabe. À utiliser lors de la création ou du stylage d'une interface contenant du texte persan/arabe/farsi, ou lorsque l'utilisateur mentionne فارسی، عربی، RTL، نیم‌فاصله، فونت فارسی. Couvre la sélection de polices, le ZWNJ (نیم‌فاصله), les chiffres persans, la ponctuation, l'interlignage et les motifs interdits comme l'espacement des lettres sur l'écriture arabe.

Qu'est-ce que rtl-typography ?

Cette compétence définit la couche typographique pour les interfaces droite-gauche (RTL). Elle est essentielle pour les développeurs travaillant avec du contenu en persan ou en arabe, car elle évite les erreurs courantes générées par l'IA, comme l'application de letter-spacing sur l'écriture arabe (qui brise la cursive des lettres) ou l'absence de ZWNJ (espace virtuel) dans les mots composés persans. La compétence fournit des directives précises pour la configuration du document (lang et dir), le choix des polices (avec un tableau détaillé pour le persan et l'arabe), l'utilisation correcte des chiffres et de la ponctuation spécifiques à chaque langue, et les réglages d'interlignage adaptés. Elle s'appuie sur des profils machine-readable (fichiers JSON) pour garantir la cohérence entre les règles écrites et les vérifications automatisées, et inclut un script Python pour corriger les textes persans existants. La compétence est conçue pour être utilisée avec Claude Code, Cursor, Codex et d'autres plateformes d'agents IA, et fait partie d'un ensemble plus large comprenant rtl-landing (pour les pages complètes) et rtl-components (pour les motifs de composants).

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mhmdsdqi87-cloud/TEKA_raast/tree/HEAD/skills/rtl-typography

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Typographie RTL : Persan & Arabe, version correcte

Cette compétence encode la couche typographique pour les interfaces droite-gauche (RTL). Suivez-la chaque fois que le texte de la page est en persan ou en arabe. Pour les constructions de pages complètes, voir rtl-landing ; pour les motifs de composants, voir rtl-components.

1. Configuration du document — toujours en premier

<html lang="fa" dir="rtl">
  • Définissez lang ET dir ensemble. lang="fa" pour le persan, lang="ar" pour l'arabe.
  • Ne simulez jamais le RTL avec text-align: right sur un document LTR. Les navigateurs, lecteurs d'écran, contrôles de formulaire et barres de défilement s'appuient tous sur dir.
  • Chaque alignement doit utiliser des valeurs logiques : text-align: start, pas left.

2. Polices de caractères

Utilisez une police conçue pour la langue. Une police qui ne possède pas les glyphes persans affiche des formes cassées/tofu ou se substitue silencieusement.

Choix fiables (détails + snippets CDN dans fonts.md) :

Cas d'utilisationPersanArabe
Texte principal/UI (par défaut)VazirmatnIBM Plex Sans Arabic
Affichage/titresLalezar, EstedadCairo, Changa
Style éditorial/serifMarkazi Text, ParastooNoto Naskh Arabic
Style familier/systèmeSahel, ShabnamTajawal, Almarai

Motif de pile — nommez toujours un fallback, et laissez une police couvrir le latin :

font-family: 'Vazirmatn', Tahoma, sans-serif;

Chargez uniquement du woff2, utilisez font-display: swap, ne chargez que les graisses que vous utilisez (400, 500, 700 suffisent généralement).

3. N'utilisez JAMAIS letter-spacing sur l'écriture arabe

C'est le bogue RTL généré par l'IA le plus courant.

Les lettres de l'écriture arabe sont cursives et liées. letter-spacing insère des espaces entre les glyphes liés, brisant visuellement les mots : «مدیریت» devient م د ی ر ی ت.

/* FAUX — casse la liaison */
.hero-title { letter-spacing: 0.05em; }

/* CORRECT — si vous avez besoin d'un texte d'affichage plus large, utilisez la taille/graisse à la place */
.hero-title { font-weight: 800; font-size: 3rem; }

Règle : letter-spacing: 0 ou non défini pour tout texte en écriture arabe. Les astuces de suivi (majuscules, suivi large) ne s'appliquent de toute façon pas — l'écriture arabe n'a pas de casse.

4. Interlignage et rythme

Les lignes de l'écriture arabe sont plus hautes que le latin (ascendantes/descendantes + diacritiques). Les valeurs par défaut latines semblent trop serrées.

  • Texte principal persan : line-height: 1.8–2.0 (1.9 est une valeur par défaut sûre)
  • Texte principal arabe : line-height: 1.6–1.8
  • Titres : 1.3–1.4
  • Le texte persan occupe environ 10 à 15 % de largeur en plus que l'anglais pour le même contenu — prévoyez des boutons plus larges, plus de largeur de paragraphe, ne tronquez pas trop.

Justification : préférez un alignement de début (texte en drapeau). La justification du navigateur sans support kashida crée de vilaines rivières entre les mots.

5. ZWNJ — نیم‌فاصله (U+200C)

Les composés et affixes persans s'écrivent avec un Zero-Width Non-Joiner (espace sans largeur non-liant) entre les parties. L'absence de ZWNJ est le défaut d'orthographe le plus visible dans le texte persan généré.

Tableau d'utilisation correcte

Erroné (espace ou lié)Correct (avec U+200C)
می رودمی‌رود
نمی شودنمی‌شود
می خواهممی‌خواهم
خانه هاخانه‌ها
کتاب هایکتاب‌های
بهترین هابهترین‌ها
خوب ترخوب‌تر
برنامه نویسیبرنامه‌نویسی
راه اندازیراه‌اندازی
ورود به سیستم می پردازدورود به سیستم می‌پردازد

Règles empiriques :

  • Préfixes می, نمی, بی, هم, نا, باز + verbe/adjectif → ZWNJ : می‌گوید، نمی‌دانست، بی‌نقص، هم‌گام
  • Suffixes ها, های, تر, ترین après un mot → ZWNJ : پرنده‌ها، کتاب‌های، بزرگ‌تر، بزرگ‌ترین
  • Noms composés de la liste de l'Académie → ZWNJ : راه‌اندازی، برنامه‌نویسی، نرم‌افزار، ذخیره‌سازی
  • Suffixes possessifs ام/ات/اش s'écrivent liés : کتابم، خانه‌ات — n'insérez PAS de ZWNJ ici.

Lorsque vous générez du texte persan, écrivez le ZWNJ de manière native (pas un espace). Pour assainir un texte existant, utilisez le script fourni :

python3 scripts/fix-zwnj.py draft.md            # diff d'essai (dry-run)
python3 draft-output.md > fixed.md --apply ...  # voir --help

Le script joint les motifs cassés courants (می رود, خانه ها, خوب تر), convertit l'arabe ي ك en persan ی ک, et ne touche jamais aux blocs de code ni aux URL.

6. Chiffres

LangueChiffresPlage Unicode
Persan۰۱۲۳۴۵۶۷۸۹U+06F0–U+06F9
Arabe٠١٢٣٤٥٦٧٨٩U+0660–U+0669
Latin (contextes intégrés)0123456789U+0030–U+0039
  • Le texte rédigé en persan utilise les chiffres persans : «۵ دلیل»، «۲۴ ساعت».
  • Prix : ۱۲۵٬۰۰۰ تومان — le séparateur de milliers est U+066C (٬), la virgule décimale est U+066B (٫).
  • Pourcentage après le nombre, sans espace : ۱۲٪ (signe pourcentage arabe U+066A).
  • Ne formatez jamais ces éléments à la main : utilisez les API de locale JS.
(125000).toLocaleString('fa-IR')   // "۱۲۵٬۰۰۰"
(12.5).toLocaleString('fa-IR')     // "۱۲٫۵"
new Intl.NumberFormat('fa-IR', { style: 'percent' }).format(0.12)  // "۱۲٪"

Gardez les chiffres occidentaux uniquement dans les atomes intrinsèquement LTR : numéros de téléphone, URL, code, prix en devise étrangère.

7. Ponctuation — marques persanes dans le texte persan

ObjectifPersan/ArabeN'utilisez pas
Virgule، (U+060C),
Point d'interrogation؟ (U+061F)?
Point-virgule؛ (U+061B);
Guillemet«متن»"متن"
Décimal / milliers٫ ٬. ,
Pourcentage٪ (U+066A)%

L'ellipse est …, pas trois points. Pas d'espace avant ، ؟ ؛ ; un espace après.

8. Persan vs Arabe — décidez d'abord

Ce sont des langues différentes avec des conventions différentes. Confirmez laquelle avant de styliser :

  • Chiffres : fa → ۱۲۳ (U+06F0), ar → ١٢٣ (U+0660)
  • Lettres : persan ی/ک vs arabe ي/ك — une police persane doit inclure les formes persanes
  • La ponctuation se chevauche mais le ton/l'idiome diffèrent
  • Une police uniquement persane sur une page arabe affiche des formes de lettres incorrectes pour ک/ی et vice versa

Les conventions lisibles par machine (plages de chiffres, séparateurs, ponctuation, listes d'affixes) se trouvent dans raast/profiles/fa.json et raast/profiles/ar.json — les mêmes fichiers que ceux utilisés par le CLI raast, de sorte que les règles en prose et les vérifications automatisées ne divergent jamais.

9. Copie, collage, sélection et rendu

Le texte en écriture arabe se brise plus souvent lors du copier-coller et de la sélection que le latin. Règles :

  • Rendu de la sélection : définissez ::selection avec un contraste suffisant (les amas de glyphes de l'écriture arabe s'étendent sous la ligne ; une fine bande de surbrillance les coupe visuellement). L'ajout de padding sur ::selection aide.
  • Intégrité du copier-coller : n'insérez jamais ZWNJ par programme dans les zones où les utilisateurs peuvent coller dans des champs de texte brut ; lors du collage dans la page, conservez le texte collé exactement octet par octet (pas de « nettoyage » automatique de U+200C, U+200E/F, U+061C marque de lettre arabe). La suppression de caractères invisibles corrompt silencieusement la recherche et l'orthographe persanes.
  • user-select: all sur les citations pour que les guillemets restent attachés.
  • Composants copier-dans-le-presse-papiers (prix, numéro de suivi) doivent copier la chaîne logique, pas celle réordonnée visuellement — testez avec une page RTL + un visualiseur de presse-papiers LTR.
  • Indicateurs de rendu de police : préférez text-rendering: optimizeLegibility ; n'utilisez PAS les graisses font-synthesis sur les polices d'affichage arabes (le faux gras brise le rythme du naskh) — chargez de vraies graisses.
  • Avertissements sur les transformations ambiguës : la normalisation des chiffres arabo-indiens (٠١٢) en persan (۰۱۲) est sûre dans le contenu fa, destructrice dans le contenu ar. Toute conversion automatisée doit être limitée par langue — voir references/normalization.md pour la table de décision.

10. Bases de l'écriture mixte (détails dans la compétence rtl-bidi)

  • Téléphone/e-mail/URL/code dans un texte persan : enveloppez dans <bdi> ou une balise dir="ltr".
  • Blocs de code : toujours dir="ltr" + text-align: left, même sur les pages RTL.
  • Entrées générées par l'utilisateur : dir="auto" pour que chaque entrée s'adapte à son propre contenu.

11. Liste de vérification pré-vol

  • <html lang="fa|ar" dir="rtl"> défini
  • La police couvre la langue ; fallback nommé
  • letter-spacing absent sur le texte en écriture arabe
  • Interlignage du corps ≥ 1.8 (persan)
  • Tous les affixes utilisent le vrai U+200C, pas des espaces
  • Chiffres persans + ٬ ٫ ٪ dans le texte ; chiffres latins uniquement dans les atomes LTR
  • Ponctuation persane ، ؟ ؛ «» dans le texte
  • Les alignements utilisent start/end, jamais left/right

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

Skills associés