pi-persian-rtl

Persian / Farsi RTL rendering support for the Pi terminal UI.

Important: native BiDi is the default

Version 0.1.1 no longer reverses Persian text before sending it to the terminal. Modern terminals already implement the Unicode Bidirectional Algorithm; manually reversing the line makes them process it twice and breaks sentences containing English identifiers, commands, numbers, or URLs.

The package now keeps text in logical Unicode order, preserves ANSI styling, right-aligns Persian-first lines, and wraps them in RLI/PDI isolation controls so mixed Persian/English content is handled by the terminal's own BiDi engine.

Install or upgrade

pi remove npm:pi-arabic-rtl 2>/dev/null || true
pi update npm:pi-persian-rtl
npx pi-persian-rtl apply

Restart Pi after upgrading.

For a first installation:

pi install npm:pi-persian-rtl

Modes

Native mode — default and recommended

PI_PERSIAN_RTL_MODE=native pi

Native mode:

• does not reverse Persian characters;
• keeps pi-persian-rtl, Context Mode, URLs, paths, and code in LTR order;
• keeps Persian digits and ZWNJ intact;
• preserves ANSI colors and styles;
• right-aligns Persian-first lines.

Visual fallback — only for terminals without BiDi support

PI_PERSIAN_RTL_MODE=visual pi

This uses application-side visual reordering. Do not use it in GNOME/VTE or another terminal that already handles BiDi, because that causes double reversal.

Disable transformation

PI_PERSIAN_RTL_MODE=off pi

Commands

npx pi-persian-rtl apply
npx pi-persian-rtl check
npx pi-persian-rtl restore

apply patches the installed @earendil-works/pi-tui output layer. The first patch creates .pi-persian-rtl.bak files beside the modified files. restore restores those backups.

When discovery cannot find Pi's TUI installation:

PI_TUI_DIST=/path/to/@earendil-works/pi-tui/dist npx pi-persian-rtl apply

Test text

۱. Pi یک دستیار کدنویسی سریع و قابل اعتماد است.
۲. پکیج pi-persian-rtl نسخه ۰.۱.۱ نصب شد.
۳. Context Mode و npm test باید درست نمایش داده شوند.
۴. لینک https://pi.dev و مسیر /home/user/project سالم می‌مانند.
۵. من می‌روم و عدد ۱۲۳٬۴۵۶ را بررسی می‌کنم.

Development

npm test
npm run check
npm pack

Compatibility

• Current Pi releases using @earendil-works/pi-tui.
• Node.js 20 or newer.
• Linux, macOS, and Windows.
• Native mode requires a terminal with Unicode BiDi support.
• Visual mode is an opt-in fallback for terminals without it.

License

MIT. See NOTICE for attribution to the original pi-arabic-rtl package that inspired the patching approach.