# 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

Plumbo ships in **English** (the default, at `/`), **French** (at `/fr/`), and **Arabic** (at `/ar/`), with full right-to-left support on Arabic pages. Every page, menu, label, price, 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](../../features/rtl-arabic/).

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

In the Tina edition, these files are the language folders, **Menus and footer columns**, and **Interface labels** at `/admin/`. In the Sanity edition, content, menus, and interface labels are documents in the Studio, one set per language. The language list and the language settings stay in `language.json` and `config.toml`.

### 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/sections/french/` and `src/content/services/arabic/` |
| Interface text | `src/i18n/<language>.json`, such as `fr.json`: buttons, labels, form messages, units, the booking steps, the 404 link labels |
| Menus | `src/config/menu.<language>.json`, such as `menu.ar.json` |

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

| 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 |
| `dir` | `ltr` or `rtl`. This one value sets the direction of the page |
| `ogLocale` | The language of social previews |
| `dateLocale` | The format of dates and numbers |
| `weight` | The order of the language links |

Visitors switch language with the links in the footer and at the bottom of the phone menu. A link goes to the same page in the other language.

Your business details stay in one place for every language: `[business]` in `config.toml` (name, phone, address, hours). Don't type them into translations.

### 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` ("Get a price") 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` and `source`. Translate the labels.
- **Links inside text:** a Markdown link in a translated file carries its language, such as `[Guarantee](/fr/guarantee/)`. Menu and button URLs don't need it.
- **Prices:** keep every number in each language's `src/content/pricing/<language>/-index.md` identical. `npm run build` prints a `[pricing]` warning listing any key that differs.

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

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

- a key in the default language's `src/i18n/` file is missing from another language file, or the reverse,
- a key in that file is no longer read by any code,
- a menu file differs from the default language's menu in structure (item count, `url`, `source`),
- a content file in the default language's folder has no copy in another language folder, or the reverse.

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

### Numbers, Prices, And Dates
Plumbo formats every price, number, date, and opening time for the page language with the browser's `Intl` tools: `$1,240` in English becomes `1 240 $US` in French. Arabic pages use Western digits. You never write a formatted price in content: prices come from the numbers in the pricing file.

```toml
[settings.estimator]
  currency        = "USD"     # ISO 4217 code, one currency for every language
  currencyDisplay = "symbol"  # symbol ($ / $US) | narrowSymbol ($ in every language) | code (USD)
```

Set `currency` to your own (`"EUR"`, `"GBP"`, `"CAD"`), and use `narrowSymbol` to show `$` in French too. Opening hours and booking dates use `timezone` in `[business]`.

### 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** in the Astro and Tina editions:

<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` once.
4. Run `npm run remove-multilingual`. It deletes the content folders, the menu file, and the `src/i18n/` file of every language except the default, French and Arabic included, and rewrites `language.json`.

</Steps>

**In the Sanity edition**, run `npm run remove-multilingual`. It keeps your default language in `language.json` and in the demo content file. The other languages' documents stay in your project unless you add `-- --delete-online`, which deletes them and can't be undone.

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

<Steps>

1. Run the language script. In the Astro and Tina editions:

   ```bash
   npm run generate-multilingual-content -- --lang de --name Deutsch --dir-name german --locale de-DE --og de_DE
   ```

   In the Sanity edition, the last setting is called `--og-locale`:

   ```bash
   npm run generate-multilingual-content -- --lang de --name Deutsch --dir-name german --locale de-DE --og-locale de_DE
   ```

   For a right-to-left language, add `--dir rtl`. The script adds the language to `language.json`. In the Astro and Tina editions, it copies your default language's content folders, menu file, and `src/i18n/` file. It keeps files that already exist unless you add `--force`. In the Sanity edition, it creates a copy of every default-language document in your project, and your other documents aren't touched.

2. Translate the copies. In the copied files, add the language to Markdown links, such as `[Guarantee](/de/guarantee/)`.

3. In the Tina edition, run `npm run tina:generate` so the editor offers the new language.

4. On Netlify, add a `/de/*` block to `netlify.toml`, copied from the `/fr/*` block. The script doesn't write this rule in any edition.

5. If the language's alphabet needs its own font, add one to `src/config/fonts.json`, using the Arabic font as your model.

6. Restart the dev server. In the Astro and Tina editions, run `npm run check-i18n` and fix what it lists.

</Steps>

### Do It With AI
```text
Add [LANGUAGE] (code [CODE], folder [FOLDER]) to my Plumbo site. Follow "Add or remove a language"
in SKILLS.md: run npm run generate-multilingual-content with the flags it lists, then translate the
new content folders, src/config/menu.[CODE].json, and src/i18n/[CODE].json. Add the language prefix
to Markdown links in the new files. Keep every number in the pricing file identical. 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.
```