Автор:
    Aymeric PINEAU
    Создание:2025-09-09Последнее обновление:2026-08-25

    Переведите ваш Tanstack Start с Intlayer | Интернационализация (i18n)

    Содержание

    Это руководство демонстрирует, как интегрировать Intlayer для бесшовной интернационализации в проектах Tanstack Start с маршрутизацией, учитывающей локаль, поддержкой TypeScript и современными практиками разработки.

    Почему Intlayer лучше альтернатив?

    По сравнению с основными решениями, такими как «react-i18next», «use-intl» или «paraglide», Intlayer предлагает решение со встроенными оптимизациями, такими как:

    Intlayer полностью оптимизирован для TanStack Start и обеспечивает многоязычную маршрутизацию, управление файлами cookie, генерацию карты сайта, динамическую загрузку контента и все функции, необходимые для масштабирования ваших усилий по интернационализации (i18n).

    Вместо загрузки огромных файлов JSON на свои страницы загружайте только необходимый контент. Intlayer помогает уменьшить размер бандла и страниц до 50 %.

    Определение области содержимого вашего приложения облегчает обслуживание крупномасштабных приложений. Вы можете дублировать или удалить отдельную папку функций, не утруждав себя мысленным бременем проверки всей кодовой базы контента. Кроме того, Intlayer полностью типизирован, что обеспечивает точность вашего контента.

    Совместное размещение контента уменьшает контекст, необходимый для моделей большого языка (LLM). Intlayer также поставляется с набором инструментов, таких как CLI для проверки отсутствия переводов,LSP, MCP, и agent skills, чтобы сделать работу разработчика (DX) еще более удобной для агентов ИИ.

    Используйте автоматизацию для перевода в своем конвейере CI/CD, используя LLM по вашему выбору за счет вашего поставщика ИИ. Intlayer также предлагает компилятор для автоматизации извлечения контента, а также веб-платформу, которая помогает переводить в фоновом режиме.

    Подключение больших файлов JSON к компонентам может привести к проблемам с производительностью и реактивностью. Intlayer оптимизирует загрузку контента во время сборки (build time).

    Intlayer предлагает больше, чем просто решение i18n. Он предоставляет автономный визуальный редактор и полный CMS, чтобы помочь вам управлять многоязычным контентом в реальном времени, упрощая сотрудничество с переводчиками, копирайтерами и другими членами команды. Контент может храниться локально и/или удаленно.

    Пошаговое руководство по настройке Intlayer в приложении Tanstack Start

    www.youtube.com
    ide.intlayer.org
    intlayer-tanstack-start-template.vercel.app

    См. Шаблон приложения на GitHub.

    1. Создайте проект

      Начните с создания нового проекта TanStack Start, следуя руководству Start new project на сайте TanStack Start.

    2. Установите пакеты Intlayer

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

      bash
      npx intlayer init --interactive
      флаг --interactive не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.
      Эта команда определит вашу среду и установит необходимые пакеты. Например:
      bash
      npm install intlayer react-intlayer
npm install vite-intlayer --save-dev

      • intlayer

        Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, объявления контента, транспиляции и CLI-команд.

      • react-intlayer Пакет, который интегрирует Intlayer с приложением React. Он предоставляет провайдеры контекста и хуки для интернационализации в React.

      • vite-intlayer Включает плагин Vite для интеграции Intlayer с сборщиком Vite, а также промежуточное ПО для определения предпочтительной локали пользователя, управления куки и обработки перенаправления URL.

    3. Конфигурация вашего проекта

      Создайте файл конфигурации для настройки языков вашего приложения:

      intlayer.config.ts
      import type { IntlayerConfig } from "intlayer";

import { Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    defaultLocale: Locales.ENGLISH,
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
  },
};

export default config;
      С помощью этого файла конфигурации вы можете настроить локализованные URL, перенаправление через middleware, имена cookie, расположение и расширение ваших объявлений контента, отключить логи Intlayer в консоли и многое другое. Для полного списка доступных параметров обратитесь к документации по конфигурации.

    4. Интеграция Intlayer в вашу конфигурацию Vite

      Добавьте плагин intlayer в вашу конфигурацию:

      vite.config.ts
      import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

const config = defineConfig({
  plugins: [
    nitro(),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    viteReact(),
  ],
});

