Smart RTL

Persian and Arabic text, easier to read inside your code.

Smart RTL automatically improves right-to-left display for Persian and Arabic text in the standard VS Code editor: tag content, attributes, strings, and comments. It updates as you type and scroll, without rewriting your source files.

Preview · Free · Publisher: Arsam Kalhor (arsam-dev)

Install from Visual Studio Marketplace

Install

Open Extensions (Ctrl+Shift+X), search for Smart RTL by Arsam Kalhor, and select Install.

Or run:

code --install-extension arsam-dev.smart-rtl

You can also open Quick Open (Ctrl+P) and enter:

ext install arsam-dev.smart-rtl

Use

Detection runs automatically after activation. Open a file containing Persian or Arabic text and start editing.

• Click FA RTL in the status bar to turn the extension on or off.
• Or run Smart RTL: Toggle from the Command Palette (Ctrl+Shift+P).
• FA RTL: Off means decorations are disabled. A language listed in excludedLanguages remains excluded even when the extension is enabled.

Actual editor preview

These screenshots show the same unmodified examples/demo.html source in VS Code 1.142.0 on Linux. Only the Smart RTL setting changes between the two captures.

Before — Smart RTL disabled

After — Smart RTL enabled

The images show actual editor rendering. Smart RTL does not style code blocks in this README or in the Marketplace preview. Raw mixed-direction code can look different there; open the example in VS Code to compare the result.

<div title="توضیح فارسی">نسخه VS Code شماره ۱۲۳ آماده است!</div>
<!-- این کامنت فارسی است و کلمه English هم دارد. -->

const title = "سلام به همه دوستان!";
const mixed = "نسخه React 19 آماده است!";
// این توضیح برای تابع است.

Features

• Detects Arabic-script letters, including Persian پ چ ژ گ ی ک and Arabic letter variants.
• Preserves half-spaces (ZWNJ) in words such as می‌توانیم.
• Keeps mixed Latin words and numbers within the detected text segment.
• Updates visible lines after typing, scrolling, and switching editors.
• Supports a quick toggle and language exclusions.
• Adds no hidden direction characters and does not change saved text or clipboard contents.

Settings

Search for persianSmartRtl in Settings, or add these options to settings.json:

{
  "persianSmartRtl.enabled": true,
  "persianSmartRtl.excludedLanguages": [],
  "persianSmartRtl.debounceMs": 80,
  "persianSmartRtl.maxLineLength": 10000
}

enabled turns automatic decorations on or off. excludedLanguages accepts VS Code language IDs, such as markdown or plaintext. debounceMs controls the update delay after typing. Lines longer than maxLineLength are skipped to keep large or minified files responsive.

Privacy

All processing happens locally. Smart RTL sends no network requests, collects no telemetry, and does not upload your code. It does not modify VS Code's installation files.

Preview limitations

Smart RTL improves text display; it is not a complete native bidirectional editing engine. Cursor movement, selection, word wrapping, fonts, themes, and input methods can affect the result.

Detection uses Arabic-script letters and common code delimiters rather than a complete parser for every language. Quotes, tags, braces, slashes, and other delimiters can split a phrase into separate segments. Syntax highlighting can also split a phrase across multiple rendered tokens. Persian and Arabic are not distinguished linguistically.

The implementation uses fixed CSS through VS Code text decorations. Additional direction styling is a compatibility workaround, not an official direction decoration property, and may need adjustments in future VS Code releases.

Verified environment: VS Code 1.142.0 on Linux, including the example's rendered direction, mouse click position, typing, Undo, split editors, and scrolling. Windows, macOS, IME, and every combination of wrapping, cursor, selection, and syntax highlighting have not been verified.

The extension affects the editor display only. For an RTL website, set dir="rtl" or appropriate CSS in the website itself.

راهنمای فارسی

Smart RTL نمایش متن فارسی و عربی را داخل ادیتور VS Code خواناتر می‌کند؛ از متن داخل تگ‌ها و ویژگی‌ها گرفته تا رشته‌ها و کامنت‌ها. تشخیص پس از فعال‌شدن افزونه خودکار است و با تایپ و اسکرول به‌روز می‌شود.

نصب و استفاده

در بخش Extensions، عبارت Smart RTL را جست‌وجو و افزونهٔ Arsam Kalhor را نصب کنید؛ یا از صفحهٔ Marketplace استفاده کنید.

برای روشن یا خاموش‌کردن، روی FA RTL در نوار پایین کلیک کنید یا دستور Smart RTL: Toggle را از Command Palette اجرا کنید. اگر زبان فایل در persianSmartRtl.excludedLanguages باشد، نمایش RTL برای آن زبان غیرفعال می‌ماند.

نیم‌فاصله، حروف فارسی و ترکیب فارسی با کلمات انگلیسی و عدد در قطعهٔ تشخیص‌داده‌شده پشتیبانی می‌شوند. تنظیمات پیش‌فرض در بخش Settings همین راهنما آمده‌اند؛ برای پیداکردن آن‌ها در تنظیمات VS Code عبارت persianSmartRtl را جست‌وجو کنید.

پیش‌نمایش واقعی

تصویرهای بخش Actual editor preview از یک کد یکسان در VS Code گرفته شده‌اند؛ تصویر اول با افزونهٔ خاموش و تصویر دوم با افزونهٔ روشن است. افزونه داخل پیش‌نمایش README یا Marketplace اجرا نمی‌شود. بلوک کد زیر بخش بازشدنی فقط برای کپی است و نمایش نتیجهٔ افزونه محسوب نمی‌شود.

حریم خصوصی و محدودیت‌ها

پردازش کاملاً محلی است؛ افزونه متن فایل را تغییر نمی‌دهد، کاراکتر مخفی اضافه نمی‌کند و کد شما را به جایی نمی‌فرستد.

این نسخه پیش‌نمایش است و جایگزین پشتیبانی بومی کامل RTL برای مکان‌نما، انتخاب و شکستن خط نیست. تشخیص بر اساس حروف و جداکننده‌های رایج کد انجام می‌شود؛ قالب‌های پیچیده و رنگ‌آمیزی کد ممکن است یک عبارت را به چند قطعه تقسیم کنند.

نمایش و تعامل‌های نمونه در VS Code 1.142.0 روی Linux بررسی شده‌اند. Windows، macOS، روش‌های ورودی IME و همهٔ ترکیب‌های زبان، فونت و تم بررسی نشده‌اند. برای راست‌به‌چپ‌بودن خود صفحهٔ وب همچنان باید dir="rtl" یا CSS مناسب را در سایت تنظیم کنید.

Development

With Node.js 22 or later and Python 3:

npm ci
npm run check
npm test
npm run test:integration
npm run package

To refresh the real before/after screenshots, run npm run capture:demo on Linux before packaging. The capture toggles the actual extension setting, verifies that the source stays unchanged, and writes assets/rtl-disabled.png and assets/rtl-enabled.png.

The VSIX is written to artifacts/. Packaging registers both images as public release assets, so the Marketplace README does not depend on an external image host. To install a local package, use Extensions → … → Install from VSIX… and select the generated file. Open examples/demo.html for sample content, or press F5 in this project to launch the development extension.

The integration runner requires Linux, xvfb-run, and VS Code. It uses a temporary profile, defaults to /usr/share/code/code, and needs local port 9335 available. Set VSCODE_EXECUTABLE to use another executable. Rendering evidence is saved to artifacts/editor.png and artifacts/rendering.json.

License

MIT. See the LICENSE file included with the extension.