What actually breaks when you build a website in Arabic

Most teams find out their site does not work in Arabic on the day they publish it. The switch itself is trivial: set the document direction and the text flows the other way. What nobody warns you about is the second category of problem, the kind that throws no error and looks plausible in a screenshot, but leaves the page quietly pointing the wrong way. This is that list, written from building and shipping a site in English, Arabic and French at the same time.

Why does my layout break when I switch to Arabic?

Because direction: rtl only reverses text flow, and most of a layout is not text flow. It correctly flips the reading order of inline content and the default alignment of blocks. It does nothing at all to an element positioned with left: 5px, an image cropped with object-position, a keyframe that translates by a negative percentage, or an icon drawn pointing right. Each of those keeps its physical direction while everything around it reverses, so the page ends up internally contradictory rather than visibly broken. That is why these bugs survive review: the screenshot looks fine, and only somebody reading Arabic notices the toggle thumb is sitting under the wrong option.

Some of it, and the part it handles is the part that was never hard. Webflow applies right-to-left automatically on published sites for Arabic, Persian, Hebrew, Urdu and Yiddish locales. Next.js needs one attribute on the html element. Either route gives you correct text flow and nothing else on this list, because the platform does not know which of your icons encode a direction, which of your images have a subject rather than a texture, or which of your keyframes assumed a left-running layout. Treat automatic right-to-left as the start of the work rather than as the feature. What it does buy you is that every remaining problem lives in your own code, where you can actually fix it.

Why do my numbers come out backwards in Arabic?

The Unicode bidirectional algorithm is reordering them, and it is doing exactly what it was designed to do. In a right-to-left paragraph a trailing plus or percent sign is a neutral character, so the algorithm resolves its position from the surrounding direction rather than from the order you typed. 100+ renders as +100, and 50% as %50. The digits themselves stay in the right order; only the attached symbol moves. The fix is to tell the algorithm that the numeral is its own small island, with direction: ltr and unicode-bidi: isolate on the span that holds it. Pair that with font-variant-numeric: tabular-nums if the value counts up, or the digits will jitter as their widths change.

Should I mirror the icons too?

Mirror the ones that mean a direction, and nothing else. An arrow pointing to the next slide, a chevron in a breadcrumb, a back button: those encode direction and have to flip with the layout. A brand logo, a play button, a clock face and a checkmark do not, and mirroring them ranges from wrong to embarrassing. The trap is that the rule people reach for is a blanket one, and blanket rules catch things you never aimed them at. A selector broad enough to flip every arrow will eventually flip a partner logo, on the day somebody drops one into that container. Scope the mirroring to a class you apply on purpose, never to every SVG inside a flipped subtree.

Why does my marquee scroll off the screen in Arabic?

Because the keyframe moves it in a fixed direction while the layout now starts from the opposite edge. A scrolling logo strip normally animates to translate3d(-50%): the track begins at the left edge, travels leftward, and a duplicated half keeps the loop seamless. Flip the document and the track now begins at the right edge, but the animation still runs leftward, so it walks away from the viewport and leaves a growing gap behind it. Percentages inside a transform resolve against the element's own box, not against the writing direction, so nothing about the flip ever reaches them. You need a second keyframe ending at positive 50 percent, and a rule that selects it only under right-to-left.

Why is the person in my photo cropped out in Arabic?

Because object-position moves the crop window rather than the subject, and the two travel in opposite directions. This one is counterintuitive enough to be worth stating flatly: to carry a subject who sits right of centre further into frame, you raise the X value, which moves the window to the right and therefore carries the subject to the left. A mirrored layout usually wants the opposite value from the one that worked left-to-right. Because a portrait that is slightly off still reads as a portrait, this is the failure most likely to reach production unnoticed. Check the crop on every image that has a subject rather than a texture, and check it in the real locale instead of imagining the flip.

Which CSS properties should I be using instead?

Use the logical ones, which resolve against the writing direction instead of against the screen. Written this way, most of a layout flips correctly with no direction-specific CSS at all, and that is the real goal: not a second stylesheet, but one stylesheet that was never direction-dependent to begin with. Keep a list of the properties that have no logical equivalent, because those are precisely the ones that will need a manual override later. Transforms, object-position, background-position, gradient angles and anything driven by keyframes all stay physical, which is why every problem earlier in this article lives in that group rather than in margins and padding.

• margin-left becomes margin-inline-start, and margin-right becomes margin-inline-end.
• padding-left and padding-right become padding-inline-start and padding-inline-end.
• left and right become inset-inline-start and inset-inline-end.
• text-align: left becomes text-align: start, and float: right becomes float: inline-end.
• No logical equivalent exists for transform, object-position, background-position or gradient angles. Those need an explicit right-to-left rule.

Does Arabic need a different font?

Yes, and not only for glyph coverage. Arabic is a joining script: each letter changes shape according to what sits either side of it, so a face has to carry the initial, medial, final and isolated forms plus the ligatures between them. A Latin family that happens to include some Arabic glyphs will usually render them disconnected, at the wrong optical weight, or both. Pair a real Arabic family with your Latin one and declare both in the same stack. Two consequences follow from the script itself. Arabic has no mid-word break, because the letters of a word are joined, so a narrow column that wraps English will overflow instead. And translated strings rarely match their source in length, which means every button and input wants testing in both languages.

How do you actually test a right-to-left build?

Read it in the real locale, on a real device, with somebody who reads the language. Everything short of that is a partial check. A screenshot diff will not catch a mirrored logo, because a mirrored logo is still a logo-shaped object in a logo-shaped space. A visual regression suite will not catch a numeral rendering as +100, because that is three correct glyphs in a plausible order. Automated tooling earns its place on the mechanical half of the job, catching hard-coded physical properties in the stylesheet before they ship. The failures that survive into production are semantic, and a person who reads Arabic finds them in a minute. Budget that review into the build rather than asking for it as a favour afterwards.