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.
Le Compiler de Lingo.dev fournit le hook useLingoContext() pour lire et modifier la langue active à l’exécution. Utilisez-le pour créer des sélecteurs de langue, des composants adaptés à la langue ou toute interface qui s’adapte aux préférences linguistiques de l’utilisateur.
Hook useLingoContext()#
Le hook renvoie un objet contenant la langue active et une fonction pour la modifier :
import { useLingoContext } from "@lingo.dev/compiler/react";
const { locale, setLocale } = useLingoContext();| Propriété | Type | Description |
|---|---|---|
locale | string | Le code de la langue active (par ex. "en", "es"). |
setLocale | (locale: string) => void | Définit la nouvelle langue. Déclenche par défaut la persistance et le rechargement de la page. |
Exemple de sélecteur de langue#
Un composant de sélection de la langue sous forme de menu déroulant :
"use client"; // Required for Next.js App Router
import { useLingoContext } from "@lingo.dev/compiler/react";
const localeLabels: Record<string, string> = {
en: "English",
es: "Espanol",
de: "Deutsch",
fr: "Francais",
ja: "日本語",
};
export function LanguageSwitcher() {
const { locale, setLocale } = useLingoContext();
return (
<select value={locale} onChange={(e) => setLocale(e.target.value)}>
{Object.entries(localeLabels).map(([code, label]) => (
<option key={code} value={code}>
{label}
</option>
))}
</select>
);
}Dans Next.js, le sélecteur de langue doit être un composant client ("use client"), car il utilise un hook React.
Que se passe-t-il lorsque setLocale est appelé#
La langue est conservée
Par défaut, la nouvelle langue est enregistrée dans un cookie nommé locale avec une durée de vie maximale d’un an. Cela garantit que cette préférence est conservée après le rechargement de la page et le redémarrage du navigateur.
La page se recharge
La page se recharge afin de restituer tous les composants dans la nouvelle langue. Les composants serveur récupèrent les traductions de la nouvelle langue côté serveur, et les composants client reçoivent le dictionnaire mis à jour.
Les requêtes suivantes utilisent la nouvelle langue
Au chargement de page suivant, le Compiler lit la langue conservée et fournit les traductions correspondantes.
Options de persistance#
Le mécanisme de persistance par défaut repose sur les cookies et se configure via localePersistence :
{
localePersistence: {
type: "cookie",
config: {
name: "locale", // Cookie name
maxAge: 31536000, // 1 year in seconds
},
},
}| Option | Par défaut | Description |
|---|---|---|
type | "cookie" | Mécanisme de persistance. |
config.name | "locale" | Nom du cookie. |
config.maxAge | 31536000 | Durée de vie du cookie en secondes. |
Persistance personnalisée#
Pour un routage de langue basé sur l’URL, l’utilisation de localStorage ou une détection personnalisée à partir des en-têtes, créez des résolveurs de langue personnalisés. L’export persistLocale dans votre résolveur client contrôle ce qui se passe lorsque setLocale est appelé :
// .lingo/locale-resolver.client.ts
export function resolveLocale(): string {
return localStorage.getItem("locale") || "en";
}
export function persistLocale(locale: string): void {
localStorage.setItem("locale", locale);
window.location.reload();
}Consultez Custom Locale Resolvers pour voir des exemples complets de configurations basées sur l’URL, les cookies et les en-têtes.
Lire la langue sans la changer#
Si vous avez besoin de la langue active pour l’affichage ou le rendu conditionnel sans proposer de sélecteur, utilisez le même hook :
"use client";
import { useLingoContext } from "@lingo.dev/compiler/react";
export function LocaleBadge() {
const { locale } = useLingoContext();
return <span>{locale.toUpperCase()}</span>;
}