Переключение локали

Альфа

Lingo.dev Compiler находится на стадии альфа-версии. Он нестабилен, не рекомендуется для production, а API могут меняться от релиза к релизу.

Lingo.dev Compiler предоставляет хук useLingoContext(), который позволяет читать и менять активную локаль во время выполнения. Используйте его, чтобы создавать переключатели языка, компоненты с поддержкой локали или любой UI, который учитывает языковые предпочтения пользователя.

Хук useLingoContext()#

Хук возвращает объект с текущей локалью и функцией для её изменения:

tsx

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

const { locale, setLocale } = useLingoContext();

Свойство	Тип	Описание
`locale`	`string`	Код активной локали, например `"en"` или `"es"`.
`setLocale`	`(locale: string) => void`	Устанавливает новую локаль. По умолчанию запускает сохранение и перезагрузку страницы.

Пример переключателя языка#

Компонент переключателя языка с выпадающим списком:

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

В Next.js переключатель языка должен быть Client Component ("use client"), потому что он использует React-хук.

Что происходит при вызове setLocale#

Локаль сохраняется

По умолчанию новая локаль сохраняется в cookie с именем locale и максимальным сроком действия 1 год. Благодаря этому выбранный язык сохраняется после перезагрузки страницы и перезапуска браузера.

Страница перезагружается

Страница перезагружается, чтобы заново отрендерить все компоненты с новой локалью. Server Components получают переводы для новой локали на сервере, а Client Components — обновлённый словарь.

Следующие запросы используют новую локаль

При следующей загрузке страницы Compiler считывает сохранённую локаль и отдает соответствующие переводы.

Параметры сохранения#

По умолчанию для сохранения используется cookie. Этот механизм настраивается через localePersistence:

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

Опция	По умолчанию	Описание
`type`	`"cookie"`	Механизм сохранения.
`config.name`	`"locale"`	Имя cookie.
`config.maxAge`	`31536000`	Срок жизни cookie в секундах.

Пользовательское сохранение#

Если вы используете маршрутизацию локали через URL, localStorage или пользовательское определение по заголовкам, создайте собственные резолверы локали. Экспорт persistLocale в клиентском резолвере определяет, что происходит при вызове setLocale:

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

Полные примеры для URL, cookie и заголовков смотрите в разделе Пользовательские резолверы локали.

Чтение локали без переключения#

Если текущая локаль нужна только для отображения или условного рендеринга, без самого переключателя, используйте тот же хук:

tsx

"use client";

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

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

Что дальше#

Пользовательские резолверы локали

Сохранение через URL, localStorage и заголовки

Справочник по конфигурации

Параметры localePersistence

Интеграция с Next.js

Поведение Server Components и Client Components

Vite + React

Переключение локали на клиенте