How to Translate RTL Languages in WordPress: Arabic, Hebrew, Persian
You have just finished translating your WordPress theme into Arabic. You upload the .mo file, switch the site language, and the result is unreadable. Text overflows to the left, buttons overlap, and your carefully designed layout looks like it was fed through a paper shredder.
Welcome to the world of Right-to-Left (RTL) languages -- where translation is only half the battle.
Arabic, Hebrew, and Persian (Farsi) are among the most widely spoken languages on earth. Arabic alone has over 400 million native speakers. If your WordPress site ignores these audiences, you are leaving serious money on the table. But serving them requires more than swapping English words for Arabic ones. It requires rethinking your entire layout direction.
This guide covers everything you need to know: how RTL works in WordPress, how to fix your CSS, how to handle .po files with RTL strings, and how to avoid the most common pitfalls.
How RTL Works in WordPress
WordPress has built-in RTL support. When you set your site language to Arabic (ar), Hebrew (he), or Persian (fa), WordPress automatically adds dir="rtl" to the <html> tag and loads an rtl.css stylesheet if your theme provides one.
This is the theory. In practice, most themes ship with minimal or broken RTL support.
What Actually Changes
When RTL mode activates, the browser mirrors the entire page layout:
- Text flows from right to left.
- Sidebars swap sides.
- Navigation menus reverse order.
- Padding and margin values flip (left becomes right).
- Icons with directional meaning (arrows, chevrons) need to be mirrored.
If your theme's CSS was written only for LTR, every margin-left, padding-right, float: left, and text-align: left declaration is now fighting against the browser's RTL engine.
Fixing Your CSS for RTL: A Practical Guide
The cleanest approach is to use CSS Logical Properties, which adapt automatically to the document's writing direction. Instead of left and right, you use inline-start and inline-end.
Before: Physical Properties (Breaks in RTL)
/* LTR-only CSS -- breaks in Arabic */
.sidebar {
float: left;
margin-right: 20px;
}
.nav-arrow {
padding-left: 10px;
text-align: left;
}
.card {
border-left: 3px solid #0073aa;
}
After: Logical Properties (Works in Both Directions)
/* Direction-agnostic CSS -- works in both LTR and RTL */
.sidebar {
float: inline-start;
margin-inline-end: 20px;
}
.nav-arrow {
padding-inline-start: 10px;
text-align: start;
}
.card {
border-inline-start: 3px solid #0073aa;
}
With logical properties, you write your CSS once and it works correctly in both English and Arabic without any overrides.
The [dir="rtl"] Override Method
If you cannot refactor your entire stylesheet, you can target RTL specifically using attribute selectors:
[dir="rtl"] .sidebar {
float: right;
margin-left: 20px;
margin-right: 0;
}
[dir="rtl"] .nav-arrow {
padding-left: 0;
padding-right: 10px;
text-align: right;
}
This works, but it doubles your maintenance burden. Every time you update your LTR styles, you must also update the RTL overrides.
Translating PO Files with RTL Strings
The translation itself introduces challenges that go beyond layout. RTL languages have unique characteristics that trip up most automated tools.
Bidirectional Text (Bidi) in PO Files
The real complexity appears when RTL and LTR text mix in a single string. Consider this common WordPress pattern:
msgid "Powered by %s"
msgstr "مدعوم بواسطة %s"
The %s placeholder will be replaced with an English product name like "WooCommerce." In the rendered output, the browser must display Arabic text flowing right-to-left, then switch to left-to-right for the English word, then potentially switch back.
This is called bidirectional text (or "bidi"), and it is handled by the Unicode Bidirectional Algorithm. Most of the time it works automatically. But when you have multiple placeholders or numbers adjacent to RTL text, the visual order can become unpredictable.
Common Translation Mistakes
Generic translation tools make several RTL-specific errors:
-
Reversed placeholder order. A string like
%1$s out of %2$smight get the placeholders swapped because the AI reorders them to match Arabic grammar. This produces incorrect output like "10 out of Page" instead of "Page out of 10." Learn more about protecting code variables during translation. -
Broken HTML directionality. If your string contains inline HTML like
<span dir="ltr">, a naive translator might strip thedirattribute or translate it. -
Missing plural forms. Arabic has six plural forms -- zero, one, two, few, many, and other. This is the most complex plural system of any language WordPress supports. A tool that only generates two forms (like English singular/plural) will leave your Arabic
.pofile broken. For a deep dive into how Gettext plurals work, see our guide on complex pluralization in WordPress.
Here is what a correctly translated Arabic plural string looks like in a .po file:
# Arabic: nplurals=6
msgid "%d comment"
msgid_plural "%d comments"
msgstr[0] "لا تعليقات"
msgstr[1] "تعليق واحد"
msgstr[2] "تعليقان"
msgstr[3] "%d تعليقات"
msgstr[4] "%d تعليقًا"
msgstr[5] "%d تعليق"
If any of those six forms are empty or incorrect, WordPress will fall back to the English string for that specific count. Your users will see "5 comments" in English scattered through an otherwise fully Arabic interface.
Testing Your RTL Implementation
Translating and fixing CSS is not enough. You need to verify the result in a real browser.
A Quick Testing Checklist
- Switch WordPress language to Arabic in Settings > General. Do not just add
dir="rtl"manually -- use the real language setting so WordPress loads its own RTL overrides. - Check navigation menus. Are they mirrored? Do dropdowns open in the correct direction?
- Inspect form fields. Input text should flow right-to-left. Placeholder text should be right-aligned.
- Verify mixed-direction content. Strings that contain both Arabic and English (like brand names or URLs) should render in the correct visual order.
- Test on mobile. RTL layout bugs are often more severe on smaller screens where there is less room for alignment errors.
If your translations are not showing up at all, the problem might be unrelated to RTL -- check your .mo file compilation and file paths first.
Browser Developer Tools Trick
In Chrome DevTools, you can temporarily force RTL on any page without changing WordPress settings:
/* Paste in DevTools console as: document.documentElement.dir = 'rtl' */
html {
direction: rtl;
}
This gives you a quick preview of how your theme handles RTL before you even start translating.
Automating RTL Translation the Right Way
Manual translation of RTL languages is expensive and slow. Professional Arabic translators charge premium rates, and finding someone who understands both the language and WordPress-specific Gettext syntax is difficult.
SimplePoTranslate solves this with a Context-Aware AI engine that understands RTL-specific challenges natively:
- All six Arabic plural forms are generated automatically. Our engine reads the
Plural-Formsheader in your.pofile and produces exactly the number of forms your target language requires. No emptymsgstrslots, no English fallbacks. - Placeholder safety. Variables like
%s,%d, and%1$sare locked during translation. The AI cannot reorder, delete, or corrupt them -- even when Arabic grammar suggests a different word order. Read more about how syntax locking protects your code. - Bidirectional context. The AI understands that mixed-direction strings need special handling and preserves HTML directionality attributes.
Whether you are localizing a blog theme for a Hebrew audience or translating a full WooCommerce store into Persian, the process is the same: upload your .po file, select your target language, and download the translated file. The entire workflow takes minutes, not days.
For a complete walkthrough of the WordPress localization process, see our ultimate guide to WordPress localization.
Stop Treating RTL as an Afterthought
Right-to-left languages represent over a billion potential users. Arabic is the fifth most spoken language in the world. Hebrew and Persian serve critical markets in the Middle East and Central Asia.
If your WordPress site cannot serve these users with a polished, native-feeling experience, they will find a competitor who can.
The good news: WordPress already has the infrastructure. Your theme just needs proper CSS, and your .po files need a translation tool that respects the complexity of RTL languages.
Ready to translate your WordPress site into Arabic, Hebrew, or Persian? Start for free at SimplePoTranslate.com