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.
Los resolvers de idioma personalizados te permiten sobrescribir cómo el Compiler de Lingo.dev detecta y conserva el idioma del usuario. Por defecto, el Compiler utiliza persistencia basada en cookies configurada mediante la opción localePersistence. Si necesitas más control —enrutamiento por URL, detección por cabeceras, 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 | Servidor (SSR, RSC) | resolveLocale(request: Request): string |
.lingo/locale-resolver.client.ts | Cliente (navegador) | resolveLocale(): string y persistLocale(locale: string): void |
Si existe un archivo resolver, el Compiler lo utiliza en lugar del comportamiento predeterminado basado en cookies. Si solo existe uno de los archivos, el otro entorno recurre al comportamiento predeterminado.
Resolver del lado del servidor#
El resolver de servidor recibe el objeto Request de la solicitud 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 de cliente incluye dos funciones: una para leer el idioma actual y otra para conservar 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 habituales de resolvers#
Enrutamiento por prefijo en la ruta de la 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 los targetLocales o sourceLocale que hayas configurado. Si devuelve un código de idioma no compatible, el Compiler volverá al idioma de origen.
