# Languages

Multi-language support with translation keys, browser language detection, and automatic URL-based language routing (`/en/...`, `/fr/...`). Reference translations in pages using the `$t:` prefix.

## Defining Languages

Set a default language and list supported languages with code, locale, label, and text direction.

| Property           | Description                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| `default`          | ISO 639-1 code for the default language (e.g., `"en"`). Used when no language is detected.         |
| `supported`        | Array of language entry objects. Each defines a supported language.                                |
| `fallback`         | Fallback language code (2 letters). Used when a translation key is missing in the active language. |
| `detectBrowser`    | Boolean. When `true`, auto-detects the user's browser language on first visit.                     |
| `persistSelection` | Boolean. When `true`, remembers the user's language choice across sessions.                        |

```yaml
languages:
  default: en
  supported:
    - code: en
      locale: en-US
      label: English
      direction: ltr
    - code: fr
      locale: fr-FR
      label: 'Français'
      direction: ltr
    - code: ar
      locale: ar-SA
      label: 'العربية'
      direction: rtl
```

## Language Entry Properties

Each entry in the `supported` array describes a language with these properties.

| Property    | Description                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| `code`      | ISO 639-1 language code (e.g., `"en"`, `"fr"`, `"ar"`). Used in URL routing (`/en/`, `/fr/`).                |
| `locale`    | Full locale identifier (e.g., `"en-US"`, `"fr-FR"`, `"ar-SA"`). Used for number/date formatting.             |
| `label`     | Human-readable language name shown in language switchers (e.g., `"English"`, `"Français"`).                  |
| `direction` | Text direction: `"ltr"` (left-to-right) for most languages, `"rtl"` (right-to-left) for Arabic, Hebrew, etc. |
| `flag`      | Flag emoji or icon path displayed in language switchers.                                                     |

:::callout
**RTL Support.** Set `direction: rtl` for right-to-left languages like Arabic or Hebrew. Sovrium automatically mirrors the page layout, aligns text to the right, and applies the `dir="rtl"` attribute to the HTML root.
:::

## Translation Keys

Define key-value pairs for each language. Keys use dot notation for organization.

```yaml
languages:
  translations:
    en:
      hero.title: 'Welcome to My App'
      hero.description: 'Build faster with Sovrium'
      nav.home: 'Home'
      nav.about: 'About'
    fr:
      hero.title: 'Bienvenue sur Mon App'
      hero.description: 'Construisez plus vite avec Sovrium'
      nav.home: 'Accueil'
      nav.about: 'À propos'
```

## Using Translations

Reference translations in any content or prop value with the `$t:` prefix.

```yaml
# Reference translations with $t: prefix
pages:
  - name: home
    path: /
    sections:
      - type: section
        children:
          - type: h1
            content: '$t:hero.title'
          - type: paragraph
            content: '$t:hero.description'
```

:::callout
**`$t:` Translation Syntax.** Use `$t:key.path` in any page content or prop value to reference a translation. Example: `$t:hero.title` resolves to `"Welcome"` in English and `"Bienvenue"` in French.
:::

![English version of the app](/docs/screenshots/app-translation-en.png)

![French version of the app](/docs/screenshots/app-translation-fr.png)

## Adding a New Language

Follow these steps to add a new language to your application.

1. **Add language entry** — Add a new item to the `supported` array with `code`, `locale`, `label`, and `direction`.
2. **Add translations** — Create a new `translations` section for the language code with all required keys.
3. **Test the language** — Visit `/[lang-code]/` in your browser to verify the new language renders correctly.