export default config;
      Плагин Vite intlayer() используется для интеграции Intlayer с Vite. Он обеспечивает сборку файлов деклараций контента и отслеживает их в режиме разработки. Также он определяет переменные окружения Intlayer внутри приложения Vite. Дополнительно плагин предоставляет алиасы для оптимизации производительности.

    5. Создайте корневой макет

      Настройте корневой макет для поддержки интернационализации, используя useParams для определения текущей локали и установив атрибуты lang и dir в теге html.

      src/routes/__root.tsx
      import {
  createRootRouteWithContext,
  getRouteApi,
  HeadContent,
  Scripts,
} from "@tanstack/react-router";
import { defaultLocale, getHTMLTextDir } from "intlayer";
import { type ReactNode } from "react";
import { IntlayerProvider } from "react-intlayer";

const localeRoute = getRouteApi("/{-$locale}");

export const Route = createRootRouteWithContext<{}>()({
  head: () => ({
    meta: [
      {
        charSet: "utf-8",
      },
      {
        content: "width=device-width, initial-scale=1",
        name: "viewport",
      },
      {
        title: "TanStack Start Starter",
      },
    ],
  }),

  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: ReactNode }) {
  const params = localeRoute.useParams();
  const locale = params?.locale ?? defaultLocale;

  return (
    <html dir={getHTMLTextDir(locale)} lang={locale}>
      <head>
        <HeadContent />
      </head>
      <body>
        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
        <Scripts />
      </body>
    </html>
  );
}

    6. Создайте макет локали

      Создайте макет, который обрабатывает префикс локали и выполняет валидацию.

      src/routes/{-$locale}/route.tsx
      import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
import { validatePrefix } from "intlayer";

export const Route = createFileRoute("/{-$locale}")({
  beforeLoad: ({ params }) => {
    const localeParam = params.locale;

    // Валидация префикса локали
    const { isValid, localePrefix } = validatePrefix(localeParam);

    if (!isValid) {
      throw redirect({
        to: "/{-$locale}/404",
        params: { locale: localePrefix },
      });
    }
  },
  component: Outlet,
});
      Здесь {-$locale}, это динамический параметр маршрута, который заменяется текущей локалью. Эта нотация делает слот необязательным, позволяя ему работать с такими режимами маршрутизации, как 'prefix-no-default' и т. д.

      Имейте в виду, что этот слот может вызвать проблемы, если вы используете несколько динамических сегментов в одном маршруте (например, /{-$locale}/other-path/$anotherDynamicPath/...). Для режима 'prefix-all' вы можете предпочесть переключить слот на $locale. Для режимов 'no-prefix' или 'search-params' вы можете полностью удалить слот.

    7. Объявите ваш контент

      Создавайте и управляйте объявлениями контента для хранения переводов:

      src/contents/page.content.ts
      import type { Dictionary } from "intlayer";

import { t } from "intlayer";

const appContent = {
  content: {
    links: {
      about: t({
        en: "About",
        es: "Acerca de",
        fr: "À propos",
      }),
      home: t({
        en: "Home",
        es: "Inicio",
        fr: "Accueil",
      }),
    },
    meta: {
      title: t({
        en: "Welcome to Intlayer + TanStack Router",
        es: "Bienvenido a Intlayer + TanStack Router",
        fr: "Bienvenue à Intlayer + TanStack Router",
      }),
      description: t({
        en: "This is an example of using Intlayer with TanStack Router",
        es: "Este es un ejemplo de uso de Intlayer con TanStack Router",
        fr: "Ceci est un exemple d'utilisation d'Intlayer avec TanStack Router",
      }),
    },
  },
  key: "app",
} satisfies Dictionary;

