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.
- Accès requis
- Clé API de l'application portant le droit languages.read, côté serveur
- Durée
- 25 min
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.
- Les langues et les textes de votre application existent dans Wakastart : voir Langues et traductions.
- Votre serveur dispose d'une clé 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.
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. N'importez ce module que depuis du code serveur : il lit la clé API.
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 :
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 :
"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 :
"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). Une fois l'utilisateur connecté, appliquez-la :
"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
"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
- Ouvrez une page qui utilise
t("…"): le texte vient de vos traductions Wakastart. - Choisissez English dans le sélecteur : vos textes et ceux des tableaux passent en anglais.
- 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.