🖋️ QalamRTL

قلم — Smart RTL Formatting for Arabic in Claude.ai

Transform your Arabic AI conversations with intelligent RTL formatting

Features • Installation • How It Works • Privacy • Contributing

🌟 The Problem

Arabic text in Claude.ai appears left-aligned and broken, making conversations difficult to read. Code blocks get corrupted when mixed with Arabic text, and manual text direction fixes are tedious and time-consuming.

✨ The Solution

QalamRTL is a lightweight Chrome extension that automatically detects Arabic content and applies proper RTL (Right-To-Left) formatting while intelligently preserving code blocks, JSON, and English text in their correct LTR direction.

🎯 Supported Platform

Platform	Status	URL
Claude.ai	✅ Full Support	claude.ai

🚀 Features

🧠 Smart Arabic Detection

Intelligent threshold-based analysis — Only applies RTL when Arabic is dominant (30%+ ratio, 10+ characters)
Per-paragraph processing — Each text block evaluated independently
False positive prevention — Won't trigger on single Arabic words in English sentences
Streaming response support — Works seamlessly as AI types character-by-character

🛡️ Code Block Protection

Preserves all programming languages — Python, JavaScript, JSON, SQL, etc.
Inline code safety — Keeps code snippets readable within Arabic text
Syntax integrity — Zero formatting corruption or character reversal
Multi-level nesting — Handles code blocks inside lists, blockquotes, and tables

⚡ Performance & UX

Real-time processing — Applies formatting instantly during AI streaming
Debounced mutations — Optimized observer pattern prevents layout thrashing
Zero configuration — Works out-of-the-box, no settings required
Toggle control — Enable/disable per tab with one click

🔒 Privacy-First Design

100% local processing — Everything runs in your browser
Zero data collection — No analytics, tracking, or telemetry
Minimal permissions — Only storage (for toggle state)
No external requests — Completely offline after installation
Open source — Fully auditable codebase

📦 Installation

Option 1: Install from Chrome Web Store (Recommended)

🚧 Coming Soon — Extension is pending review

Option 2: Developer Mode (Current)

Clone the repository

git clone https://github.com/fathighanem/QalamRTL.git
cd QalamRTL

Verify assets
- Ensure assets/ contains icon16.png, icon32.png, icon48.png, icon128.png
- All icon files are already included ✅
Load in Chrome
- Open chrome://extensions/
- Enable Developer mode (top-right toggle)
- Click Load unpacked
- Select the QalamRTL folder
Verify installation
- QalamRTL icon should appear in your extensions toolbar
- Visit Claude.ai
- Extension auto-activates on the supported site

📖 Detailed setup: See INSTALLATION.md

🎯 Usage

Basic Operation

Navigate to Claude.ai
Type your message in Arabic (or mixed Arabic/English)
Send — QalamRTL automatically formats the response
Read properly aligned, beautifully formatted Arabic text

Toggle Control

Click the QalamRTL icon in your toolbar to:

✅ Enable (مُفعَّل) — Active RTL formatting
⭕ Disable (معطَّل) — Pause formatting for current tab

Example Use Cases

✅ Pure Arabic conversations
✅ Mixed Arabic/English technical documentation  
✅ Code tutorials with Arabic explanations
✅ Arabic comments in programming examples
✅ Multilingual AI-assisted learning

🔍 How It Works

Architecture Overview

┌─────────────────────────────────────────────────┐
│           Browser Content Script                │
├─────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌──────────────────────┐    │
│  │   Constants │  │  Arabic Detector     │    │
│  │   Config    │  │  - Unicode ranges    │    │
│  └─────────────┘  │  - Ratio threshold   │    │
│                    └──────────────────────┘    │
│  ┌──────────────────────────────────────────┐  │
│  │         Code Block Guard                 │  │
│  │  Protects: pre, code, JSON, inline code │  │
│  └──────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────┐  │
│  │         RTL Applicator                   │  │
│  │  Applies .qrtl-block class to elements  │  │
│  └──────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────┐  │
│  │      MutationObserver + Debouncing       │  │
│  │  Watches DOM changes, handles streaming │  │
│  └──────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────┐  │
│  │        Claude.ai Site Adapter            │  │
│  │  Platform-specific selectors & init     │  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

Processing Pipeline

Detection — Page load triggers Claude adapter
Observation — MutationObserver watches for new messages
Analysis — Each text block scanned for Arabic Unicode ranges
Protection — Code blocks locked to LTR before RTL application
Application — CSS class applied to qualifying elements
Streaming — Debounced re-processing during AI response typing

Key Technical Details

Manifest V3 — Latest Chrome Extension standard
Vanilla JavaScript — Zero dependencies, <50KB total size
CSS-based styling — No inline styles, clean DOM manipulation
Adaptive selectors — Failover mechanisms for DOM structure changes
Memory efficient — Cleanup on disable, no memory leaks

📘 Deep dive: See ARCHITECTURE.md

🔧 Configuration

Customizable Thresholds

Edit src/constants.js to adjust behavior:

const QRTL_CONSTANTS = {
  // Arabic Detection
  ARABIC_RATIO_THRESHOLD: 0.30,    // 30% Arabic content required
  ARABIC_MIN_CHAR_COUNT: 10,       // Minimum 10 Arabic characters
  
  // Performance
  STREAMING_DEBOUNCE_MS: 400,      // Streaming response delay
  OBSERVER_DEBOUNCE_MS: 100,       // DOM mutation debounce
  
  // Polling (for SPA container detection)
  CONTAINER_POLL_INTERVAL_MS: 300, // Poll every 300ms
  CONTAINER_POLL_MAX_RETRIES: 60   // Max 18 seconds wait
};

