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

Настройте, как определяется и сохраняется локаль, с помощью собственных файлов-резолверов.

По умолчанию компилятор использует куки для сохранения локали. Пользовательские резолверы позволяют реализовать другие стратегии, такие как localStorage, параметры URL, поиск в базе данных или определение по поддомену.

Как это работает

Создайте необязательные файлы в директории .lingo/:

.lingo/locale-resolver.server.ts — определение локали на сервере
.lingo/locale-resolver.client.ts — определение и сохранение локали на клиенте

Если эти файлы отсутствуют, компилятор использует стандартную реализацию на основе куки.

Серверный резолвер локали

Создайте .lingo/locale-resolver.server.ts для пользовательского определения локали на сервере:

// .lingo/locale-resolver.server.ts
export async function getServerLocale(): Promise<string> {
  // Your custom logic
  return "en";
}

Пример: заголовок Accept-Language (Next.js)

import { headers } from "next/headers";

export async function getServerLocale(): Promise<string> {
  const headersList = await headers();
  const acceptLanguage = headersList.get("accept-language");

  // Parse accept-language: "en-US,en;q=0.9,es;q=0.8"
  const locale = acceptLanguage
    ?.split(",")[0]
    ?.split("-")[0]
    ?.trim() || "en";

  return locale;
}

Пример: поиск в базе данных

import { cookies } from "next/headers";
import { db } from "@/lib/db";

export async function getServerLocale(): Promise<string> {
  const cookieStore = await cookies();
  const sessionToken = cookieStore.get("session")?.value;

  if (!sessionToken) return "en";

  // Query user preferences from database
  const user = await db.user.findUnique({
    where: { sessionToken },
    select: { preferredLocale: true },
  });

  return user?.preferredLocale || "en";
}

Пример: определение по поддомену

import { headers } from "next/headers";

export async function getServerLocale(): Promise<string> {
  const headersList = await headers();
  const host = headersList.get("host") || "";

  // Extract subdomain: es.example.com → es
  const subdomain = host.split(".")[0];

  // Map subdomain to locale
  const localeMap: Record<string, string> = {
    es: "es",
    de: "de",
    fr: "fr",
  };

  return localeMap[subdomain] || "en";
}

Клиентский резолвер локали

Создайте .lingo/locale-resolver.client.ts для пользовательского определения и сохранения локали на клиенте:

// .lingo/locale-resolver.client.ts
export function getClientLocale(): string {
  // Detect locale
  return "en";
}

export function persistLocale(locale: string): void {
  // Save locale preference
}

Пример: localStorage

export function getClientLocale(): string {
  if (typeof window === "undefined") return "en";

  // Check localStorage
  const stored = localStorage.getItem("user-locale");
  if (stored) return stored;

  // Fall back to browser language
  return navigator.language.split("-")[0] || "en";
}

export function persistLocale(locale: string): void {
  if (typeof window === "undefined") return;

  localStorage.setItem("user-locale", locale);

  // Optionally reload page to apply new locale
  window.location.reload();
}

Пример: параметры URL

export function getClientLocale(): string {
  if (typeof window === "undefined") return "en";

  // Check URL parameter: ?lang=es
  const params = new URLSearchParams(window.location.search);
  const urlLocale = params.get("lang");

  if (urlLocale) return urlLocale;

  // Fall back to localStorage
  return localStorage.getItem("locale") || "en";
}

export function persistLocale(locale: string): void {
  if (typeof window === "undefined") return;

  // Update URL parameter
  const url = new URL(window.location.href);
  url.searchParams.set("lang", locale);
  window.history.replaceState({}, "", url.toString());

  // Also save to localStorage
  localStorage.setItem("locale", locale);

  // Reload to apply new locale
  window.location.reload();
}

Пример: комбинированная стратегия

export function getClientLocale(): string {
  if (typeof window === "undefined") return "en";

  // Priority 1: URL parameter
  const params = new URLSearchParams(window.location.search);
  const urlLocale = params.get("lang");
  if (urlLocale) return urlLocale;

  // Priority 2: localStorage
  const stored = localStorage.getItem("locale");
  if (stored) return stored;

  // Priority 3: Browser language
  const browserLocale = navigator.language.split("-")[0];
  const supportedLocales = ["en", "es", "de", "fr"];
  if (supportedLocales.includes(browserLocale)) {
    return browserLocale;
  }

  // Priority 4: Default
  return "en";
}

