Troca de idioma
Alfa
O Compiler da Lingo.dev está em alfa. Ele é instável, não é recomendado para uso em produção, e as APIs podem mudar entre versões.
O Compiler da Lingo.dev oferece o hook useLingoContext() para ler e alterar o idioma ativo em tempo de execução. Use-o para criar seletores de idioma, componentes sensíveis ao idioma ou qualquer interface que responda à preferência de idioma do usuário.
Hook useLingoContext()#
O hook retorna um objeto com o idioma atual e uma função para alterá-lo:
import { useLingoContext } from "@lingo.dev/compiler/react";
const { locale, setLocale } = useLingoContext();| Propriedade | Tipo | Descrição |
|---|---|---|
locale | string | O código do idioma ativo (por exemplo, "en", "es"). |
setLocale | (locale: string) => void | Define o novo idioma. Por padrão, aciona a persistência e recarrega a página. |
Exemplo de seletor de idioma#
Um componente de seletor de idioma em dropdown:
"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>
);
}No Next.js, o seletor de idioma precisa ser um Client Component ("use client"), porque usa um hook do React.
O que acontece quando setLocale é chamado#
O idioma é persistido
Por padrão, o novo idioma é salvo em um cookie chamado locale, com duração máxima de 1 ano. Isso garante que a preferência seja mantida após recarregamentos de página e reinicializações do navegador.
A página é recarregada
A página é recarregada para renderizar novamente todos os componentes com o novo idioma. Os Server Components buscam as traduções do novo idioma no servidor, e os Client Components recebem o dicionário atualizado.
As próximas requisições usam o novo idioma
No próximo carregamento da página, o Compiler lê o idioma persistido e entrega as traduções correspondentes.
Opções de persistência#
O mecanismo de persistência padrão é baseado em cookies e configurado via localePersistence:
{
localePersistence: {
type: "cookie",
config: {
name: "locale", // Cookie name
maxAge: 31536000, // 1 year in seconds
},
},
}| Opção | Padrão | Descrição |
|---|---|---|
type | "cookie" | Mecanismo de persistência. |
config.name | "locale" | Nome do cookie. |
config.maxAge | 31536000 | Tempo de vida do cookie, em segundos. |
Persistência personalizada#
Para roteamento de idioma baseado em URL, localStorage ou detecção personalizada com base em headers, crie resolvedores de idioma personalizados. A exportação persistLocale no resolvedor do cliente controla o que acontece quando setLocale é chamado:
// .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();
}Consulte Resolvedores de Idioma Personalizados para ver exemplos completos de padrões baseados em URL, cookies e headers.
Ler o idioma sem alternar#
Se você precisa do idioma atual para exibição ou renderização condicional, sem oferecer um seletor, use o mesmo hook:
"use client";
import { useLingoContext } from "@lingo.dev/compiler/react";
export function LocaleBadge() {
const { locale } = useLingoContext();
return <span>{locale.toUpperCase()}</span>;
}