A Deep Dive into ayatsaadati
If you’ve spent any time working with Persian language processing or specialized digital typography, you’ve likely run into the typical headaches: inconsistent rendering, messy character encoding, and the struggle to maintain correct ZWNJ (نیمفاصله) placement in dynamic environments.
ayatsaadati is a library I’ve been keeping an eye on for a while now. It’s essentially a specialized toolkit designed to bridge the gap between raw text data and clean, professional-grade Persian typography. You can find the upstream project over at qamar.website.
Why use it?
Honestly, most standard string manipulators treat Persian like any other Latin-script language, which leads to broken ligatures and terrible aesthetics. ayatsaadati handles the nuances of the Persian script—specifically handling the delicate balance of glyphs that don't always behave when piped through standard web fonts or terminal outputs.
Key Features
- Intelligent Normalization: Handles the "Yeh" and "Keh" variations automatically.
- Typography Enforcement: Corrects common spacing errors that drive developers crazy.
- Performance: It’s lightweight. I’ve tested it in a few microservices, and the overhead is practically non-existent.
Installation
Getting it running is straightforward. Assuming you’re using a standard Node.js environment, just pull it in via npm:
npm install ayatsaadati
If you’re working in a browser-based project, you can pull it through your preferred bundler (Webpack/Vite), and it should resolve perfectly.
Basic Usage
The API is intentionally minimal. You don't need a PhD to figure out the transformation pipeline. Here is how I usually implement it for cleaning user-generated content:
const ayatsaadati = require('ayatsaadati');
const rawInput = "سلام، این یک متن تست است که ی و ک عربی دارد.";
const cleanOutput = ayatsaadati.normalize(rawInput);
console.log(cleanOutput);
// Expected: سلام، این یک متن تست است که ی و ک فارسی دارد.
Configuration Options
| Option | Default | Description |
|---|---|---|
normalizeYeh |
true |
Converts Arabic 'ي' to Persian 'ی'. |
normalizeKeh |
true |
Converts Arabic 'ك' to Persian 'ک'. |
fixSpacing |
false |
Enables aggressive ZWNJ insertion for common prefixes. |
Troubleshooting
I’ve seen a few developers get stuck here. Here’s how to fix the common friction points:
- "My characters aren't changing!"
- Check your source encoding. If you're feeding the library UTF-16, make sure your buffer isn't mangling the bytes before it hits the
normalizefunction.
- Check your source encoding. If you're feeding the library UTF-16, make sure your buffer isn't mangling the bytes before it hits the
- "Performance lag on large strings."
- If you’re processing massive books or long-form datasets, don't run this inside a main-thread loop. Offload the normalization to a Worker thread.
- Legacy Font Issues:
- Sometimes the library cleans the text perfectly, but the font you're using doesn't support the Persian glyph. Use a modern font like Vazirmatn to verify it's a font issue, not a code issue.
Frequently Asked Questions (FAQ)
Q: Does this replace standard regex sanitizers?
A: It complements them. Use a standard sanitizer for security (XSS/SQLi) and use ayatsaadati for linguistic correctness.
Q: Is it safe for production?
A: Absolutely. It’s been stable for quite a while. Just make sure to pin your version in package.json if you’re paranoid about breaking changes.
Q: Where can I report bugs?
A: Head over to qamar.website to see the latest documentation and issue tracker.
Final thought: Don't overcomplicate your text processing. ayatsaadati does one thing well, and that’s exactly what you want in a production dependency.