RTL & Arabic

RTL & Arabic

Files: src/config/language.json, src/config/fonts.json, src/i18n/ar.json, src/config/menu.ar.json, src/content/**/arabic/ · Skill level: Beginner

In the Sanity edition, Arabic content, menus, and labels are documents in the Studio, under the Arabic entry. language.json and fonts.json stay in the project in every edition.

The theme supports right-to-left (RTL) languages throughout, and ships with Arabic as a complete example at /ar/. Every page, menu, and label has an Arabic version. For how languages work in general, see Internationalization.

What Changes In RTL

Direction comes from one setting, so there is nothing to switch on page by page. On a page in an RTL language:

• <html> gets the right lang and dir="rtl", and the layout mirrors.
• Menus, flyouts, the mobile panel, and their keyboard arrows follow the direction.
• Arrows and other direction icons flip. Carousels and scrolling logo rows run the other way.
• Code, email addresses, web addresses, phone numbers, and prices that need it stay left to right.
• Arabic text uses an Arabic font, which loads only on Arabic pages. Latin text stays in the theme’s Latin font.
• Dates use the language’s format.
• The llms files and Markdown copies work at /ar/llms.txt and /ar/llms-full.txt.

The Language Entry

This is the Arabic entry in src/config/language.json:

{
  "languageName": "العربية",
  "languageCode": "ar",
  "contentDir": "arabic",
  "dir": "rtl",
  "ogLocale": "ar_SA",
  "dateLocale": "ar",
  "weight": 3
}

Every language has these keys. The theme reads them from this file, so you never list languages anywhere else.

Add Another RTL Language

These steps add Hebrew. Any RTL language works the same way.

1. Run npm run generate-multilingual-content, with the options on your theme’s Internationalization page, and add --dir rtl. The options can differ by edition. For Hebrew, the code is he, the name is עברית, the folder is hebrew, the locale is he-IL, and the social locale is he_IL.

   It adds the language to language.json, and makes copies of your default language to translate. In the Sanity edition, the copies are new documents in your project.

2. In the Tina edition, run npm run tina:generate so the editor knows the language.

3. Translate the new content, menu, and interface labels.

4. If you host on Netlify, check netlify.toml for a /he/* block. If the script didn’t add one, copy the /ar/* block for /he/*.

5. Add a font that covers the language to src/config/fonts.json, using the Arabic font as your model. The Arabic text styles use :lang(ar) in the CSS, so add the same rules for your language if it needs them.

6. Restart npm run dev, open /he/, and check the menu, a form, and a blog post. Then run npm run astro-check.

Remove Arabic

To turn Arabic off and keep the files, add it to disableLanguages:

[settings.multilingual]
  disableLanguages = ["ar"]

npm run remove-multilingual removes every language except your default one. In the Astro and Tina editions, it deletes their files, so save a git commit or a copy of the folder first. In the Sanity edition, their documents stay in your project unless you add -- --delete-online, which can’t be undone. Read Internationalization before you run it.

If You Add Your Own Code

Use logical CSS, which follows the direction of the page, instead of left and right:

translate-x-*, transform-origin, and gradient directions have no logical version, so handle them with the rtl: variant or [dir="rtl"].

Other rules:

• Direction icons flip in one central list in the icon component. Add new ones there, not where you use them.
• Wrap values that must stay left to right with dir="ltr" or <bdi>, such as a phone number or a code sample.
• Under :lang(ar), don’t add letter-spacing or text-transform, because they break Arabic script.

Do It With AI

Add [LANGUAGE] as a right-to-left language. Use npm run generate-multilingual-content with
--dir rtl, then translate the new content, menu, and interface label files. Keep every key and
frontmatter field. Add a font that covers the language to src/config/fonts.json. Use logical CSS
only. Don't run remove-multilingual. Then run npm run astro-check and list the pages I should
check by eye.