export default appContent;
      Ваши объявления контента могут быть определены в любом месте вашего приложения, как только они включены в директорию contentDir (по умолчанию, ./app). И соответствуют расширению файла объявления контента (по умолчанию, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Для получения дополнительной информации обратитесь к документации по объявлениям контента.

    8. Создание компонентов и хуков с поддержкой локализации

      Создайте компонент LocalizedLink для навигации с учетом локали:

      src/components/localized-link.tsx
      import type { FC } from "react";

import { Link, type LinkComponentProps } from "@tanstack/react-router";
import { useLocale } from "react-intlayer";
import { getPrefix } from "intlayer";

export const LOCALE_ROUTE = "{-$locale}" as const;

export type To = StripLocalePrefix<LinkComponentProps["to"]>;

export type StripLocalePrefix<T extends string | undefined> = T extends
  `/${typeof LOCALE_ROUTE}/` | `/${typeof LOCALE_ROUTE}`
  ? "/"
  : T extends `/${typeof LOCALE_ROUTE}/${infer Rest}`
    ? `/${Rest}`
    : T;

type LocalizedLinkProps = {
  to?: To;
} & Omit<LinkComponentProps, "to">;

export const LocalizedLink: FC<LocalizedLinkProps> = (props) => {
  const { locale } = useLocale();
  const { localePrefix } = getPrefix(locale);

  return (
    <Link
      {...props}
      params={{
        locale: localePrefix,
        ...(typeof props?.params === "object" ? props?.params : {}),
      }}
      to={`/${LOCALE_ROUTE}${props.to}` as LinkComponentProps["to"]}
    />
  );
};

      Этот компонент выполняет две задачи:

      • Удаляет ненужный префикс {-$locale} из URL.
      • Вставляет параметр локали в URL, чтобы пользователь был напрямую перенаправлен на локализованный маршрут.

      Далее мы можем создать хук useLocalizedNavigate для программной навигации:

      src/hooks/useLocalizedNavigate.tsx
      import { useNavigate } from "@tanstack/react-router";
import { getPrefix } from "intlayer";
import { useLocale } from "react-intlayer";
import type { StripLocalePrefix } from "@/components/localized-link";
import type { FileRouteTypes } from "@/routeTree.gen";

type NavigateFn = ReturnType<typeof useNavigate>;
type BaseNavigateOptions = Parameters<NavigateFn>[0];

type LocalizedTo = StripLocalePrefix<FileRouteTypes["to"]>;

export type LocalizedNavigateOptions = Omit<
  BaseNavigateOptions,
  "to" | "params"
> & {
  to: LocalizedTo;
  params?: Omit<NonNullable<BaseNavigateOptions["params"]>, "locale">;
};

type LocalizedNavigate = (
  options: LocalizedNavigateOptions
) => ReturnType<NavigateFn>;

export const useLocalizedNavigate = () => {
  const navigate = useNavigate();

  const { locale } = useLocale();

  const localizedNavigate: LocalizedNavigate = (args: any) => {
    const { localePrefix } = getPrefix(locale);

    if (typeof args === "string") {
      return navigate({
        to: `/${LOCALE_ROUTE}${args}`,
        params: { locale: localePrefix },
      });
    }

    const { to, ...rest } = args;

    const localizedTo = `/${LOCALE_ROUTE}${to}` as any;

    return navigate({
      to: localizedTo,
      params: { locale: localePrefix, ...rest } as any,
    });
  };

  return localizedNavigate;
};

    9. Использование Intlayer на ваших страницах

      Используйте useIntlayer по умолчанию: это рекомендуемый способ читать контент внутри компонентов, и компилятор разрешает его в отрисовываемую локаль. Обращайтесь к getIntlayer / getIntlayerAsync только вне дерева React: в head маршрутов, загрузчиках и серверных функциях.

      Получайте доступ к вашим словарям контента по всему приложению:

      Локализованная домашняя страница

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import { useIntlayer } from "react-intlayer";

import LocaleSwitcher from "@/components/locale-switcher";
import { LocalizedLink } from "@/components/localized-link";
import { useLocalizedNavigate } from "@/hooks/useLocalizedNavigate";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
});

function RouteComponent() {
  const content = useIntlayer("app");
  const navigate = useLocalizedNavigate();

  return (
    <div>
      <div>
        {content.title}
        <LocaleSwitcher />
        <div>
          <LocalizedLink to="/">{content.links.home}</LocalizedLink>
          <LocalizedLink to="/about">{content.links.about}</LocalizedLink>
        </div>
        <div>
          <button onClick={() => navigate({ to: "/" })}>
            {content.links.home}
          </button>
          <button onClick={() => navigate({ to: "/about" })}>
            {content.links.about}
          </button>
        </div>
      </div>
    </div>
  );
}

      Если вы хотите использовать ваш контент в атрибуте string, таком как alt, title, href, aria-label и т. д., вы можете использовать значение функции, например:

      html
      <img src="{content.image.src.value}" alt="{content.image.value}" />
<img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
<img src="{String(content.image.src)}" alt="{String(content.image)}" />
      Чтобы узнать больше о хуке useIntlayer, обратитесь к документации.

    10. Создание компонента переключателя локали

      Создайте компонент, позволяющий пользователям изменять языки:

      src/components/locale-switcher.tsx
      import { useLocation } from "@tanstack/react-router";
