# RTL & Arabic

## RTL & Arabic

**Files:** `src/config/language.json`, `src/content/<collection>/arabic/`, `src/i18n/ar.json`, `src/config/menu.ar.json` · **Skill level:** Beginner

Givo ships in English, French, and Arabic. Arabic is written right to left (RTL), and every Arabic page is mirrored: the header, menus, mega menu, cards, forms, progress bars, and arrows all flip, so the page reads naturally from the right. Arabic pages live under `/ar/`, for example `/ar/donate/`.

You don't need to do anything to get this. If you don't need Arabic, you can turn it off (see below). If you add another right-to-left language, such as Hebrew, Persian, or Urdu, it works the same way.

<Aside type="caution">
  The Arabic text in the theme is a machine translation. Have a native speaker
  review it before you publish the Arabic pages.
</Aside>

### How A Language Becomes Right To Left
Each language is one entry in `src/config/language.json`. The Arabic entry is:

```json
{
  "languageName": "Ar",
  "languageCode": "ar",
  "contentDir": "arabic",
  "weight": 3,
  "ogLocale": "ar_SA",
  "dir": "rtl",
  "dateLocale": "ar"
}
```

`"dir": "rtl"` is the switch. It sets `dir="rtl"` on the page, and the theme's layout follows it. `dateLocale` sets how dates and numbers are written.

### What Changes On Arabic Pages
- **Layout**: columns, margins, and alignment mirror. Text starts on the right.
- **Menus**: dropdowns and flyouts open toward the left, the mobile menu slides in from the other side, and the `Left` and `Right` arrow keys follow the reading direction.
- **Progress bars**: the bar on cause cards and cause pages fills from right to left.
- **Arrows and chevrons**: icons that point in a direction mirror themselves.
- **Font**: Arabic text uses Readex Pro (`--font-arabic` in `src/config/fonts.json`), with no letter spacing. The wordmark keeps the brand font.
- **Numbers and amounts**: they keep Western digits (0 to 9), so $1,250 and dates read the same as on the English page. Phone numbers, emails, and web addresses stay left to right.
- **Counted labels**: Arabic has more plural forms than English. "1 donor", "2 donors", "3 donors", and "11 donors" each get the right Arabic word (see below).

### Plural Labels
Labels with a number, such as "412 donors" or "3 days left", come from `src/i18n/<language>.json`. English and French need two forms, for one and for more than one:

```json
"donors": "{count} donors",
"donorOne": "{count} donor",
```

Arabic adds `_two`, `_few`, and `_many` keys beside the plural key in `src/i18n/ar.json`:

```json
"donors": "{count} متبرّع",
"donors_two": "متبرّعان",
"donors_few": "{count} متبرّعين",
"donors_many": "{count} متبرّعًا",
"donorOne": "متبرّع واحد",
```

The theme picks the right form for each number. If you add a language with more plural forms, add the same kind of keys (`_zero`, `_two`, `_few`, or `_many`) beside each count key. `npm run check-i18n` accepts them.

### Editing Arabic Content
Arabic content is in the `arabic/` folder of each collection, with the same file names and the same keys as `english/`:

- `src/content/causes/arabic/clean-water-wells.md`
- `src/content/sections/arabic/hero-section.md`
- `src/content/donate/arabic/-index.md`

Translate the text values only. Keep keys, file names, URLs, icon names, layout values, and numbers as they are. Goals, amounts raised, donor counts, preset amounts, and tiers must be the same in every language: `npm run build` prints a `[donate]` warning when the giving numbers differ.

The Arabic menu is `src/config/menu.ar.json`, and the Arabic interface text (buttons, labels, form messages) is `src/i18n/ar.json`. See [Internationalization](/givo/customization/internationalization/) for the full list.

### Remove Arabic
To hide Arabic without deleting anything, add its code to `disableLanguages` in `[settings.multilingual]` in `src/config/config.toml`, then restart the dev server:

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

To delete it for good, remove the `arabic/` folders, `menu.ar.json`, `ar.json`, and the Arabic entry in `language.json`.

### For Developers
If you change components, keep them working right to left:

- Use logical Tailwind classes: `ms-` and `me-`, `ps-` and `pe-`, `start-` and `end-`, `text-start` and `text-end`, `border-s` and `border-e`. Never `ml-`, `pr-`, `left-`, or `text-left`.
- In raw CSS, use `margin-inline`, `padding-inline`, `inset-inline`, and `text-align: start`.
- `translate-x-*`, `transform-origin`, and gradient directions do not flip by themselves. Add `rtl:` or `[dir="rtl"]` rules for them.
- To mirror a new direction icon, add its name to the `DIRECTIONAL` list in `src/layouts/helpers/Icons.astro`. Don't flip icons where they are used. The mirroring CSS is in `src/styles/rtl.css`.
- Format money, numbers, and dates with the helpers in `src/lib/campaign.ts` (`formatMoney`, `formatNumber`, `formatPercent`, with `localeFor`), so Arabic keeps Western digits.
- Open the page at `/ar/` after every layout change.

`AGENTS.md` in the theme has the full list of these rules, so AI tools follow them too.

### Do It With AI
```text
Check my Givo site's [PAGE] page in Arabic (/ar/[page]/) for right-to-left problems. Follow the
RTL rules in AGENTS.md: logical classes only, the DIRECTIONAL icon list in
src/layouts/helpers/Icons.astro, and the money and number helpers in src/lib/campaign.ts. List
what you find before you change anything.
```