# Langues

Prise en charge multilingue avec clés de traduction, détection de la langue du navigateur et routage automatique par URL (`/en/...`, `/fr/...`). Référencez les traductions dans les pages avec le préfixe `$t:`.

## Définir les langues

Définissez une langue par défaut et listez les langues prises en charge avec code, locale, libellé et direction du texte.

| Propriété          | Description                                                                                                           |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `default`          | Code ISO 639-1 de la langue par défaut (par ex. `"en"`). Utilisé quand aucune langue n'est détectée.                  |
| `supported`        | Tableau d'objets d'entrée de langue. Chacun définit une langue prise en charge.                                       |
| `fallback`         | Code de langue de secours (2 lettres). Utilisé quand une clé de traduction est manquante dans la langue active.       |
| `detectBrowser`    | Booléen. Lorsque `true`, détecte automatiquement la langue du navigateur de l'utilisateur lors de la première visite. |
| `persistSelection` | Booléen. Lorsque `true`, mémorise le choix de langue de l'utilisateur entre les 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
```

## Propriétés d'entrée de langue

Chaque entrée du tableau `supported` décrit une langue avec ces propriétés.

| Propriété   | Description                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `code`      | Code de langue ISO 639-1 (par ex. `"en"`, `"fr"`, `"ar"`). Utilisé dans le routage par URL (`/en/`, `/fr/`).                       |
| `locale`    | Identifiant de locale complet (par ex. `"en-US"`, `"fr-FR"`, `"ar-SA"`). Utilisé pour le formatage des nombres et dates.           |
| `label`     | Nom lisible de la langue affiché dans les sélecteurs de langue (par ex. `"English"`, `"Français"`).                                |
| `direction` | Direction du texte : `"ltr"` (gauche à droite) pour la plupart des langues, `"rtl"` (droite à gauche) pour l'arabe, l'hébreu, etc. |
| `flag`      | Emoji drapeau ou chemin d'icône affiché dans les sélecteurs de langue.                                                             |

:::callout
**Prise en charge RTL.** Définissez `direction: rtl` pour les langues droite-à-gauche comme l'arabe ou l'hébreu. Sovrium inverse automatiquement la mise en page, aligne le texte à droite et applique l'attribut `dir="rtl"` à la racine HTML.
:::

## Clés de traduction

Définissez des paires clé-valeur pour chaque langue. Les clés utilisent la notation pointée pour l'organisation.

```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'
```

## Utiliser les traductions

Référencez les traductions dans tout contenu ou valeur de propriété avec le préfixe `$t:`.

```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
**Syntaxe de traduction `$t:`.** Utilisez `$t:key.path` dans tout contenu ou valeur de propriété de page pour référencer une traduction. Exemple : `$t:hero.title` se résout en `"Welcome"` en anglais et `"Bienvenue"` en français.
:::

![Version anglaise de l'application](/docs/screenshots/app-translation-en.png)

![Version française de l'application](/docs/screenshots/app-translation-fr.png)

## Ajouter une nouvelle langue

Suivez ces étapes pour ajouter une nouvelle langue à votre application.

1. **Ajouter l'entrée de langue** — Ajoutez un nouvel élément au tableau `supported` avec `code`, `locale`, `label` et `direction`.
2. **Ajouter les traductions** — Créez une nouvelle section `translations` pour le code de langue avec toutes les clés nécessaires.
3. **Tester la langue** — Visitez `/[lang-code]/` dans votre navigateur pour vérifier que la nouvelle langue s'affiche correctement.