Resolvedores personalizados de idioma
Alpha
O Lingo.dev Compiler está em alpha. É instável, não recomendado para uso em produção, e as APIs podem mudar entre versões.
Resolvedores personalizados de idioma permitem substituir a forma como o Lingo.dev Compiler detecta e persiste o idioma do usuário. Por padrão, o Compiler usa persistência baseada em cookie, configurada pela opção localePersistence. Para ter mais controle — com roteamento por URL, detecção por cabeçalho, localStorage ou qualquer lógica personalizada — crie arquivos resolvedores no diretório .lingo/.
Arquivos resolvedores#
O Compiler procura dois arquivos opcionais:
| Arquivo | Ambiente | Exportações |
|---|---|---|
.lingo/locale-resolver.server.ts | Servidor (SSR, RSC) | resolveLocale(request: Request): string |
.lingo/locale-resolver.client.ts | Cliente (navegador) | resolveLocale(): string e persistLocale(locale: string): void |
Se um arquivo resolvedor existir, o Compiler o usará no lugar do comportamento padrão baseado em cookie. Se apenas um dos arquivos existir, o outro ambiente continuará usando o padrão.
Resolvedor no servidor#
O resolvedor no servidor recebe o objeto Request da requisição e retorna uma string com o código do 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";
}Resolvedor no cliente#
O resolvedor no cliente tem duas funções: uma para ler o idioma atual e outra para persistir uma mudança 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}`;
}Padrões comuns de resolvedores#
Roteamento por prefixo no caminho da 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}`;
}A função resolveLocale deve retornar um código de idioma que corresponda a um dos targetLocales ou sourceLocale configurados. Retornar um código de idioma não compatível faz com que o Compiler use o idioma de origem como fallback.