rtl-and-persian-localization
Skill1 starsChanged 18 days agoMITView on GitHub
Localize a storefront for Persian (fa_IR) and right-to-left layout: logical CSS, digits, Yeh and Kaf, ZWNJ, currency display, and Gregorian storage. Use when building or reviewing Persian, Farsi, or RTL commerce UI.
In this repository28 other files it gives its agents.
- b2b-pricingSkill
- catalog-import-and-migrationSkill
- checkout-ux-and-conversionSkill
- conversion-event-trackingSkill
- ecommerce-seo-structured-dataSkill
- fraud-and-risk-basicsSkill
- google-merchant-product-feedsSkill
- headless-nextjs-storefrontSkill
- inventory-and-multi-warehouseSkill
- iranian-payment-gatewaysSkill
- marketplace-search-and-rankingSkill
- mcp-store-toolingSkill
- multi-vendor-payoutsSkill
- order-and-webhook-reliabilitySkill
- payment-gateway-integrationSkill
- product-catalog-modelingSkill
- product-description-guardrailsSkill
- returns-and-refundsSkill
- shopify-app-developmentSkill
- storefront-accessibilitySkill
- storefront-performanceSkill
- stripe-paymentsSkill
- subscription-billingSkill
- tax-and-shippingSkill
- vector-product-searchSkill
- woocommerce-plugin-developmentSkill
- woocommerce-rest-apiSkill
- wordpress-plugin-securitySkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Use this skill for a Persian storefront or any right-to-left commerce UI.
- Very specific: line 25
Prefer margin-inline-start, padding-inline, inset-inline-start, border-inline-end, and text-align: start.
- Very specific: line 26
Use flex and grid. flex-direction: row follows the document direction.
- Very specific: line 35
Keep ZWNJ (U+200C) in stored and displayed words (میروم).
- Distinctive: line 37
Use a font that covers Arabic script.
- Very specific: line 58
Put every new string in gettext with the plugin text domain.
- Very specific: line 75
Search normalization makes كالا and کالا match.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
RTL and Persian localization
Use this skill for a Persian storefront or any right-to-left commerce UI. Search matching uses the marketplace search skill. The normalizer in scripts/normalize-persian.mjs is for display and for search text. Letter and digit rules are in the Persian text notes.
Procedure
- Set the document language and direction. For Persian,
lang="fa"anddir="rtl". In WordPress, thefa_IRlocale is RTL andis_rtl()is the check to use in PHP. - Lay out with CSS logical properties. Do not mirror the whole page with a plugin that flips
leftandrightin existing files. - Store catalog text as Unicode with Persian Yeh and Kaf and with ZWNJ where the word needs it. Store dates as Gregorian timestamps. Store money as a decimal amount plus an ISO currency code.
- Format digits for display only. APIs, SKUs, payment amounts, and HTML attributes stay ASCII.
- Translate user-facing strings with the plugin text domain. Do not hard-code Persian in a PHP string that should go through gettext, and do not hard-code English in a template that Persian shoppers see.
Direction
- Prefer
margin-inline-start,padding-inline,inset-inline-start,border-inline-end, andtext-align: start. - Use flex and grid.
flex-direction: rowfollows the document direction. Userow-reverseonly when the order is intentionally opposite to the language. - Mirror directional icons such as back and forward. Do not mirror logos, payment marks, product photos, or numbers.
- Form focus order follows the visual order. Test with the keyboard, not only with a screenshot.
- WooCommerce emails that render the same template need the same direction. A storefront
dir="rtl"does not change an email that is a separate HTML document.
Persian text
- Locale code:
fa_IR. - Fold Arabic Yeh
ي(U+064A) to Persian Yehی(U+06CC) and Arabic Kafك(U+0643) to Persian Kafک(U+06A9) when you normalize input. Shoppers and old content use both. - Keep ZWNJ (U+200C) in stored and displayed words (
میروم). Search normalization may remove it so the two spellings match. Display normalization must not. - Persian digits
۰۱۲۳۴۵۶۷۸۹are a display format. Also accept Arabic-Indic digits٠١٢٣٤٥٦٧٨٩on input and normalize them. - Use a font that covers Arabic script. A Latin-only stack renders Persian as missing glyphs.
Run the script:
node scripts/normalize-persian.mjs --file title.txt
node scripts/normalize-persian.mjs --search "كالاي ۱۲"--search prints the match form. The default prints the display form and keeps ZWNJ. --persian-digits converts ASCII digits to Persian digits for display.
Money, dates, addresses
- WooCommerce currency for the Iranian rial is the ISO code
IRR. Format the amount with the store's decimal settings (wc_get_price_decimals()), not with a hard-coded exponent. - Toman is a display and pricing decision: 1 toman equals 10 rials. If the shop charges in toman, say that in the currency label and store a consistent unit. Do not divide amounts by 10 only in the theme while checkout charges rials.
- WordPress and WooCommerce store order dates in Gregorian, with a site timezone and a GMT field. A Jalali calendar is a presentation layer. Do not write Jalali strings into order date columns.
- Iranian addresses need country
IR, province, city, street, and a 10-digit postal code. Do not require a state from a country list that has no Iranian provinces unless those provinces are actually configured. Add them through WooCommerce's country locale and state list rather than a one-off checkout hack. - Phone numbers: accept a local mobile number without a North American mask. Store a normalized form you can dial, and display the local form.
WordPress and WooCommerce
- Put every new string in gettext with the plugin text domain. Load private translations on
init. - Switch field order and labels with
woocommerce_get_country_localeandwoocommerce_localisation_address_formatsforIR, not by editing core templates first. bodygets thertlclass from WordPress when the locale is RTL. Theme CSS should key offdiror.rtland still prefer logical properties so the same stylesheet serves both directions.- Prices in templates go through
wc_price(). That helper uses the store currency settings. Do not concatenate a hard-codedریالor$in front of a raw number.
Gotchas
direction: rtlon a single inner box, while the document is LTR, traps punctuation and mixed English SKUs. Set direction on the document, and on emails, not on random cards.leftandrightin copied CSS survive an RTL locale and pin totals to the wrong side.- Replacing every digit in the HTML document breaks CSS, JSON, and payment signatures. Convert digits in text nodes you control.
- Sorting Persian with a binary code-point order is not alphabetical. Use a Persian collation when the list is a dictionary. Do not use it for SKUs.
- Translating a string that includes the price ("Pay 19.00") needs a placeholder, not concatenation:
sprintf( __( 'Pay %s', 'example' ), $formatted ).
Verification
fa_IRrenders the shopper-facing checkout RTL, with the total and the pay control aligned to the inline end.- A title that contains Arabic Yeh and Persian digits round-trips through display normalization without losing ZWNJ.
- Search normalization makes
كالاandکالاmatch. The stored title is unchanged. - An order date stored by WooCommerce remains Gregorian. Any Jalali label is display-only.
- A test payment uses the same major units the shopper saw. Toman and rial are not mixed inside one order.
Evaluation
Worked examples and the checks they must satisfy are in evals/tasks.json.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

