An OJS Theme for Arabic and Persian Journals: What RTL Support Actually Requires

Some of the largest communities of Open Journal Systems users publish in languages written from right to left. Iraq, Iran, Egypt, Saudi Arabia and Jordan together run thousands of OJS journals, and many of them serve their readers an Arabic or Persian interface. Most third-party OJS themes were never tested in that mode. Switch the language and the menu sits on the wrong side, icons point the wrong way, and the text renders in whatever Arabic font the operating system happens to have.

This article explains what OJS already does for right-to-left (RTL) languages, where themes break, and what a theme has to do to deserve the label “RTL support”. It ends with a short checklist you can use on any theme, ours included.

What OJS does on its own

OJS knows which locales are right-to-left. When a reader switches the interface to Arabic, Persian, Urdu, Kurdish Sorani or Hebrew, the platform sets dir="rtl" on the page body. Browsers take it from there: text runs from right to left, lists indent on the right, and any layout written with direction-aware CSS mirrors itself automatically.

The default theme that ships with OJS includes a dedicated stylesheet for this case. That is why a plain OJS installation looks acceptable in Arabic, and why the problems start the moment a journal installs a third-party theme.

Where themes break

A theme is mostly CSS, and CSS has two ways to say “left”. The old way is physical: margin-left, padding-right, left: 0, text-align: left. Those rules mean the same thing regardless of the reading direction, so a sidebar pushed to the left in English stays on the left in Arabic, where readers expect it on the right. The new way is logical: margin-inline-start, padding-inline-end, inset-inline-start, text-align: start. Those rules follow the direction of the document and flip on their own.

Most third-party OJS themes we have looked at, including, until recently, the two we sell, were written with physical properties. In an English journal nobody notices. In an Arabic journal the result is a page where the text reads from the right while the frame around it is still built for the left: the logo and the navigation on the wrong side, article cards with their accent border on the wrong edge, dropdown menus opening off-screen, and “next” arrows pointing backwards.

There is a second, less visible failure. Themes ship their own fonts, and those fonts usually contain Latin glyphs only. Arabic text then falls back to a system font that does not match the design, with the wrong weight and line height. The layout may be mirrored correctly and still look broken.

The third failure is invisible until you know to look for it. OJS builds the translation bundle for a plugin only from the requested language. A theme that ships English and Polish strings, but no Arabic file, prints raw keys such as ##plugins.themes.clarity.articles## in the Arabic interface. There is no fallback to English.

What “RTL support” has to mean

When we added right-to-left support to Clarity and Opus, the work came down to five things. Any theme that claims RTL support should be able to show you the same five.

1. Logical CSS properties everywhere. Every physical left or right rule replaced with its logical counterpart, and a check in the build that fails when a new physical rule sneaks in. Clarity needed 51 replacements, Opus 27.
2. A short RTL stylesheet for what logical properties cannot express. Icons drawn with CSS transforms, arrow glyphs typed into templates, the position of a select box caret, a shadow that should fall to the other side. This file should be short. If it is long, the theme is patching over physical CSS instead of fixing it.
3. Bundled Arabic fonts. We ship Noto Sans Arabic and Noto Naskh Arabic with both themes, declared with unicode-range so they activate only for Arabic-script glyphs. Latin text keeps whichever of the four typography pairings the journal chose, and no request goes to Google Fonts.
4. Translation files for the RTL locales. Both themes now include Arabic and Persian strings for every key, so the interface never shows raw keys. Urdu, Kurdish and Hebrew fall back to the platform’s own translations for the core interface; theme-specific strings in those three languages are still English.
5. Testing in the actual interface, on both supported OJS versions. We compared the English layout pixel by pixel before and after the change to make sure nothing moved, then reviewed the Arabic and Persian interfaces on the home page, issue table of contents, article page, archive, login form and mobile view, on OJS 3.4 and 3.5.

Two details from that work are worth passing on to anyone doing the same. Hidden elements positioned with left: -9999px, a common trick for screen-reader-only links, create ten thousand pixels of scrollable overflow in an RTL document and can push the whole page out of view; the logical inset-inline-start does not. And carousels need no special handling if the library reads the document direction; Swiper, which OJS uses for highlights, does.

How Clarity and Opus look in Arabic

Both demos below are rendered from a real OJS 3.5 installation with the interface switched to Arabic. Nothing in them is a mock-up.

• Clarity in Arabic, the modern theme with the highlights carousel and the issue hero.
• Opus in Arabic, the serif-first scholarly theme.

The product pages for Clarity and Opus list the RTL support alongside the other features. It ships in the current releases for both OJS 3.4 and OJS 3.5, at no extra cost.

A checklist for evaluating any OJS theme for RTL

Before buying or installing a theme for an Arabic, Persian, Urdu, Kurdish or Hebrew journal, ask the vendor these six questions, or check the theme yourself on a test installation:

1. Does the theme’s CSS use logical properties, or does it rely on a separate RTL stylesheet that overrides physical rules? The first is a design decision; the second is a patch that breaks with every update.
2. Does the theme ship fonts with Arabic glyphs, or does Arabic text fall back to the system font?
3. Does the theme include translation files for your interface language, so that no ##keys## appear?
4. Were the Arabic and English versions compared after the RTL work, or was RTL added without checking that the English layout survived?
5. Is RTL support present on the OJS version you actually run, not just the newest one?
6. Can you see a demo rendered from a real installation in your language, rather than a screenshot?

If the answers are yes, the theme will serve your readers properly. If the vendor cannot answer, the safest choice for an RTL journal remains the default OJS theme, which is at least tested in that mode. And whichever theme you choose, install it from a source you can identify; our OJS security checklist explains why that matters more than any visual feature.