# Internationalization (Languages)

## Internationalization

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

Givo ships in **English** (the default, at `/`), **French** (at `/fr/`), and **Arabic** (at `/ar/`), with the whole layout mirrored on Arabic pages. Every page, menu, label, amount, and date exists in every language. You can keep all three, keep only your default language, or add another one. For how right-to-left works, see [RTL & Arabic](/givo/features/rtl-arabic/).

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

### What Makes Up A Language
| Part | Files |
| --- | --- |
| The language itself | an entry in `src/config/language.json` |
| Page and section text | a folder per language in every content folder, such as `src/content/causes/french/` and `src/content/sections/arabic/` |
| Interface text | `src/i18n/<language>.json`, such as `fr.json`: buttons, labels, form messages, campaign labels ("Ended", "Last day", "days left"), the page-title tagline |
| Menus | `src/config/menu.<language>.json`, such as `menu.ar.json` |

```json
[
  {
    "languageName": "En",
    "languageCode": "en",
    "contentDir": "english",
    "weight": 1,
    "ogLocale": "en_US",
    "dir": "ltr",
    "dateLocale": "en-US"
  },
  {
    "languageName": "Fr",
    "languageCode": "fr",
    "contentDir": "french",
    "weight": 2,
    "ogLocale": "fr_FR",
    "dir": "ltr",
    "dateLocale": "fr-FR"
  },
  {
    "languageName": "Ar",
    "languageCode": "ar",
    "contentDir": "arabic",
    "weight": 3,
    "ogLocale": "ar_SA",
    "dir": "rtl",
    "dateLocale": "ar"
  }
]
```

| Key | What it does |
| --- | --- |
| `languageName` | The label on the language links |
| `languageCode` | The URL prefix and the file suffix (`fr.json`, `menu.fr.json`) |
| `contentDir` | The folder name inside each content folder |
| `weight` | The order of the language links |
| `ogLocale` | The language of social previews |
| `dir` | `ltr` or `rtl`. This one value sets the direction of the page |
| `dateLocale` | The format of dates, numbers, and amounts |

Visitors switch language with the links in the header, the mobile menu, and the footer. A link goes to the same page in the other language.

Your organization details stay in one place for every language: `[organization]` in `config.toml` (name, registration number, phone, address, hours). Don't type them into translations. See [Organization Info](/givo/customization/organization-info/).

### Language Settings
```toml
# src/config/config.toml
[settings.multilingual]
  enable               = true
  defaultLanguage      = "en"
  disableLanguages     = [""]   # e.g. ["fr"] to switch French off without deleting it
  showDefaultLangInUrl = false  # true: English at /en/ instead of /
```

Restart `npm run dev` after you change these values.

### Translate Or Edit Text
- **Page and section text:** edit the file with the **same name** in the language's folder, for example `src/content/sections/french/hero-section.md`. Keep the keys and structure the same as in English; translate the values only.
- **Interface text:** edit the same key in the language's file, for example `navigation.buttonLabel` ("Donate") in `src/i18n/fr.json`.
- **Menus:** each `src/config/menu.<language>.json` must keep the same structure as `menu.en.json`: the same items, in the same order, with the same `url`. Translate the names. Menu and button URLs are written without the language prefix; the theme adds it.
- **Links inside text:** a Markdown link in a translated file needs its language prefix, such as `[Questions](/fr/faq/)`. Without it the link opens the English page.

### Keep The Numbers The Same In Every Language
Translate words, never figures. These numbers must be identical in every language folder:

- the giving data in `src/content/donate/<language>/-index.md`: `currency`, `amounts`, `default`, `minimum`, `coverFeesPercent`, the amounts of `impactMap`, and the `tiers` amounts. `npm run build` prints a `[donate]` warning when they differ. See [Donation Form](/givo/customization/donation-form/).
- the `goal`, `raised`, `donors`, and `deadline` of each cause in `src/content/causes/<language>/`
- the dates, times, `capacity`, and `price` of each event in `src/content/events/<language>/`
- the spending split on `/impact/` and its copies on the homepage and the donate page. See [Impact & Transparency](/givo/customization/impact-transparency/).

### Page-Title Tagline And Site Description
Every page title ends with a tagline: "Clean water wells - your tagline". Each language has its own, with the default description for pages that don't set one:

```json
// src/i18n/en.json
"seo": {
  "tagline": "Charity & Non-Profit Astro & Tailwind CSS Theme",
  "siteDescription": "An Astro and Tailwind CSS theme for charities and non-profits: ..."
}
```

Both ship with the theme's own sample text. Replace them in every file in `src/i18n/` before you launch. Set `"tagline": ""` to end titles with the organization name instead. A value in `tagline` or `description` under `[site]` in `config.toml` replaces them in every language, which suits a site with one language. See [Site Identity & Logo](/givo/customization/site-identity-logo/).

