Our approach to building Persian–English websites

Alongside our own products, our team designs and builds websites. Two of them are live, and both are in Persian and English: Zagros Star, an international business advisory firm in Tehran, and Tolid Daru, which makes and imports veterinary medicines. They look nothing alike, but underneath they are built on the same decisions. Doing two languages well is much more than translating the text: the layout runs the other way, fonts behave differently, numbers and dates have their own forms, and search engines need to know which page is for whom. This is how we approach it.

One address per language

The single most important decision: each language gets its own address. Zagros Star has its Persian pages under /fa/ and its English pages under /en/. Tolid Daru keeps Persian at the root of the site and English under /en/, and every page has a corresponding version in the other language: each of its 56 products has a Persian page and an English one. A language switch that only swaps the text with JavaScript on the same address looks neat, but search engines index one version of a page per address, so the other language effectively disappears from search.

With separate addresses, every page tells search engines about its corresponding language version:

• A hreflang link for every language version, including the page itself, plus an x-default for visitors whose language is neither. Both sites mainly serve Persian-speaking clients, so on both the x-default is the Persian page.
• A canonical link pointing to the page itself, never to the other language. Pointing the Persian page's canonical at the English one tells Google they are duplicates, and the Persian page can drop out of results.
• The same pairs in the sitemap, so the relationship is stated twice. Tolid Daru's sitemap lists 130 addresses, each with its corresponding language version.

Google's documentation on localized versions of pages is the reference here, and worth reading in full. For the rest of the technical checks on a Persian site (titles, Persian characters, speed with Persian fonts, hosting), see our SEO checklist for Persian websites.

The language switch opens the same page in the other language

A visitor reading about one product who presses "EN" should land on the same product in English, not on the English home page. On Tolid Daru, the language link on every product page opens the corresponding language version of that product. We never guess a visitor's language from their IP address: it is often wrong (travellers, VPNs), and it confuses search crawlers, which usually crawl from one country. The choice is the visitor's.

Right to left is more than text alignment

Setting dir="rtl" on the Persian page's <html> element flips the direction of the text, and with modern CSS most of the layout follows: grids and flex rows run right to left by themselves. The trouble comes from properties that name a physical side.

• Use logical properties. margin-inline-start and padding-inline-end follow the text direction; margin-left does not. Zagros Star's stylesheet is written this way, so one set of rules serves both directions.
• Decide what not to mirror. Arrows and progress should point the reading direction. Logos, photographs, code, phone numbers and brand names in Latin script should not flip.
• Isolate mixed runs. A Latin word or number inside a Persian sentence can make punctuation jump to the wrong place. Wrapping it in <bdi> or giving it unicode-bidi: isolate keeps it in order.

Each language its own type

• Use a real Persian font, and pair it. Fonts designed for Latin often include Arabic letters as an afterthought, with the wrong forms for Persian. Both sites set Persian in IRANSansX, a typeface designed for Persian, and give English its own faces: Playfair Display and Montserrat on Zagros Star, Sora on Tolid Daru. Each language reads as if the site had been designed in it.
• Give the lines more room. Persian letters carry dots and marks above and below; a line height that suits English clips them. Persian body text needs noticeably looser lines.
• Never add letter-spacing. Persian letters join; spacing between them breaks the joins. The same goes for capitals: Persian has none, so a text-transform meant for English labels has to be switched off.
• Justified text has no kashida. Traditional Persian typesetting stretches words with the kashida (ـ) to justify lines; browsers stretch the spaces instead. It works, but check it on narrow phone screens.

A search that forgives the way people type

Persian is typed in more ways than it looks. Some keyboards produce the Arabic ي and ك instead of the Persian ی and ک; people type a space where a half-space (نیم‌فاصله) belongs, or the reverse; digits come in Persian, Arabic or Western forms. They look nearly the same and are different characters, so a strict search finds nothing.

Tolid Daru's product search brings both the query and the catalogue to one form before comparing them: Arabic letters become their Persian forms, a half-space counts as a space, every kind of digit becomes the same digit, and the short vowel marks are dropped. On top of that it accepts small typing mistakes, so a misspelt product name still finds the product, in either language. The rest of that site, its catalogue and its order box, is in our Tolid Daru case study.

Digits and dates

Persian readers expect Persian digits (۱۲۳) and the Solar Hijri calendar. Browsers can do both natively: Intl.NumberFormat('fa-IR') formats numbers, and Intl.DateTimeFormat with the fa-IR-u-ca-persian locale gives Persian dates without any library. Keep the underlying data in one standard form (Western digits, ISO dates) and convert only for display, so that sorting, search and structured data stay consistent.

Pages that arrive complete

Search engines and link previews read the HTML the server sends. On both sites, each page's text is in that HTML in its own language: Tolid Daru's product pages are written out as plain pages in both languages from a single source of product information, so a correction made once reaches both. Each site also describes its company to search engines in structured data, in both languages.

Write naturally in each language

Finally, the part no code fixes: a page that reads like a translation reads like a translation. Write the Persian and the English from the same facts, each in the way people actually write in that language, and have a native speaker read each one. Search engines reward pages people want to read, and people can tell.