Resolvers de idioma personalizados
Alfa
El Compiler de Lingo.dev está en alfa. Es inestable, no se recomienda para producción y las API pueden cambiar entre versiones.
Los resolvers de idioma personalizados te permiten anular la forma en que el Compiler de Lingo.dev detecta y persiste el idioma del usuario. De forma predeterminada, el Compiler usa persistencia basada en cookies configurada mediante la opción localePersistence. Si necesitas más control —enrutamiento por URL, detección por encabezados, localStorage o cualquier lógica personalizada— crea archivos resolver en el directorio .lingo/.
Archivos resolver#
El Compiler busca dos archivos opcionales:
| Archivo | Entorno | Exportaciones |
|---|---|---|
.lingo/locale-resolver.server.ts | Del lado del servidor (SSR, RSC) | resolveLocale(request: Request): string |
.lingo/locale-resolver.client.ts | Del lado del cliente (navegador) | resolveLocale(): string y persistLocale(locale: string): void |
Si existe un archivo resolver, el Compiler lo usa en lugar del comportamiento predeterminado basado en cookies. Si solo existe uno, el otro entorno vuelve al comportamiento predeterminado.
Resolver del lado del servidor#
El resolver del servidor recibe el objeto Request entrante y devuelve una cadena con el código de idioma:
// .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";
}Resolver del lado del cliente#
El resolver del cliente tiene dos funciones: una para leer el idioma actual y otra para persistir un cambio de idioma:
// .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}`;
}Patrones comunes de resolvers#
Enruta por prefijo en la ruta 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 función resolveLocale debe devolver un código de idioma que coincida con uno de tus targetLocales o sourceLocale configurados. Si devuelve un código de idioma no compatible, el Compiler recurre al idioma de origen.