jubyuhanna-create/arabic-ready

Arabisch-korrekte Ausgabe

Ziel: Arabisch, das beim ersten Versuch korrekt gerendert, gelesen und sich wie Muttersprache anfühlt – in jedem Ausgabeformat.

1. Entscheide drei Dinge, bevor du etwas schreibst

Entscheidung	Standard	Ändere, wenn ...
Zielregion (Locale)	ar + Region falls bekannt (ar-SA, ar-EG, ar-AE, ar-MA...)	Der Benutzer nennt ein Land/eine Stadt/einen Markt
Ziffern	Westliche 0-9 für UI, Preise, Telefone, Code, Diagramme. Arabisch-Indisch ٠-٩ für formelle/redaktionelle Texte, die für Ägypten, Saudi-Arabien, Irak, die Levante, Sudan, Jemen bestimmt sind	Der Benutzer fragt danach, oder die Marke/Region verwendet deutlich ٠-٩. Maghreb (MA/DZ/TN) verwendet immer 0-9
Register	Modernes Hocharabisch (فصحى), klar und modern, nicht klassisch	Der Benutzer fragt nach einem Dialekt (Ägyptisch, Golf, levantinisch...) oder der Kanal ist informell (WhatsApp-Aktionen, Social Posts): siehe references/writing.md

Mische niemals Ziffernsysteme in einem einzelnen Ausgabestück.

2. Kernregeln (gelten für jeden Ausgabetyp)

1. Richtung an der Wurzel deklarieren, einmal. Dann alles erben lassen. ❌ <html> + style="direction:rtl" auf Elementen verteilt ✅ <html lang="ar" dir="rtl"> · docx <w:bidi/> + <w:rtl/> · pptx rtl="1" · Flutter Directionality(textDirection: TextDirection.rtl) / locale: Locale('ar')
2. Logische Richtungen verwenden, niemals links/rechts. „Start“ ist im Arabischen die rechte Seite. ❌ 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-Inseln isolieren (Telefonnummern, E-Mails, URLs, Code, englische Namen neben Zahlen, negative Zahlen). ❌ اتصل على +966 50 123 4567. → rendert als 4567 123 50 966+ ✅ اتصل على <bdi dir="ltr">+966 50 123 4567</bdi>. · Klartext: in LRI…PDI (⁦…⁩) einwickeln oder LRM ‎ vor -5 setzen
4. Eingabefelder für Telefon, E-Mail, URL, Code, IBAN, Passwörter bleiben dir="ltr" auch innerhalb eines RTL-Formulars (ausrichten mit text-end).
5. Nur richtungsabhängige Symbole spiegeln. Zurück/Vor-Pfeile, Chevrons, Senden, Antworten, Rückgängig/Wiederholen, Fortschrittsrichtung umdrehen. Play/Pause, Mediensteuerung, Häkchen, Uhren, Suche, Logos, Markenzeichen und Zahlen nicht.
6. Typografie: eine arabisch gestaltete Schriftart verwenden (Liste in references/typography.md), Zeilenhöhe ≥ 1,6 für Fließtext und Platz ober- und unterhalb für Tashkeel lassen. Niemals Buchstabenabstand/tracking-*, uppercase, italic oder enge overflow:hidden-Höhen auf Arabisch anwenden.
7. Formung: Rohtext an formende Renderer, geformten Text an die übrigen. Niemals beides. Browser, Word, LibreOffice, PowerPoint, WeasyPrint, Chromium PDF, matplotlib ≥ 3.11, Pillow mit libraqm, fpdf2 mit set_text_shaping() formen Arabisch selbst: den Rohtext übergeben. reportlab, PyMuPDF insert_text, OpenCV, matplotlib ≤ 3.10, Pillow ohne raqm zeichnen Zeichen für Zeichen: prepare(text) aus scripts/shape_text.py übergeben. Das erneute Formen von Text für einen Renderer, der bereits formt, kehrt ihn wieder um (getestet in matplotlib 3.11 und Pillow+raqm).
8. Arabische Interpunktion: ، Komma, ؛ Semikolon, ؟ Fragezeichen, «» Anführungszeichen. . und ! beibehalten. Kein Leerzeichen vor Interpunktion und ein Leerzeichen danach.
9. Arabisch muttersprachlich schreiben, nicht wortwörtlich übersetzen. Imperativ für Schaltflächen (أرسل, احفظ, ابدأ الآن) und keine englische Wortstellung. Siehe references/writing.md.
10. Zahlen/Daten/Währung mit Locale formatieren, nicht mit String-Verkettung. Intl.NumberFormat('ar-SA', ...) / Intl.DateTimeFormat('ar-EG-u-nu-latn', ...) verwenden und immer nu (Ziffern) und ca (Kalender) explizit setzen.

3. Die Referenz für deinen Ausgabetyp laden

Nur das lesen, was die Aufgabe benötigt:

