Alpha
Le Compiler de Lingo.dev est en alpha. Il est instable, déconseillé en production, et les API peuvent changer d’une version à l’autre.
Les résolveurs de langue personnalisés vous permettent de redéfinir la façon dont le Compiler de Lingo.dev détecte et conserve la langue de l’utilisateur. Par défaut, le Compiler utilise une persistance par cookie configurée via l’option localePersistence. Si vous avez besoin de plus de contrôle — routage par URL, détection par en-tête, localStorage ou logique personnalisée — créez des fichiers de résolution dans le répertoire .lingo/.
Fichiers de résolution#
Le Compiler recherche deux fichiers facultatifs :
| Fichier | Environnement | Exports |
|---|---|---|
.lingo/locale-resolver.server.ts | Côté serveur (SSR, RSC) | resolveLocale(request: Request): string |
.lingo/locale-resolver.client.ts | Côté client (navigateur) | resolveLocale(): string et persistLocale(locale: string): void |
Si un fichier de résolution existe, le Compiler l’utilise à la place du comportement par défaut basé sur les cookies. Si un seul fichier est présent, l’autre environnement utilise le comportement par défaut.
Résolveur côté serveur#
Le résolveur serveur reçoit l’objet Request entrant et renvoie une chaîne contenant le code de langue :
// .lingo/locale-resolver.server.ts
export function resolveLocale(request: Request): string {
const url = new URL(request.url);
// Check URL path prefix: /es/about -> "es"
const pathLocale = url.pathname.split("/")[1];
const supportedLocales = ["en", "es", "de", "fr", "ja"];
if (supportedLocales.includes(pathLocale)) {
return pathLocale;
}
// Fall back to Accept-Language header
const acceptLanguage = request.headers.get("Accept-Language");
if (acceptLanguage) {
const preferred = acceptLanguage.split(",")[0].split("-")[0];
if (supportedLocales.includes(preferred)) {
return preferred;
}
}
return "en";
}Résolveur côté client#
Le résolveur client expose deux fonctions : l’une pour lire la langue actuelle, l’autre pour conserver un changement de langue :
// .lingo/locale-resolver.client.ts
export function resolveLocale(): string {
// Check URL path prefix
const pathLocale = window.location.pathname.split("/")[1];
const supportedLocales = ["en", "es", "de", "fr", "ja"];
if (supportedLocales.includes(pathLocale)) {
return pathLocale;
}
// Fall back to localStorage
const stored = localStorage.getItem("locale");
if (stored && supportedLocales.includes(stored)) {
return stored;
}
return "en";
}
export function persistLocale(locale: string): void {
localStorage.setItem("locale", locale);
// Navigate to the locale-prefixed URL
const path = window.location.pathname.replace(/^\/[a-z]{2}/, "");
window.location.href = `/${locale}${path}`;
}Modèles de résolveurs courants#
Router par préfixe dans le chemin de l’URL (/es/about, /de/pricing) :
// .lingo/locale-resolver.server.ts
export function resolveLocale(request: Request): string {
const url = new URL(request.url);
const locale = url.pathname.split("/")[1];
const supported = ["en", "es", "de", "fr"];
return supported.includes(locale) ? locale : "en";
}// .lingo/locale-resolver.client.ts
export function resolveLocale(): string {
const locale = window.location.pathname.split("/")[1];
const supported = ["en", "es", "de", "fr"];
return supported.includes(locale) ? locale : "en";
}
export function persistLocale(locale: string): void {
const path = window.location.pathname.replace(/^\/[a-z]{2}/, "");
window.location.href = `/${locale}${path}`;
}La fonction resolveLocale doit renvoyer un code de langue correspondant à l’une des valeurs configurées dans targetLocales ou sourceLocale. Si elle renvoie un code de langue non pris en charge, le Compiler reviendra à la langue source.
