# Fichiers de traduction

> Clés de traduction, types de fichiers FRONT, BACK et EXTRA, format JSON publié, nommage, publication automatique et mise en cache.

Les textes de votre application ne vivent pas dans son code : Wakastart les conserve par clé et par langue, puis les publie dans des fichiers JSON que votre application télécharge.

## Définition

- Une **clé de traduction** désigne un texte de l'application, en notation pointée : `common.buttons.save`, `errors.network`. Elle fait 255 caractères au plus.
- Une **valeur** est le texte d'une clé dans une langue, 5 000 caractères au plus. Le HTML actif y est refusé.
- Chaque clé appartient à un **type de fichier** :

| Type | Usage |
|---|---|
| `FRONT` | textes visibles dans l'interface |
| `BACK` | messages produits par votre serveur, e-mails de votre application |
| `EXTRA` | textes complémentaires : aide, parcours d'accueil, infobulles |

Une même clé peut exister dans deux types différents avec des valeurs différentes.

## Un fichier par langue et par type

Wakastart publie un fichier par combinaison (application, langue, type), nommé `i18-<WID>-<type>-<langue>.json` et rangé sous `langs/<WID>/<langue>/` :

```text
langs/EXAPP1/fr/i18-EXAPP1-front-fr.json
langs/EXAPP1/fr/i18-EXAPP1-back-fr.json
langs/EXAPP1/en/i18-EXAPP1-front-en.json
```

Le contenu est un objet JSON **imbriqué** selon les points de la clé :

```json
{
  "common": {
    "buttons": {
      "save": "Enregistrer",
      "cancel": "Annuler"
    }
  },
  "errors": {
    "network": "Connexion impossible. Réessayez dans un instant."
  }
}
```

Ce format est directement lisible par i18next, next-intl ou vue-i18n.

## Clés sans valeur

Chaque fichier contient **toutes** les clés du type. Une clé qui n'a pas encore de valeur dans une langue y figure avec une chaîne vide (`""`). Prévoyez ce cas dans votre application : traitez une chaîne vide comme une traduction manquante et affichez la langue par défaut à la place.

## Publication automatique

Le fichier d'une langue est régénéré automatiquement à chaque modification de ses traductions, y compris la suppression d'une clé. Les fichiers sont servis avec un cache d'une heure (`Cache-Control: max-age=3600`) : un texte modifié peut mettre jusqu'à une heure à apparaître chez un utilisateur qui a déjà chargé le fichier.

## Pour aller plus loin

- [Charger les traductions](/v1.0/langues-et-traductions/charger-les-traductions)
- [Référence des langues et traductions](/v1.0/langues-et-traductions/reference)
