Alternância de idioma
Alfa
O Lingo.dev Compiler está em alfa. É instável, não é recomendado para utilização em produção e as APIs podem mudar entre versões.
O Lingo.dev Compiler disponibiliza o hook useLingoContext() para ler e alterar o idioma ativo em tempo de execução. Utilize-o para criar seletores de idioma, componentes sensíveis ao idioma ou qualquer interface que responda à preferência linguística do utilizador.
Hook useLingoContext()#
O hook devolve um objeto com o idioma atual e uma função para o alterar:
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 predefinição, ativa a persistência e recarrega a página. |
Exemplo de seletor de idioma#
Um componente de seletor de idioma em lista pendente:
"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 tem de ser um Client Component ("use client") porque utiliza um hook de React.
O que acontece quando setLocale é chamado#
O idioma é persistido
Por predefinição, o novo idioma é guardado num cookie com o nome locale e uma duração máxima de 1 ano. Isto garante que a preferência se mantém após recarregamentos da página e reinícios do navegador.
A página é recarregada
A página é recarregada para voltar a renderizar todos os componentes com o novo idioma. Os Server Components obtêm as traduções para o novo idioma no servidor, e os Client Components recebem o dicionário atualizado.
Os pedidos seguintes utilizam o novo idioma
No carregamento seguinte da página, o Compiler lê o idioma persistido e disponibiliza as traduções correspondentes.
Opções de persistência#
O mecanismo de persistência predefinido é baseado em cookies e é configurado através de localePersistence:
{
localePersistence: {
type: "cookie",
config: {
name: "locale", // Cookie name
maxAge: 31536000, // 1 year in seconds
},
},
}| Opção | Predefiniçã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 encaminhamento de idioma baseado em URL, localStorage ou deteção personalizada com base em cabeçalhos, crie resolvedores de idioma personalizados. A exportação persistLocale no resolvedor de 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 Custom Locale Resolvers para ver exemplos completos de abordagens baseadas em URL, cookies e cabeçalhos.
Ler o idioma sem alternar#
Se precisar do idioma atual para apresentação ou renderização condicional, sem disponibilizar um seletor, utilize o mesmo hook:
"use client";
import { useLingoContext } from "@lingo.dev/compiler/react";
export function LocaleBadge() {
const { locale } = useLingoContext();
return <span>{locale.toUpperCase()}</span>;
}