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.
- Accès requis
- Clé API ou jeton portant le droit languages.read
- Durée
- 20 min
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 de l'application qui porte ce droit, plutôt qu'avec le jeton de chaque utilisateur. - Votre application dispose du jeton enrichi de l'utilisateur, ou peut le décoder côté serveur : voir Authentification.
- Les traductions de l'application existent dans les langues visées.
Déterminer la langue
Retenez, dans cet ordre :
- la revendication
wlngdu jeton enrichi, si elle est présente et fait partie des langues de l'application ; - sinon, la langue dont
isDefaultvauttruedansGET /api/apps/{appWid}/runtime-config.
Le détail de cette résolution est expliqué dans Résolution de la langue.
Obtenir l'adresse du fichier
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) :
{
"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.
// 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" });
}
});// 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 ».
Conseil
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
- Appelez votre route
/translations/fr: elle renvoie un objet JSON imbriqué. - Connectez-vous avec un utilisateur dont la langue préférée est l'anglais : l'interface s'affiche en anglais.