import {
  getHTMLTextDir,
  getLocaleName,
  getPathWithoutLocale,
  getPrefix,
  Locales,
} from "intlayer";
import type { FC } from "react";
import { useLocale } from "react-intlayer";

import { LocalizedLink, type To } from "./localized-link";

export const LocaleSwitcher: FC = () => {
  const { pathname } = useLocation();

  const { availableLocales, locale, setLocale } = useLocale();

  const pathWithoutLocale = getPathWithoutLocale(pathname);

  return (
    <ol>
      {availableLocales.map((localeEl) => (
        <li key={localeEl}>
          <LocalizedLink
            aria-current={localeEl === locale ? "page" : undefined}
            onClick={() => setLocale(localeEl)}
            params={{ locale: getPrefix(localeEl).localePrefix }}
            to={pathWithoutLocale as To}
          >
            <span>
              {/* Локаль - например FR */}
              {localeEl}
            </span>
            <span>
              {/* Язык в его собственной локали - например Français */}
              {getLocaleName(localeEl, locale)}
            </span>
            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
              {/* Язык в текущей локали - например Francés с текущей локалью установленной в Locales.SPANISH */}
              {getLocaleName(localeEl)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Язык на английском - например French */}
              {getLocaleName(localeEl, Locales.ENGLISH)}
            </span>
          </LocalizedLink>
        </li>
      ))}
    </ol>
  );
};
      Чтобы узнать больше о хуке useLocale, обратитесь к документации.

    11. Управление атрибутами HTML

      Как показано на шаге 5, вы можете управлять атрибутами lang и dir тега html используя useParams в вашем корневом компоненте. Это гарантирует, что правильные атрибуты установлены на сервере и клиенте.

      src/routes/__root.tsx
      const localeRoute = getRouteApi("/{-$locale}");

