Locale Switching

Alpha

The Lingo.dev Compiler is in alpha. It is unstable, not recommended for production use, and APIs may change between releases.

The Lingo.dev Compiler provides the useLingoContext() hook for reading and changing the active locale at runtime. Use it to build language switchers, locale-aware components, or any UI that responds to the user's language preference.

useLingoContext() hook#

The hook returns an object with the current locale and a function to change it:

tsx

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

const { locale, setLocale } = useLingoContext();

Property	Type	Description
`locale`	`string`	The active locale code (e.g., `"en"`, `"es"`).
`setLocale`	`(locale: string) => void`	Sets the new locale. Triggers persistence and a page reload by default.

Language switcher example#

A dropdown language switcher component:

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>
  );
}

In Next.js, the language switcher must be a Client Component ("use client") because it uses a React hook.

What happens when setLocale is called#

Locale is persisted

By default, the new locale is saved to a cookie named locale with a max-age of 1 year. This ensures the preference survives page reloads and browser restarts.

Page reloads

The page reloads to re-render all components with the new locale. Server Components fetch translations for the new locale on the server, and Client Components receive the updated dictionary.

Subsequent requests use the new locale

On the next page load, the compiler reads the persisted locale and serves the corresponding translations.

Persistence options#

The default persistence mechanism is cookie-based, configured via localePersistence:

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "locale",       // Cookie name
      maxAge: 31536000,     // 1 year in seconds
    },
  },
}

Option	Default	Description
`type`	`"cookie"`	Persistence mechanism.
`config.name`	`"locale"`	Cookie name.
`config.maxAge`	`31536000`	Cookie lifetime in seconds.

Custom persistence#

For URL-based locale routing, localStorage, or custom header-based detection, create custom locale resolvers. The persistLocale export in your client resolver controls what happens when setLocale is called:

// .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();
}

See Custom Locale Resolvers for full examples of URL-based, cookie-based, and header-based patterns.

Reading locale without switching#

If you need the current locale for display or conditional rendering without providing a switcher, use the same hook:

tsx

"use client";

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

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

Next Steps#

Custom Locale Resolvers

URL-based, localStorage, and header-based persistence

Configuration Reference

localePersistence options

Next.js Integration

Server and Client Component behavior

Vite + React

Client-side locale switching