CSS Customization

Modify css/rtl-fixes.css to adjust visual styling:

.qrtl-block {
  direction: rtl !important;
  unicode-bidi: embed !important;
  text-align: right !important;
}

🧪 Testing

Manual Testing

# Open Chrome DevTools on Claude.ai and paste:

# 1. Check if messages are found
document.querySelectorAll('[data-testid="assistant-message"]').length

# 2. Verify RTL processing
document.querySelectorAll('.qrtl-block').length

# 3. Check processed markers
document.querySelectorAll('[data-qrtl-processed]').length

# 4. Inspect console logs
# Look for: [QalamRTL] messages in console

Automated Tests

# Run unit tests (Node.js)
cd tests
node unit-runner.js

# Expected: 25/25 passing

Test Coverage

✅ Pure Arabic text (100% ratio)
✅ Pure English text (0% ratio)
✅ Mixed content (50/50 split)
✅ Code blocks with Arabic comments
✅ Inline code preservation
✅ JSON structure integrity
✅ Streaming response handling
✅ Edge cases (URLs, math, tables)

📋 Test plan: See tests/MANUAL-QA.md

🐛 Troubleshooting

Extension Not Working?

Check browser console:

// Open DevTools (F12) and run:
console.log(window.QRTLClaudeAdapter);
// Should return an object, not undefined

Verify installation:

Go to chrome://extensions/
QalamRTL should be enabled with no errors
Check that you're on claude.ai

Force reload:

Refresh the page (Ctrl+R or Cmd+R)
Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
Reload extension from chrome://extensions/

Selectors Outdated?

Claude.ai updates their DOM frequently. If formatting stops working:

Check adapter file for [VERIFY-ON-UPDATE] comments:
- src/adapters/claude.js

Inspect current selectors:

// In DevTools console:
document.querySelectorAll('[data-testid="assistant-message"]').length // Claude

Update selectors if needed and reload extension

📖 Debugging guide: See docs/DEBUGGING.md

🔒 Privacy & Security

Zero Data Collection

QalamRTL is 100% privacy-first:

Aspect	Guarantee
Analytics	❌ None — no tracking pixels, no telemetry
Network Requests	❌ None — completely offline
Data Storage	✅ Only toggle state (local)
Permissions	✅ `storage` only (for toggle)
Code Auditing	✅ Fully open source

Permission Justification

{
  "permissions": ["storage"],  // Save toggle state
  "host_permissions": [        // Apply CSS/JS only on:
    "https://claude.ai/*"
  ]
}

No access to:

❌ Browsing history
❌ Other tabs or websites
❌ Clipboard
❌ Downloads
❌ Geolocation

Security Practices

✅ No eval() or dynamic code execution
✅ No external CDN dependencies
✅ Content Security Policy compliant
✅ Minimal DOM manipulation scope
✅ No third-party libraries

🤝 Contributing

Contributions are welcome! Here's how to help:

Areas for Improvement

🌐 Platform support — Gemini, Perplexity, Poe, etc.
🧪 Test coverage — Expand unit tests for edge cases
🎨 UI enhancements — Settings page, custom themes
🌍 Localization — Interface translations (Arabic, English, etc.)
📱 Firefox support — WebExtension port

Development Setup

# 1. Fork and clone
git clone https://github.com/fathighanem/QalamRTL.git
cd QalamRTL

# 2. Load in Chrome (Developer Mode)
# chrome://extensions/ → Load unpacked

# 3. Make changes
# Edit files in src/, css/, popup/

# 4. Test
node tests/unit-runner.js

# 5. Submit PR
git checkout -b feature/your-feature
git commit -am "Add your feature"
git push origin feature/your-feature

Code Style

✅ Use 'use strict'; in all modules
✅ IIFE pattern: (function(window) {...})(window);
✅ JSDoc comments for all functions
✅ Consistent 2-space indentation
✅ Descriptive variable names

📚 Documentation

Document	Description
REQUIREMENTS.md	Complete functional & non-functional requirements
ARCHITECTURE.md	Technical architecture & design decisions
INSTALLATION.md	Detailed installation guide
tests/MANUAL-QA.md	Manual testing checklist (38 items)
docs/DEBUGGING.md	Troubleshooting guide with console commands
docs/SELECTOR-MAINTENANCE.md	How to update DOM selectors

📝 License

This project is licensed under the MIT License — see LICENSE for details.

Copyright (c) 2026 QalamRTL Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
...

🙏 Acknowledgments

Built for Arabic-speaking developers, researchers, and students worldwide
Inspired by the need for proper RTL support in modern AI interfaces
Thanks to the open-source community for Chrome Extension standards

🌐 Links

Repository: github.com/fathighanem/QalamRTL
Issues: Report a bug
Chrome Web Store: (Coming Soon)

قلم (Qalam) — Arabic for "pen" or "writing instrument"

Made with ❤️ for the Arabic-speaking tech community

Name		Name	Last commit message	Last commit date
assets		assets
css		css
docs		docs
popup		popup
src		src
tests		tests
ARCHITECTURE.md		ARCHITECTURE.md
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
README.md		README.md
REQUIREMENTS.md		REQUIREMENTS.md
SECURITY.md		SECURITY.md
manifest.json		manifest.json

Latest commit

History

Folders and files

Repository files navigation