export function persistLocale(locale: string): void {
  if (typeof window === "undefined") return;

  // Save to localStorage
  localStorage.setItem("locale", locale);

  // Update URL
  const url = new URL(window.location.href);
  url.searchParams.set("lang", locale);
  window.history.replaceState({}, "", url.toString());

  // Reload page
  window.location.reload();
}

Типы TypeScript

Оба резолвера полностью типизированы:

// Server resolver
export async function getServerLocale(): Promise<string>;

// Client resolver
export function getClientLocale(): string;
export function persistLocale(locale: string): void;

Интеграция с setLocale

Функция setLocale() из useLingoContext() автоматически вызывает ваш кастомный persistLocale():

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

function MyComponent() {
  const { setLocale } = useLingoContext();

  // Calls your persistLocale() under the hood
  setLocale("es");
}

Особенности SSR

Для SSR-фреймворков (Next.js, Remix и др.):

Серверный резолвер запускается при каждом запросе
Клиентский резолвер работает в браузере после гидрации
Важно обеспечить согласованность между определением на сервере и клиенте

Типовой паттерн: Сервер читает из cookie/заголовка, клиент сохраняет в cookie/localStorage.

Реализация по умолчанию

Если не заданы кастомные резолверы, компилятор использует такой дефолт:

// Default server resolver
export async function getServerLocale(): Promise<string> {
  const cookies = await import("next/headers").then((m) => m.cookies());
  return cookies().get("locale")?.value || "en";
}

// Default client resolver
export function getClientLocale(): string {
  return document.cookie
    .split("; ")
    .find((row) => row.startsWith("locale="))
    ?.split("=")[1] || "en";
}

export function persistLocale(locale: string): void {
  document.cookie = `locale=${locale}; path=/; max-age=31536000`;
  window.location.reload();
}

Частые вопросы

Нужны ли оба резолвера — серверный и клиентский? Нет. Добавляйте только то, что хотите кастомизировать. Для отсутствующих файлов используется поведение по умолчанию.

Можно ли использовать кастомные резолверы в SPA? Да. Для SPA нужен только клиентский резолвер. Серверный — для SSR.

Работает ли это с Vite? Да. Клиентский резолвер работает так же. Серверный резолвер специфичен для Next.js (SSR).

Как тестировать кастомные резолверы?

Создайте файлы резолверов
Реализуйте свою логику
Запустите dev-сервер
Проверьте переключение локали с вашей кастомной логикой сохранения

Можно ли использовать Next.js-специфичные API? Да. Импортируйте утилиты Next.js (headers, cookies и т.д.) прямо в файлы резолверов.

Что если getServerLocale вернёт невалидную локаль? Компилятор использует sourceLocale если возвращённая локаль не входит в targetLocales.

Примеры по кейсам

Роутинг по поддомену

Сервер:

const host = (await headers()).get("host") || "";
const locale = host.split(".")[0]; // es.example.com → es
return supportedLocales.includes(locale) ? locale : "en";

Клиент:

const locale = window.location.hostname.split(".")[0];
return supportedLocales.includes(locale) ? locale : "en";

Предпочтения пользователя из базы данных

Сервер:

const session = await getSession();
const user = await db.user.findUnique({
  where: { id: session.userId },
});
return user.locale || "en";

Клиент:

// After user changes locale in UI
await fetch("/api/user/locale", {
  method: "POST",
  body: JSON.stringify({ locale }),
});
window.location.reload();

Маршрутизация по пути (/en/about, /es/about)

Сервер:

const pathname = (await headers()).get("x-pathname") || "/";
const locale = pathname.split("/")[1];
return supportedLocales.includes(locale) ? locale : "en";

Клиент:

const locale = window.location.pathname.split("/")[1];
return supportedLocales.includes(locale) ? locale : "en";

Дальнейшие шаги

Смена локали — Реализуйте переключатели языков
Интеграция с фреймворками — Специфика для разных фреймворков
Лучшие практики — Рекомендованные стратегии определения локали