Ausgabe	Lesen
HTML, CSS, Tailwind, React, Next.js, Vue, React Native, Flutter, E-Mail-HTML	references/web.md + references/bidi.md
Gemischt Arabisch + Englisch/Zahlen überall (inkl. Markdown, Klartext, SMS, JSON-Strings)	references/bidi.md
Schriftarten, Zeilenhöhe, Tashkeel, Strichstärken, Blocksatz	references/typography.md
Word (.docx), PowerPoint (.pptx), PDF	references/documents.md
matplotlib, Pillow, SVG, Canvas, OpenCV, Plotly, jedes Bild mit Text	references/charts-images.md
Textwerbung, Übersetzung, Dialekte, Ziffern, Daten, Währung, Namen, Hijri	references/writing.md

4. Was sich in RTL umdreht und was nicht

Dreht sich um (spiegelt das Layout)	Bleibt gleich
Leserichtung, Textausrichtung, Navigationsreihenfolge, Seitenleiste	Telefonnummern, Kreditkarten, IBANs (immer LTR)
Breadcrumbs, Paginierung, Step-Indikatoren: „Weiter“ zeigt nach links. Text › > ( spiegeln automatisch, aber → und SVG-Symbole nicht	Code-Blöcke, Terminalausgabe, URLs, E-Mails
Zurück/Vor-Pfeile, Chevrons, Karussells/Schieberegler-Wischrichtung	Zeitreihen-Diagramm-X-Achse (Zeit läuft von links nach rechts). Kategorieachsen können umdrehen
Tabellenspaltenreihenfolge (erste Spalte rechts)	Mediensteuerung (Play ▶, Vorlauf), Uhren, Häkchen
Fortschrittsbalken und Bereichsregler füllen von rechts	Logos, Markenzeichen, Fotos, Karten
Formularbeschriftungen rechts, Schließen-Button × links unten im Dialog	Mathematische Ausdrücke und Zahlen selbst (1.234,5 bleibt 1.234,5)
Toast/Drawer-Einschubseite, Badges auf Avataren, Listenpunkte	Tastaturkürzel (Strg+S)

5. Bevor du fertig bist

1. Führe den Linter aus auf jedem von dir erstellten Code (er benötigt nur die Python-Standardbibliothek): python <skill-verzeichnis>/scripts/rtl_check.py <datei-oder-ordner> Behebe jeden error. Behebe warnings, es sei denn, sie sind beabsichtigt, und markiere beabsichtigte mit einem rtl-ok-Kommentar.
2. Rendere und schau nach, wenn möglich, und überprüfe dann, ob die Buchstaben verbunden sind, das erste Wort rechts steht, Satzzeichen am linken Ende sitzen und Zahlen in der richtigen Reihenfolge gelesen werden:
   • HTML: python -m playwright screenshot --full-page file://$PWD/index.html shot.png (oder npx playwright screenshot …). Wenn kein Browser verfügbar ist, liefert weasyprint index.html out.pdf eine statische Renderausgabe.
   • docx/pptx: soffice --headless --convert-to pdf file.docx, dann das PDF rastern.
   • PDF → PNG: python -c "import pymupdf; pymupdf.open('f.pdf')[0].get_pixmap(dpi=110).save('f.png')"
   • Bilder/Diagramme: öffne das von dir geschriebene PNG.
3. Wenn Skripte nicht ausgeführt werden können (kein Python, keine Shell), gehe diese Checkliste manuell durch:
   • root dir="rtl" + lang="ar…" (oder das Äquivalent des Formats)
   • kein left/right bei Abständen, Positionierung oder Ausrichtung
   • Telefone/E-Mails/URLs/Code isoliert und LTR
   • richtungsabhängige Symbole gespiegelt, andere unverändert
   • arabische Schriftart geladen, Zeilenhöhe ≥ 1.6, kein Buchstabenabstand, italic oder uppercase
   • Bild/PDF-Text: Formungspfad stimmt mit dem Renderer überein (Regel 7)
   • ، ؛ ؟ verwendet, ein Ziffernsystem, natürliches MSA (oder der angeforderte Dialekt)

Skripte

• scripts/rtl_check.py <pfad>: lintet HTML/CSS/Tailwind/JSX/TSX/Vue/Svelte/React Native/Flutter auf RTL-Fehler. Gibt datei:zeile, das Problem und die genaue Korrektur aus. Exit-Code 1 bei Fehlern. Nur Stdlib.
• scripts/shape_text.py: prepare(text, target) für Renderer, die Arabisch nicht formen. Es erkennt native matplotlib/Pillow-Unterstützung und gibt den Text unverändert zurück, wenn keine Formung nötig ist. Es verwendet arabic-reshaper + python-bidi (bei Bedarf per pip installiert) oder fällt auf einen integrierten Stdlib-Former zurück. python shape_text.py --check meldet, was dieser Rechner benötigt.