# 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](../../customization/internationalization/).

<Aside type="caution">
  The Arabic text is machine translated, in Modern Standard Arabic. Have a
  native speaker review it before you launch an Arabic site.
</Aside>

### 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`:

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

| Key            | What it does                                                                     |
| -------------- | -------------------------------------------------------------------------------- |
| `languageName` | The name shown in the language switch                                            |
| `languageCode` | The address prefix (`/ar/`) and the file suffix (`ar.json`, `menu.ar.json`)      |
| `contentDir`   | The folder name inside each content folder                                       |
| `dir`          | `rtl` or `ltr`. This one value sets the direction of the page                    |
| `ogLocale`     | The language code for social previews, such as `ar_SA` or `fr_FR`                |
| `dateLocale`   | The format for dates, such as `ar` or `fr-FR`                                    |
| `weight`       | The language's position in the language switch                                   |

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.

<Steps>

1. Run `npm run generate-multilingual-content`, with the options on your theme's [Internationalization](../../customization/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`.

</Steps>

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

```toml
# src/config/config.toml
[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](../../customization/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:

| Instead of                 | Use                                     |
| -------------------------- | --------------------------------------- |
| `ml-*`, `mr-*`             | `ms-*`, `me-*`                          |
| `pl-*`, `pr-*`             | `ps-*`, `pe-*`                          |
| `left-*`, `right-*`        | `start-*`, `end-*`                      |
| `text-left`, `text-right`  | `text-start`, `text-end`                |
| `rounded-l-*`, `rounded-r-*` | `rounded-s-*`, `rounded-e-*`          |
| `border-l-*`, `border-r-*` | `border-s-*`, `border-e-*`              |
| `space-x-*`                | `gap-*`                                 |
| `margin-left` in CSS       | `margin-inline-start`                   |
| `padding-right` in CSS     | `padding-inline-end`                    |
| `left: 0` in CSS           | `inset-inline-start: 0`                 |
| `text-align: left` in CSS  | `text-align: start`                     |

`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
```text
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.
```