# Traduire l'interface

> Charger les traductions Wakastart de votre application dans waka-ui, afficher l'interface dans la langue de l'utilisateur et adapter les textes des composants.

waka-ui traduit avec i18next. Deux catalogues cohabitent : celui de votre application, que vous chargez depuis Wakastart, et celui des composants de waka-ui (pagination, filtres, boutons des tableaux…), livré dans le paquet en français et en anglais. Ce guide branche le premier, fait suivre la langue de l'utilisateur et montre comment adapter le second.

## Avant de commencer

- waka-ui est installé : voir [Installer waka-ui](/v1.0/interface-waka-ui/installer-waka-ui).
- Les langues et les textes de votre application existent dans Wakastart : voir [Langues et traductions](/v1.0/langues-et-traductions).
- Votre serveur dispose d'une [clé API](/v1.0/cles-api) de l'application qui porte le droit `languages.read`, dans une variable d'environnement.

## Comment les textes sont résolus

Pour chaque clé, waka-ui cherche d'abord dans vos traductions, puis dans son propre catalogue, et affiche en dernier recours le texte anglais prévu par le composant. Vos traductions gagnent toujours : une clé que vous définissez remplace celle de waka-ui.

Sans aucune traduction de votre part, les composants s'affichent déjà en français ou en anglais, selon la langue active.

::::steps

### Charger les traductions côté serveur

Créez `lib/translations.ts`. Il demande l'adresse du fichier `FRONT` de chaque langue à l'API publique, puis télécharge le fichier, comme décrit dans [Charger les traductions](/v1.0/langues-et-traductions/charger-les-traductions). N'importez ce module que depuis du code serveur : il lit la clé API.

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

export type Messages = { [key: string]: string | Messages };

// Une clé sans valeur est publiée avec une chaîne vide : on la retire pour
// que le texte de la langue par défaut s'affiche plutôt qu'un libellé vide.
function dropEmptyValues(messages: Messages): Messages {
  const result: Messages = {};
  for (const [key, value] of Object.entries(messages)) {
    if (typeof value !== "string") result[key] = dropEmptyValues(value);
    else if (value !== "") result[key] = value;
  }
  return result;
}

export async function loadTranslations(lang: string): Promise<Messages> {
  const res = await fetch(
    `${API}/languages/code/${encodeURIComponent(lang)}/file?appWid=${APP_WID}&fileType=FRONT`,
    { headers: { "x-api-key": API_KEY }, next: { revalidate: 3600 } },
  );
  if (!res.ok) return {};
  const { s3Url } = (await res.json()) as { s3Url: string };

  const file = await fetch(s3Url, { next: { revalidate: 3600 } });
  return file.ok ? dropEmptyValues((await file.json()) as Messages) : {};
}
```

`revalidate: 3600` garde les fichiers en cache une heure : une traduction modifiée dans la console apparaît au plus tard une heure après.

### Transmettre les traductions au fournisseur

Dans `app/layout.tsx`, chargez les langues de l'application et passez-les au composant `Providers` :

```tsx
import type { ReactNode } from "react";
import "./globals.css";
import { Providers } from "./providers";
import { loadTranslations } from "@/lib/translations";

export default async function RootLayout({ children }: { children: ReactNode }) {
  const [fr, en] = await Promise.all([loadTranslations("fr"), loadTranslations("en")]);

  return (
    <html lang="fr">
      <body>
        <Providers resources={{ fr: { translation: fr }, en: { translation: en } }}>{children}</Providers>
      </body>
    </html>
  );
}
```

Dans `app/providers.tsx`, ajoutez les traductions à la configuration :

```tsx
"use client";

import { useMemo, type ReactNode } from "react";
import { Toaster, WakaProvider, type WakaProviderConfig } from "@wakastellar/ui";

type Resources = NonNullable<WakaProviderConfig["language"]["resources"]>;

export function Providers({ children, resources }: { children: ReactNode; resources: Resources }) {
  // useMemo : la configuration ne change que si les traductions changent.
  const config = useMemo<WakaProviderConfig>(
    () => ({
      language: {
        defaultLanguage: "fr",
        supportedLanguages: ["fr", "en"],
        languages: [
          { code: "fr", label: "Français" },
          { code: "en", label: "English" },
        ],
        resources,
      },
      theme: { defaultTheme: "default", themes: [{ id: "default", label: "Par défaut" }], enableSystem: true },
    }),
    [resources],
  );

  return (
    <WakaProvider config={config}>
      {children}
      <Toaster />
    </WakaProvider>
  );
}
```

Utilisez ensuite vos clés dans n'importe quel composant client :

```tsx
"use client";

import { Button, useTranslation } from "@wakastellar/ui";

export function SaveButton() {
  const { t } = useTranslation();
  return <Button>{t("common.buttons.save")}</Button>;
}
```

### Suivre la langue de l'utilisateur

Wakastart détermine la langue de chaque utilisateur et la porte dans son jeton enrichi (voir [Résolution de la langue](/v1.0/langues-et-traductions/resolution-de-la-langue)). Une fois l'utilisateur connecté, appliquez-la :

```tsx
"use client";

import { useEffect } from "react";
import { useWaka } from "@wakastellar/ui";

export function UserLanguage({ lang }: { lang: string | null }) {
  const { currentLanguage, changeLanguage } = useWaka();

  useEffect(() => {
    if (lang && lang !== currentLanguage) void changeLanguage(lang);
  }, [lang, currentLanguage, changeLanguage]);

  return null;
}
```

La langue doit figurer dans `supportedLanguages` et avoir ses traductions dans `resources`. Le choix est mémorisé dans le navigateur.

### Proposer un sélecteur de langue

```tsx
"use client";

import { LanguageSelector, useWaka } from "@wakastellar/ui";

export function LanguageMenu() {
  const { currentLanguage, changeLanguage, languages } = useWaka();

  return (
    <LanguageSelector
      languages={languages}
      value={currentLanguage}
      onChange={(code) => void changeLanguage(code)}
      variant="compact"
    />
  );
}
```

`LanguageSelector` accepte les variantes `default`, `compact` et `minimal`. La liste vient de `language.languages` dans la configuration.

::::

## Adapter un texte de waka-ui

Pour changer un libellé d'un composant, définissez la même clé dans les traductions `FRONT` de votre application. Par exemple, la clé `datatable.pagination.rowsPerPage` vaut « Lignes par page » dans le catalogue de waka-ui ; si vos traductions françaises lui donnent la valeur « Éléments par page », c'est votre texte qui s'affiche.

Les valeurs livrées par waka-ui sont exportées par le paquet sous les noms `frDefaultTranslation` et `enDefaultTranslation` : consultez-les pour connaître les clés existantes.

## Vérifier le résultat

1. Ouvrez une page qui utilise `t("…")` : le texte vient de vos traductions Wakastart.
2. Choisissez **English** dans le sélecteur : vos textes et ceux des tableaux passent en anglais.
3. Connectez-vous avec un utilisateur dont la langue préférée est l'anglais, dans une fenêtre de navigation privée : l'interface s'ouvre en anglais.

## Voir aussi

- [Fichiers de traduction](/v1.0/langues-et-traductions/fichiers-de-traduction)
- [Référence de waka-ui](/v1.0/interface-waka-ui/reference#configuration-de-wakaprovider)
- [Résoudre les problèmes de waka-ui](/v1.0/interface-waka-ui/depannage)
