Adding Persian, right to left, to a Next.js admin panel: what broke and how we fixed it

What it is

Sponsor Bot is a self-hosted platform for Telegram uploader bots with a forced-join gate, sponsor campaigns and an ad shop (its engine, the queues and the TRON payments, are in an article of their own). Its panel, about 23,500 lines over 30 pages of Next.js, Tailwind CSS and Radix, was built in English and then made bilingual: English left to right, Persian right to left, each person choosing theirs. The work went page by page in nine phases, and each was checked in both languages at desktop and phone width before the next. The live demo has the language switch on its sign-in page and in the user menu.

This article is for anyone, person or AI, adding a right-to-left language to an existing React app: how the language is chosen and carried, what changes for layout, type, digits and dates, what must stay left to right, how the server and a Telegram bot speak the language too, and nine things that went wrong on the way, each with its fix.

Choosing and carrying the language

The choice is a cookie, sb_lang (en or fa), set from the user menu, Settings → Appearance and the sign-in pages. The server draws <html lang dir> from it, so a change reloads the page, and Radix's direction provider gets it too, so menus, selects and submenus open the right way. Until someone picks, the panel is English whatever the browser's language: the first version guessed from the browser, and Ramin chose English for everyone who hasn't picked. The addresses don't change: it's an admin panel, nothing for search engines.

Words sit next to the markup that shows them, typed so a missing Persian string fails the build:

export type Copy<T> = Record<Lang, T>;

/** For words kept in pairs where they're used: `const t = inLang(lang)`, then `t("Bots", "ربات‌ها")`. */
export function inLang(lang: Lang) {
  return <T>(en: T, fa: T): T => (lang === "fa" ? fa : en);
}

Sentences with a number in them are functions, because the two languages build them differently. English makes the noun plural; Persian keeps it singular after a number and puts the words around it in another order:

Right to left: logical sides, and one rule for arrows

Every physical side class became a logical one: ml-/mr- to ms-/me-, pl-/pr- to ps-/pe-, left-/right- insets to inset-s-/inset-e-, text-left to text-start, borders and rounded corners likewise. That was 262 classes in 57 files, and English renders exactly as before. Centring (left-1/2 -translate-x-1/2) stays physical, since it is symmetric anyway.

Arrows and chevrons that mean "onward" (next, continue, open, sign out) have to point the other way. Rather than a class on every icon, one rule at the end of the stylesheet turns them all:

Adding Tailwind's rtl:-scale-x-100 to one of these icons on top of it would turn it back again.

What stays left to right

Some things read left to right whatever the page: e-mail, password, URL and number fields (the shared Input sets dir="ltr" for those types), codes and keys, @usernames, addresses, transaction hashes, versions and file names. Charts and the day's time track stay left to right too, since time runs left to right like a clock's numbers; their Persian labels are isolated so they keep their own word order. Inside a sentence, two helpers wrap a piece of text in Unicode's directional isolates:

U+2066 (left-to-right isolate) and U+2067 (right-to-left isolate) open a run that the surrounding text can't reorder, and U+2069 closes it, so "@sponsor_bot" in a Persian sentence keeps its "@" in front.

On elements, dir="ltr" does the same, and that is where the first trap was:

Type: Vazirmatn, and what Persian can't do

The Persian face is Vazirmatn, placed after the Latin faces in every font stack: Latin letters keep their own faces on Persian pages, and thanks to the fonts' unicode-range, only the Arabic-script file is ever fetched, and only for a page with Persian on it. Persian letters join one to the next, so the rules differ:

No letter-spacing (the tracked labels would pull joined letters apart), no italics (a slanted Persian word is only a distorted one), and a little more line height for titles set at 1, which would clip Persian's dots.

Digits and dates

Both are one line each, and both were Ramin's calls after seeing the pages:

Persian pages use Western digits (0–9): Persian ones broke the panel's rhythm and its alignment. Dates are Gregorian with Persian month names ("11 اکتبر 2026"). Every formatter reads its locale from these, fa-IR-u-ca-gregory-nu-latn, and setting the Persian entries to "persian" and "arabext" brings the Solar Hijri calendar (مهر ۱۴۰۵) and Persian digits back everywhere; that code stays, and the browser's own persian calendar data was checked for every month of 1390–1420, leap years included. Month grids start on Saturday and run right to left in Persian, the week grid reads clicks and drags from its right edge so a drag picks the days under the pointer, and weekdays stay ISO numbers (1 Monday … 7 Sunday) in the data: only their order on screen changes.

The server and the bot speak it too

The API answers in the panel's language: a small middleware first in the pipeline reads the same cookie into an AsyncLocal, so the error handler after it follows too, and every message the panel can show, about 330 sentences, is written as a pair. Sentences the server stores and shows later (why an ad's time failed, a payment check's note) are stored in English whoever's request made them, and translated when they are read, so a Persian owner and an English admin each read the same note in their own language.

Each bot has a language of its own, chosen when it is connected, with Persian defaults for all 80 of its texts. A Persian bot writes dates ("چهارشنبه 14 اکتبر · 10:00"), durations and lists in Persian. Telegram brought two more things to handle:

The lookbehind skips a @ or / that is part of a word, an address or a link, and one that already has a mark.

Checking it, and a trap in the checker

Each phase was checked in headless Chrome at 1440 px and 390 px, in both languages, before it was committed; the typed copy means a missing Persian string fails tsc; and 19 server tests hold the API to answering in Persian with the cookie and in English without, and a Persian bot to greeting, gating and answering its uploader in Persian.

If you're doing the same

The order that worked: make the language a cookie the server reads, so <html lang dir> is right in the first byte; sweep every physical side class to a logical one before translating anything; decide early what stays left to right, and give it dir="ltr" on the innermost element or an isolate; type the copy so a missing translation can't ship; decide digits and calendar with the people who will read it, in one place; and check every page in both directions at phone width, with a viewport screenshot.