### Counted Labels (Plurals)
Labels with a number, such as "1 donor" and "412 donors" or "1 day left" and "12 days left", come in forms per language. English and French need two keys, the singular and the plural:

```json
// src/i18n/en.json, under "causes"
"donors": "{count} donors",
"donorOne": "{count} donor",
```

Arabic needs more forms, so `ar.json` adds keys with a suffix beside the plural key:

```json
// src/i18n/ar.json, under "causes"
"donors": "{count} متبرّع",
"donors_two": "متبرّعان",
"donors_few": "{count} متبرّعين",
"donors_many": "{count} متبرّعًا",
"donorOne": "متبرّع واحد",
```

The suffixes are `_zero`, `_two`, `_few`, and `_many`. The browser's plural rules pick the right form for the number, and a missing form falls back to the plural key. Developers build these labels with `countForms` and `countLabel` in `src/lib/plural.ts`, never by joining strings. When you add a language with more plural forms, add its extra keys the same way; `npm run check-i18n` accepts them.

### Numbers, Amounts, And Dates
Givo formats every amount, number, and date for the page language, from `dateLocale` in `language.json`: `$96,080` in English shows as `96 080 $` in French. Arabic pages keep Western digits. You never write a formatted amount in content: write plain numbers (`goal: 75000`), and the theme formats them.

The currency is one value for every language, `currency` in `src/content/donate/<language>/-index.md` (an ISO 4217 code such as `"USD"`, `"EUR"`, or `"GBP"`). Office hours and event times use `timezone` in `[organization]`; an event can set its own `timezone`.

### Check Your Translations
```bash
npm run check-i18n
```

It also runs as part of `npm run astro-check`, and fails when:

- a key in `src/i18n/en.json` is missing from another language file, or the reverse (the extra plural keys are allowed),
- a key in `en.json` is no longer read by any code,
- a menu file differs from `menu.en.json` in structure (item count, `url`),
- a content file in an `english/` folder has no copy in another language folder, or the reverse.

It warns about empty strings and strings still equal to the English ones. Words that are the same in every language on purpose are listed in `scripts/check-i18n.mjs`.

### Remove A Language
**To turn one language off**, add its code to `disableLanguages` in `[settings.multilingual]`, for example `["fr"]`. Its files stay in the project, and you can turn it back on later. Restart `npm run dev`.

**To keep only your default language:**

<Steps>

1. Save a git commit or a copy of the folder, because the next steps delete files.
2. Set `enable = false` in `[settings.multilingual]` of `src/config/config.toml`.
3. Run `npm run dev` (or `npm run astro-check`) once.
4. Run `npm run remove-multilingual`. It deletes the content folders of every language except the default one and rewrites `language.json`.

</Steps>

The script always keeps `menu.en.json` and `en.json`. If your default language is not English, remove the other menu and `src/i18n/` files by hand.

### Add A Language
Example: German, code `de`, folder `german`.

<Steps>

1. Copy every `english/` folder under `src/content/` to a `german/` folder next to it.

2. Add German to `src/config/language.json`, with `languageName`, `languageCode` (`"de"`), `contentDir` (`"german"`), `weight`, `ogLocale` (`"de_DE"`), `dir` (`"ltr"`, or `"rtl"` for a right-to-left language), and `dateLocale` (`"de-DE"`).

3. Copy `src/config/menu.en.json` to `menu.de.json`, and `src/i18n/en.json` to `de.json`.

4. Translate the copied content, menu, and strings. Add the language prefix to Markdown links in the copied files, such as `[Questions](/de/faq/)`. If German needs more plural forms than English for a label, add the `_zero`, `_two`, `_few`, or `_many` keys beside it. Keep every number the same as in English.

5. Run `npm run check-i18n` and fix what it lists.

6. On Netlify, add a `/de/*` block to `netlify.toml`, copied from the `/fr/*` block. If the alphabet needs its own font, add it to `src/config/fonts.json`, using the Arabic font as your model. Restart the dev server.

</Steps>

<Aside type="caution" title="Not with generate-multilingual-content">
  The theme also has `npm run generate-multilingual-content`. Don't use it to add
  a language: it only creates French, and it copies the English files over the
  French ones you already have.
</Aside>

### Do It With AI
```text
Add [LANGUAGE] (code [CODE], folder [FOLDER]) to my Givo site. Follow "Add or remove a language"
in SKILLS.md: copy every english/ content folder, add the language to src/config/language.json,
copy menu.en.json and src/i18n/en.json, and translate the copies. Add the language prefix to
Markdown links in the new files, add plural keys if the language needs them, and keep every number
(donate file, causes, events) identical. Do not run generate-multilingual-content. Then run
npm run check-i18n and fix what it lists.
```

```text
Translate my changes to every other language: for every file I changed in src/content/**/english/
today, update the file with the same name in each other language folder (same keys, translated
values, numbers unchanged), and add any new key from src/i18n/en.json to the other files in
src/i18n/. Then run npm run check-i18n.
```