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:

tsx

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:

tsx

"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:

tsx

"use client";

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LocaleBadge() {
  const { locale } = useLingoContext();
  return <span>{locale.toUpperCase()}</span>;
}

Próximos passos#

Resolvedores de Idioma Personalizados

Persistência baseada em URL, localStorage e headers

Referência de Configuração

Opções de localePersistence

Integração com Next.js

Comportamento de Server Components e Client Components

Vite + React

Troca de idioma no cliente