Shopify Arabic store: set the direction, then fix the theme

Who decides which way an Arabic page flows?

The browser does, from one attribute. The W3C’s guidance on structural markup and right-to-left text says to add dir="rtl" to the html element whenever the overall document direction is right-to-left, because the default base direction in HTML is left-to-right when nothing sets it. MDN’s reference for the dir attribute makes the same point from the other side: omitting dir does not turn on automatic detection, and for right-to-left scripts the default is the wrong one. A page in Arabic with lang="ar" and no dir is therefore laid out left to right, with the punctuation at the wrong end of every sentence and the paragraphs aligned to the wrong edge.

The W3C page adds two rules that matter for a theme. Do not use CSS to apply the base direction; set it in the markup. And use logical values (start and end) for margins, padding and alignment, so that the same stylesheet works in both directions. MDN’s direction property page repeats it: authors are encouraged to prefer the HTML dir attribute over the CSS property.

What does Shopify give a theme to work with?

One value. The shop_locale object has a direction property that returns rtl for right-to-left locales and ltr for the rest, and the documentation says you can use it to set the dir attribute on the html element so the page flows correctly. The current locale is on request.locale, so the whole job in layout/theme.liquid is:

<html lang="{{ request.locale.iso_code }}" dir="{{ request.locale.direction }}">

That is the only line the platform asks of a theme. It is also the line most themes did not need until an Arabic locale was published. We read the two reference themes on 27 October 2026. Dawn’s theme.liquid opens with <html class="js" lang="{{ request.locale.iso_code }}">: the language is written, the direction is not. Horizon’s writes dir="{{ request.locale.direction | default: 'ltr' }}" on its html element. A store on Dawn or a theme forked from it will publish Arabic pages that declare the right language and the wrong direction.

Setting the attribute is necessary and not sufficient. The browser now flows text, flex rows and table columns from the right, but any rule written as margin-left, padding-right, text-align: left, left: 0 or float: right still means the physical side. The logical equivalents, which MDN’s logical properties module describes as relative to the content’s writing direction instead of the screen’s, are margin-inline-start, padding-inline-end, text-align: start, inset-inline-start and float: inline-end. A theme either already uses them or needs a pass through its CSS.

How do you test a theme in five minutes?

Do not start with a translation. Start with the markup.

1. Open any page on the store in Chrome, view source and read the html tag. If dir is missing on a locale you intend to publish in Arabic, that is the first fix.
2. In DevTools, select the html element in the Elements panel and add dir="rtl" by hand. This flips the page in the browser without publishing anything, and shows you what an Arabic reader would see once the attribute exists.
3. Look at the header, the cart drawer, the product gallery arrows, the quantity stepper, the breadcrumb separators, the sticky add-to-cart bar and the footer columns. Anything that stayed on the left, or whose arrow still points the old way, is a physical property in the stylesheet.
4. Search the theme code for left, right, margin-left, margin-right and float. Each hit is a decision: if the element should follow the reading direction, replace it with the logical property. If it should stay (a slider that always moves one way, say), leave it.
5. Open a page with numbers and Latin text inside Arabic: a product title with a model code, a phone number, a price block. Mixed text is where the Unicode bidirectional algorithm, which MDN’s dir page says uses the base direction to order runs of text, shows its limits.

Anything a customer types or a merchant pastes should carry dir="auto" rather than inherit the page direction. MDN’s guidance is that auto is for data of unknown directionality such as user input, and the same page notes that it reads the first strong character. Review text, search boxes and address fields are the places that matter on a store.

What does Google need to find an Arabic page?

Three things, none of them in the CSS. First, the pages must exist at their own URLs. Publishing a language gives it its own URL path, so Arabic pages need a locale in Shopify’s language settings before they exist. Second, the content on those URLs has to be translated. Google’s guide to localised versions of a page says it does not use hreflang or the HTML lang attribute to detect the language of a page and uses its own algorithms instead, which means an Arabic locale with English product copy is not an Arabic page to Google, whatever the tags say. Third, the hreflang set has to include ar. Shopify writes these through content_for_header; we cover what it emits, the mistakes that follow and the reasons to prune the market list in our guide to hreflang on Shopify. The language code in the tag is the ISO 639-1 code, ar, with an optional region as in ar-AE, and Google’s page states that only codes from ISO 639-1 and ISO 3166-1 alpha-2 are supported.

What changes with Arabic is not the tag but the dependency chain behind it: translation of every product and collection field, a theme that renders the translated strings in both directions, and a language switcher that links to /ar/ as a real anchor.

Which parts of the storefront break first?

The ones built from physical assumptions. This is the order we would check them in:

• The header and navigation. Logo position, search icon, cart icon and the mega-menu alignment all follow flex-direction and text-align. Row layouts flip with the attribute; absolutely positioned dropdowns do not.
• Icons that carry direction. Chevrons, back arrows, carousel controls and breadcrumb separators point left or right as part of their meaning. They need mirroring in RTL; a magnifier, a heart or a cart do not.
• Product galleries and sliders. Scroll position, snap alignment and thumbnail strips are set up in JavaScript in many themes with scrollLeft assumptions. Test swipe and the arrow buttons in both directions.
• Forms and checkout fields. Email addresses, phone numbers and coupon-style codes are left-to-right text inside a right-to-left form. Set them as such rather than inheriting.
• Typography. Arabic needs a typeface with Arabic glyph coverage; a theme font that only ships Latin falls back to whatever the system provides, and the fallback changes line height and weight. Our guide to font loading covers how web fonts load on a theme.

Merchants who sell into the Gulf from Switzerland or Europe, as in our Switzerland guide, should also remember that adding Arabic is a market decision before it is a theme change: a locale published before its catalogue is translated creates duplicate-content pages, not an Arabic storefront. For the UAE side of our work, see Shopify agency in Dubai.

What should you fix first, and how long does it take?

1. Read the html tag on every locale you publish (five minutes). If dir is absent, add dir="{{ request.locale.direction }}" in layout/theme.liquid. The change is one line and affects only locales that return rtl.
2. Flip the page by hand in DevTools and screenshot the header, product page, cart and footer (half an hour). The screenshots are your defect list.
3. Replace physical CSS properties with logical ones on the elements that should follow the reading direction, and mirror direction-bearing icons (a day or two on a typical theme, more if the CSS is spread across apps).
4. Translate the catalogue before publishing the ar locale, then confirm hreflang includes ar on every language version of a page (an afternoon, plus the translation itself).

If you would rather have the theme’s directional assumptions, the locale setup and the hreflang output read on your own store, that is part of what our Store Teardown looks at.