Alfa
El Compiler de Lingo.dev está en fase alfa. Es inestable, no se recomienda para entornos de producción y las API pueden cambiar entre versiones.
El Compiler de Lingo.dev proporciona el hook useLingoContext() para consultar y cambiar el idioma activo en tiempo de ejecución. Úsalo para crear selectores de idioma, componentes adaptados al idioma o cualquier interfaz que responda a la preferencia de idioma del usuario.
Hook useLingoContext()#
El hook devuelve un objeto con el idioma actual y una función para cambiarlo:
import { useLingoContext } from "@lingo.dev/compiler/react";
const { locale, setLocale } = useLingoContext();| Propiedad | Tipo | Descripción |
|---|---|---|
locale | string | El código del idioma activo (p. ej., "en", "es"). |
setLocale | (locale: string) => void | Establece el nuevo idioma. Por defecto, activa la persistencia y recarga la página. |
Ejemplo de selector de idioma#
Un componente de selector de idioma con menú desplegable:
"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>
);
}En Next.js, el selector de idioma debe ser un Client Component ("use client") porque utiliza un hook de React.
Qué ocurre cuando se llama a setLocale#
El idioma se guarda
Por defecto, el nuevo idioma se guarda en una cookie llamada locale con una duración máxima de 1 año. Esto garantiza que la preferencia se conserve tras recargar la página y reiniciar el navegador.
La página se recarga
La página se recarga para volver a renderizar todos los componentes con el nuevo idioma. Los Server Components obtienen las traducciones del nuevo idioma en el servidor y los Client Components reciben el diccionario actualizado.
Las solicitudes posteriores usan el nuevo idioma
En la siguiente carga de página, el Compiler lee el idioma guardado y sirve las traducciones correspondientes.
Opciones de persistencia#
El mecanismo de persistencia predeterminado se basa en cookies y se configura mediante localePersistence:
{
localePersistence: {
type: "cookie",
config: {
name: "locale", // Cookie name
maxAge: 31536000, // 1 year in seconds
},
},
}| Opción | Predeterminado | Descripción |
|---|---|---|
type | "cookie" | Mecanismo de persistencia. |
config.name | "locale" | Nombre de la cookie. |
config.maxAge | 31536000 | Duración de la cookie en segundos. |
Persistencia personalizada#
Para el enrutado de idioma basado en URL, localStorage o la detección personalizada mediante cabeceras, crea resolvedores de idioma personalizados. La exportación persistLocale en tu resolvedor de cliente controla lo que ocurre cuando se llama a setLocale:
// .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();
}Consulta Custom Locale Resolvers para ver ejemplos completos de patrones basados en URL, cookies y cabeceras.
Leer el idioma sin cambiarlo#
Si necesitas el idioma actual para mostrarlo o para renderizado condicional sin ofrecer un selector, usa el mismo hook:
"use client";
import { useLingoContext } from "@lingo.dev/compiler/react";
export function LocaleBadge() {
const { locale } = useLingoContext();
return <span>{locale.toUpperCase()}</span>;
}