# Charger les traductions

> Déterminer la langue de l'utilisateur, obtenir l'adresse du fichier de traduction par l'API publique, puis le charger dans votre application.

Votre application charge ses textes au démarrage, dans la langue de l'utilisateur. Le chemin est toujours le même : déterminer la langue, demander l'adresse du fichier à l'API publique, télécharger le fichier.

## Avant de commencer

- L'appel qui renvoie l'adresse d'un fichier exige le droit `languages.read`. Faites-le depuis votre serveur avec une [clé API](/v1.0/cles-api) de l'application qui porte ce droit, plutôt qu'avec le jeton de chaque utilisateur.
- Votre application dispose du [jeton enrichi](/v1.0/glossaire#jeton-enrichi) de l'utilisateur, ou peut le décoder côté serveur : voir [Authentification](/v1.0/authentification).
- Les traductions de l'application existent dans les langues visées.

## Déterminer la langue

Retenez, dans cet ordre :

1. la revendication `wlng` du jeton enrichi, si elle est présente et fait partie des langues de l'application ;
2. sinon, la langue dont `isDefault` vaut `true` dans `GET /api/apps/{appWid}/runtime-config`.

Le détail de cette résolution est expliqué dans [Résolution de la langue](/v1.0/langues-et-traductions/resolution-de-la-langue).

## Obtenir l'adresse du fichier

```bash
curl "https://api.wakastart.app/api/languages/code/fr/file?appWid=EXAPP1&fileType=FRONT" \
  -H "x-api-key: sk_test_exemple"
```

| Paramètre | Obligatoire | Valeurs |
|---|---|---|
| `code` (chemin) | oui | code de la langue, par exemple `fr` |
| `appWid` | oui | WID de votre application |
| `fileType` | non | `FRONT` (par défaut), `BACK` ou `EXTRA` |

Réponse attendue (`200 OK`) :

```json
{
  "s3Url": "https://stockage.exemple.fr/langs/EXAPP1/fr/i18-EXAPP1-front-fr.json",
  "s3Key": "langs/EXAPP1/fr/i18-EXAPP1-front-fr.json"
}
```

L'adresse ne dépend que de l'application, de la langue et du type : vous pouvez la mettre en cache côté serveur.

## Charger le fichier dans votre application

L'exemple suivant expose, côté serveur, une route qui renvoie les traductions de la bonne langue, puis les charge avec i18next côté navigateur.

```ts
// server/translations.ts — route serveur (Node 18+, Express)
import express from "express";

const API = "https://api.wakastart.app/api";
const APP_WID = "EXAPP1";
const API_KEY = process.env.WAKASTART_API_KEY!; // clé sk_… portant languages.read

const urlCache = new Map<string, string>();

async function translationFileUrl(lang: string, fileType = "FRONT"): Promise<string> {
  const cacheKey = `${lang}:${fileType}`;
  const cached = urlCache.get(cacheKey);
  if (cached) return cached;

  const res = await fetch(
    `${API}/languages/code/${encodeURIComponent(lang)}/file?appWid=${APP_WID}&fileType=${fileType}`,
    { headers: { "x-api-key": API_KEY } },
  );
  if (!res.ok) throw new Error(`Adresse du fichier ${lang} : ${res.status}`);
  const { s3Url } = (await res.json()) as { s3Url: string };
  urlCache.set(cacheKey, s3Url);
  return s3Url;
}

export const router = express.Router();

router.get("/translations/:lang", async (req, res) => {
  try {
    const url = await translationFileUrl(req.params.lang);
    const file = await fetch(url);
    if (!file.ok) return res.status(404).json({ error: "translations_not_found" });
    res.set("Cache-Control", "public, max-age=3600");
    res.json(await file.json());
  } catch {
    res.status(502).json({ error: "translations_unavailable" });
  }
});
```

```ts
// client/i18n.ts — chargement dans le navigateur
import i18next from "i18next";

export async function initI18n(lang: string, defaultLang: string) {
  const load = (l: string) => fetch(`/translations/${l}`).then((r) => (r.ok ? r.json() : {}));
  const [current, fallback] = await Promise.all([load(lang), load(defaultLang)]);

  await i18next.init({
    lng: lang,
    fallbackLng: defaultLang,
    // Une clé sans valeur est publiée avec une chaîne vide : on la traite comme manquante.
    returnEmptyString: false,
    resources: {
      [lang]: { translation: current },
      [defaultLang]: { translation: fallback },
    },
  });
}
```

Appelez `initI18n("fr", "fr")` avec la langue déterminée à l'étape précédente et la langue par défaut de l'application. `i18next.t("common.buttons.save")` renvoie alors « Enregistrer ».

:::tip
Votre serveur peut charger de la même façon son fichier `BACK` au démarrage, pour traduire ses messages et ses e-mails.
:::

## Vérifier le résultat

1. Appelez votre route `/translations/fr` : elle renvoie un objet JSON imbriqué.
2. Connectez-vous avec un utilisateur dont la langue préférée est l'anglais : l'interface s'affiche en anglais.

## Voir aussi

- [Fichiers de traduction](/v1.0/langues-et-traductions/fichiers-de-traduction)
- [Résoudre les problèmes de langues](/v1.0/langues-et-traductions/depannage)
- [Traduire l'interface avec waka-ui](/v1.0/interface-waka-ui/traduire-l-interface)
- [Référence API : contenus de l'application](/v1.0/reference-api/contenus-application)