function RootDocument({ children }: { children: ReactNode }) {
  const params = localeRoute.useParams();
  const locale = params?.locale ?? defaultLocale;

  return (
    <html dir={getHTMLTextDir(locale)} lang={locale}>
      {/* ... */}
    </html>
  );
}

    12. Добавить middleware

      Вы также можете использовать intlayerProxy для добавления маршрутизации на стороне сервера в ваше приложение. Этот плагин автоматически определит текущую локаль на основе URL и установит соответствующий файл cookie локали. Если локаль не указана, плагин определит наиболее подходящую локаль на основе предпочтений языка браузера пользователя. Если локаль не обнаружена, он перенаправит на локаль по умолчанию.

      Обратите внимание, что для использования intlayerProxy в production вам необходимо переместить пакет vite-intlayer из devDependencies в dependencies.
      Начиная с Intlayer v9, intlayerProxy() встроен непосредственно в плагин intlayer() и включен по умолчанию через опцию routing.enableProxy (true по умолчанию). Регистрация его отдельно, как показано ниже, теперь опциональна: она сохранена для обратной совместимости и для настроек, которым нужно контролировать порядок плагинов. Установите routing.enableProxy: false чтобы отключить. Смотрите примечания к выпуску v9.
      vite.config.ts
      import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    nitro(),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
    tanstackStart({
      router: {
        routeFileIgnorePattern:
          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
      },
    }),
    viteReact(),
  ],
});

    13. Интернационализация ваших метаданных

      getIntlayer разрешает синхронно против объединённого словаря, того, который содержит каждую объявленную локаль. head остаётся синхронным и ничего не ожидается, но весь многоязычный словарь вытягивается в chunk маршрута, отправляемый в браузер.

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import {
  defaultLocale,
  getIntlayer,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  head: ({ params }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // Путь для этого маршрута

    const metaContent = getIntlayer("app", locale);

    return {
      links: [
        // Канонический link: Указывает на текущую локализованную страницу
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Расскажите Google обо всех локализованных версиях
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: Для пользователей на несоответствующих языках
        // Определите локаль по умолчанию (обычно ваш основной язык)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});

      Лучше всего для небольших словарей метаданных, нескольких локалей или при прототипировании.

      getIntlayerAsync (доступно с v9.4) ведёт себя как getIntlayer, но плагин сборки указывает его на chunk для конкретной локали в .intlayer/dynamic_dictionaries/ вместо объединённого словаря. Поэтому страница доставляет только локаль, которую она отображает. Поскольку этот chunk загружается по требованию, head становится async:

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import {
  defaultLocale,
  getIntlayerAsync,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  head: async ({ params }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // Путь для этого маршрута

    const metaContent = await getIntlayerAsync("app", locale);

    return {
      links: [
        // Канонический link: Указывает на текущую локализованную страницу
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Расскажите Google обо всех локализованных версиях
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: Для пользователей на несоответствующих языках
        // Определите локаль по умолчанию (обычно ваш основной язык)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: metaContent.title },
        { name: "description", content: metaContent.meta.description },
      ],
    };
  },
});
      Если head читает несколько словарей, разрешите их с помощью Promise.all: ожидание каждого getIntlayerAsync в отдельной строке цепляет запросы вместо параллельного выполнения.

      Компромисс: динамический импорт разрешается во время выполнения head, на критическом пути рендера документа. На холодном маршруте это задерживает head на несколько миллисекунд и может немного ухудшить LCP.

      Разрешите словарь в loader маршрута и прочитайте его обратно из loaderData в head. Loaders совпадающих маршрутов выполняются параллельно, и staleTime: Infinity говорит TanStack Router, что результат никогда не устаревает, поэтому chunk для конкретной локали разрешается один раз и впоследствии подается из кеша маршрутизатора, оставляя head синхронным.

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";
import {
  defaultLocale,
  getIntlayerAsync,
  getLocalizedUrl,
  localeMap,
} from "intlayer";

export const Route = createFileRoute("/{-$locale}/")({
  component: RouteComponent,
  // Разрешено параллельно с другими совпадающими маршрутами, вне критического пути head
  loader: async ({ params }) => {
    const { locale = defaultLocale } = params;

    return { metaContent: await getIntlayerAsync("app", locale) };
  },
  // Словарь никогда не меняется для данной локали: разрешите chunk один раз
  staleTime: Infinity,
  head: ({ params, loaderData }) => {
    const { locale = defaultLocale } = params;
    const path = "/"; // Путь для этого маршрута

    return {
      links: [
        // Канонический link: Указывает на текущую локализованную страницу
        { rel: "canonical", href: getLocalizedUrl(path, locale) },

        // Hreflang: Расскажите Google обо всех локализованных версиях
        ...localeMap(({ locale: mapLocale }) => ({
          rel: "alternate",
          hrefLang: mapLocale,
          href: getLocalizedUrl(path, mapLocale),
        })),

        // x-default: Для пользователей на несоответствующих языках
        // Определите локаль по умолчанию (обычно ваш основной язык)
        {
          rel: "alternate",
          hrefLang: "x-default",
          href: getLocalizedUrl(path, defaultLocale),
        },
      ],
      meta: [
        { title: loaderData?.metaContent.title },
        {
          name: "description",
          content: loaderData?.metaContent.meta.description,
        },
      ],
    };
  },
});
      head может быть вызван до того, как loader завершится, поэтому loaderData типизируется как возможно undefined. Сохраните опциональную цепочку или верните резервное название.

      Вы сохраняете chunk для конкретной локали без его стоимости на критическом пути head. Цена — это опыт разработчика: содержимое должно быть явно передано из loader в head через loaderData.

      Какое разрешение выбрать?

      Статическое разрешение Динамическое разрешение Кэшированное динамическое разрешение
      API getIntlayer getIntlayerAsync (v9.4+) getIntlayerAsync in loader (v9.4+)
      head signature synchronous async synchronous, reads loaderData
      Locales shipped every declared locale requested locale only requested locale only
      Client navigations nothing to resolve re-entered on every match served from the router cache
      Developer experience simplest one await content threaded through loaderData

    14. Получите языковой стандарт в ваших серверных действиях

      Вы можете захотеть получить доступ к текущему языковому стандарту из ваших серверных действий или конечных точек API. Вы можете сделать это, используя помощник getLocale из intlayer.

      Вот пример использования серверных функций TanStack Start:

      src/routes/{-$locale}/index.tsx
      import { createServerFn } from "@tanstack/react-start";
import {
  getRequestHeader,
  getRequestHeaders,
} from "@tanstack/react-start/server";
import { getCookie, getIntlayer, getLocale } from "intlayer";

export const getLocaleServer = createServerFn().handler(async () => {
  const locale = await getLocale({
    // Получите cookie из запроса (по умолчанию: 'INTLAYER_LOCALE')
    getCookie: (name) => {
      const cookieString = getRequestHeader("cookie");

      return getCookie(name, cookieString);
    },
    // Получите заголовок из запроса (по умолчанию: 'x-intlayer-locale')
    // Резервный вариант с использованием переговоров Accept-Language
    getHeader: (name) => getRequestHeader(name),
  });

  // Получите некоторое содержимое, используя getIntlayerAsync()
  const content = getIntlayer("app", locale);

  return { locale, content };
});

    15. Управление страницами «не найдено»

      Когда пользователь посещает несуществующую страницу, вы можете отобразить пользовательскую страницу «не найдено», и префикс языкового стандарта может повлиять на способ срабатывания страницы «не найдено».

      Локализованная главная страница

      Если вы хотите использовать ваше содержимое в атрибуте string, таком как alt, title, href, aria-label и т. д., вы можете использовать значение функции, например:

      html
      <img src="{content.image.src.value}" alt="{content.image.value}" />
<img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
<img src="{String(content.image.src)}" alt="{String(content.image)}" />
      Чтобы узнать больше о хуке useIntlayer, обратитесь к документации.
      16. src/components/locale-switcher.tsx
      import { useLocation } from "@tanstack/react-router";
import {
  getHTMLTextDir,
  getLocaleName,
  getPathWithoutLocale,
  getPrefix,
  Locales,
} from "intlayer";
import type { FC } from "react";
import { useLocale } from "react-intlayer";

import { LocalizedLink, type To } from "./localized-link";

export const LocaleSwitcher: FC = () => {
  const { pathname } = useLocation();

  const { availableLocales, locale, setLocale } = useLocale();

  const pathWithoutLocale = getPathWithoutLocale(pathname);

  return (
    <ol>
      {availableLocales.map((localeEl) => (
        <li key={localeEl}>
          <LocalizedLink
            aria-current={localeEl === locale ? "page" : undefined}
            onClick={() => setLocale(localeEl)}
            params={{ locale: getPrefix(localeEl).localePrefix }}
            to={pathWithoutLocale as To}
          >
            <span>
              {/* Локаль - например, FR */}
              {localeEl}
            </span>
            <span>
              {/* Язык на его собственной локали - например, Français */}
              {getLocaleName(localeEl, locale)}
            </span>
            <span dir={getHTMLTextDir(localeEl)} lang={localeEl}>
              {/* Язык на текущей локали - например, Francés при установленной локали Locales.SPANISH */}
              {getLocaleName(localeEl)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Язык на английском - например, French */}
              {getLocaleName(localeEl, Locales.ENGLISH)}
            </span>
          </LocalizedLink>
        </li>
      ))}
    </ol>
  );
};
      Чтобы узнать больше о хуке useLocale, обратитесь к документации.

      </Step>

    16. Управление атрибутами HTML

      return ( {/* ... _/} ); } {/_ ... */} </html> ); }

      export const Route = createFileRoute("/{-$locale}/")({ component: RouteComponent, head: async ({ params }) => { const { locale = defaultLocale } = params; const path = "/"; // The path for this route

      plaintext
      const metaContent = await getIntlayerAsync("app", locale);
      plaintext
      
> Если `head` читает несколько словарей, разрешайте их через `Promise.all`: ожидание каждого `getIntlayerAsync` отдельной строкой выстраивает запросы в цепочку вместо параллельного выполнения.

Компромисс: динамический импорт разрешается во время выполнения `head`, на критическом пути рендеринга документа. На «холодном» маршруте это задерживает `head` на несколько миллисекунд и может немного ухудшить **LCP**.

</Tab>

<Tab label="Кэшированное динамическое разрешение" value="cached">

Разрешите словарь в `loader` маршрута и прочитайте его обратно из `loaderData` в `head`. Загрузчики совпавших маршрутов выполняются параллельно, а `staleTime: Infinity` сообщает TanStack Router, что результат никогда не устаревает, поэтому пер-локальный чанк разрешается один раз, а затем отдаётся из кэша роутера, оставляя `head` синхронным.

```tsx fileName="src/routes/{-$locale}/index.tsx"
      return getCookie(name, cookieString);
    },
    // Получить заголовок из запроса (по умолчанию: 'x-intlayer-locale')
    // Резервный вариант с использованием согласования Accept-Language
    getHeader: (name) => getRequestHeader(name),
  });

  // Получить контент с помощью getIntlayer()
  const content = getIntlayer("app", locale);

    17. Управление страницами &quot;не найдено&quot;

      Когда пользователь посещает несуществующую страницу, вы можете отобразить пользовательскую страницу "не найдено", и префикс локали может повлиять на способ срабатывания страницы "не найдено".

      Понимание обработки 404 в TanStack Router с префиксами локали

      В TanStack Router обработка страниц 404 с локализованными маршрутами требует многоуровневого подхода:

      1. Выделенный маршрут 404: Специфический маршрут для отображения интерфейса 404
      2. Проверка на уровне маршрута: Проверяет префиксы локали и перенаправляет недействительные на 404
      3. Маршрут catch-all: Перехватывает все несовпадающие пути в сегменте локали
      src/routes/{-$locale}/404.tsx
      src/routes/{-$locale}/route.tsx
      src/routes/{-$locale}/$.tsx

    18. Извлечение содержимого ваших компонентов

      Необязательно

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

      Чтобы упростить этот процесс, Intlayer предлагает компилятор / экстрактор для преобразования ваших компонентов и извлечения содержимого.

      Чтобы настроить его, вы можете добавить раздел compiler в ваш файл intlayer.config.ts:

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

    /**
     * Определяет путь к выходным файлам
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Префикс ключа словаря
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      Запустите экстрактор для преобразования компонентов и извлечения содержимого

      bash

      bun x intlayer extract import { defineConfig } from "vite"; import { intlayer, intlayerCompiler } from "vite-intlayer";

      export default defineConfig({ plugins: [

      plaintext
      intlayer(),
intlayerCompiler(), // Adds the compiler plugin

      ], });

      plaintext

      bash packageManager="npm" npm run build # Или npm run dev

      plaintext

      bash packageManager="pnpm" pnpm run build # Or pnpm run dev

      plaintext

      bash packageManager="yarn" yarn build # Or yarn dev

      plaintext

      bash packageManager="bun"

      bun run build # Or bun run dev import { localeFlatMap } from "intlayer"; // ... другие импорты

      export const pathList = ["", "/about", "/404"];

      const localizedPages = localeFlatMap(({ urlPrefix }) => pathList.map((path) => ({

      plaintext
      path: `${urlPrefix}${path}`,
prerender: {
  enabled: true,
},

      })) );

      export default defineConfig({ plugins: [

      plaintext
      // ... другие плагины
tanstackStart({
  // ... другие настройки
  sitemap: {
    enabled: false,
  },
  prerender: {
    enabled: true,
    crawlLinks: false,
    concurrency: 10,
  },
  pages: localizedPages,
}),

      ], });

      plaintext
      
Затем создайте маршрут `src/routes/sitemap[.]xml.ts`, который использует функцию `generateSitemap`:

      `typescript fileName="src/routes/sitemap[.]xml.ts"

      export const Route = createFileRoute("/sitemap.xml")({ server: {

      plaintext
      handlers: {
  GET: async () => {
    const sitemap = generateSitemap(
      [
        { path: "/", changefreq: "daily", priority: 1.0 },
        { path: "/about", changefreq: "monthly", priority: 0.8 },
      ],
      { siteUrl: SITE_URL }
    );

    return new Response(sitemap, {
      headers: { "Content-Type": "application/xml" },
    });
  },
},

      }, }); { // ... ваши существующие настройки include: [

      plaintext
      // ... ваши существующие включения
".intlayer/**/*.ts", // Включить автоматически сгенерированные типы

      ], }

      Конфигурация Git

      Рекомендуется игнорировать файлы, созданные Intlayer. Это позволяет избежать их фиксации в репозитории Git.

      Для этого вы можете добавить следующие инструкции в файл .gitignore:

      .gitignore
      # Ignore the files generated by Intlayer
.intlayer

      `

      Расширение VS Code

      Чтобы улучшить опыт разработки с Intlayer, вы можете установить официальное расширение Intlayer VS Code.

      Установить из VS Code Marketplace

      Это расширение предоставляет:

      • Автодополнение для ключей переводов.
      • Обнаружение ошибок в реальном времени для отсутствующих переводов.
      • Встроенные предпросмотры переведённого контента.
      • Быстрые действия для удобного создания и обновления переводов.

      Для получения дополнительной информации об использовании расширения см. документацию расширения Intlayer VS Code.

      Дальше

      Чтобы пойти дальше, вы можете реализовать visual editor или экстернализировать ваш контент с помощью CMS.

      Ссылки на документацию

      CompilerTanstack Start Solid