Получайте уведомления о предстоящих релизах Intlayer
    Автор: AydinTheFirst
    Создание:2025-09-09Последнее обновление:2025-09-09

    Начало работы с интернационализацией (i18n) с Intlayer и Tanstack Start

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

    Что такое Intlayer?

    Intlayer — это инновационная, открытая библиотека интернационализации (i18n), созданная для упрощения поддержки многоязычности в современных веб-приложениях.

    С помощью Intlayer вы можете:

    • Легко управлять переводами с использованием декларативных словарей на уровне компонентов.
    • Динамически локализовать метаданные, маршруты и контент.
    • Обеспечить поддержку TypeScript с автогенерируемыми типами, улучшая автодополнение и обнаружение ошибок.
    • Воспользоваться расширенными возможностями, такими как динамическое определение и переключение локали.
    • Включите маршрутизацию с учётом локали с помощью файловой системы маршрутизации Tanstack Start.

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

    Шаг 1: Создайте проект

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

    Шаг 2: Установите пакеты Intlayer

    Установите необходимые пакеты с помощью предпочитаемого менеджера пакетов:

    bash
    npm install intlayer react-intlayernpm install vite-intlayer --save-dev
    • intlayer

    • intlayer

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

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

    • vite-intlayer Включает плагин Vite для интеграции Intlayer с сборщиком Vite, а также промежуточное ПО для определения предпочтительной локали пользователя, управления cookie и обработки перенаправления 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 { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayerMiddlewarePlugin, intlayerPlugin } from "vite-intlayer";import tsconfigPaths from "vite-tsconfig-paths";export default defineConfig({  plugins: [    reactRouter(),    tsconfigPaths(),    intlayerPlugin(),    intlayerMiddlewarePlugin(),  ],});

    Плагин Vite intlayerPlugin() используется для интеграции Intlayer с Vite. Он обеспечивает сборку файлов деклараций контента и их мониторинг в режиме разработки. Также он определяет переменные окружения Intlayer внутри приложения Vite. Кроме того, он предоставляет алиасы для оптимизации производительности.

    Шаг 5: Создайте компоненты макета

    Настройте корневой макет и макеты для конкретных локалей:

    Корневой макет

    src/routes/{-$locale}/route.tsx
    // src/routes/{-$locale}/route.tsximport { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { configuration } from "intlayer";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes";export const Route = createFileRoute("/{-$locale}")({  component: LayoutComponent,});function LayoutComponent() {  const { locale } = Route.useParams();  return (    <IntlayerProvider locale={locale}>      <Outlet />    </IntlayerProvider>  );}

    Шаг 6: Объявите Ваш Контент

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

    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: "Главная",        es: "Inicio",        fr: "Accueil",      }),    },    meta: {      description: t({        en: "Это пример использования Intlayer с 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",      }),    },    title: t({      en: "Добро пожаловать в Intlayer + TanStack Router",      es: "Bienvenido a Intlayer + TanStack Router",      fr: "Bienvenue à Intlayer + TanStack Router",    }),  },  key: "app",} satisfies Dictionary;export default appContent;

    Ваши объявления контента могут быть определены в любом месте вашего приложения, как только они будут включены в каталог contentDir (по умолчанию, ./app). И соответствовать расширению файла объявления контента (по умолчанию, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

    Для получения дополнительной информации обратитесь к документации по объявлениям контента.

    Шаг 7: Создайте компоненты и хуки с поддержкой локализации

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

    src/components/localized-link.tsx
    // src/components/localized-link.tsx// eslint-disable-next-line no-restricted-importsimport { Link, type LinkProps } from "@tanstack/react-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";type LocalizedLinkProps = {  to: string;} & Omit<LinkProps, "to">;export function LocalizedLink(props: LocalizedLinkProps) {  const { locale } = useLocale();  const isExternal = (to: string) => {    return /^(https?:)?\/\//.test(to);  };  const to = isExternal(props.to)    ? props.to    : getLocalizedUrl(props.to, locale);  return <Link {...props} to={to as LinkProps["to"]} />;}

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

    src/hooks/useLocalizedNavigate.tsx
    // src/hooks/useLocalizedNavigate.tsx// eslint-disable-next-line no-restricted-importsimport { NavigateOptions, useNavigate } from "@tanstack/react-router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";type LocalizedNavigateOptions = {  to: string;} & Omit<NavigateOptions, "to">;export const useLocalizedNavigate = () => {  const navigate = useNavigate();  const { locale } = useLocale();  const isExternal = (to: string) => {    return /^(https?:)?\/\//.test(to);  };  const localizedNavigate = (options: LocalizedNavigateOptions) => {    const to = isExternal(options.to)      ? options.to      : getLocalizedUrl(options.to, locale);    navigate({ ...options, to: to as NavigateOptions["to"] });  };  return localizedNavigate;};

    Шаг 8: Использование Intlayer на ваших страницах

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

    Страница перенаправления корня

    src/routes/page.tsx
    // src/routes/page.tsximport { useLocale } from "react-intlayer";import { Navigate } from "react-router";export default function Page() {  const { locale } = useLocale();  return <Navigate replace to={locale} />;}

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

    src/routes/{-$locale}/index.tsx
    import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";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,  head: ({ params }) => {    const { locale } = params;    const metaContent = getIntlayer("app", locale);    return {      meta: [        { title: metaContent.title },        { content: metaContent.meta.description, name: "description" },      ],    };  },});function RouteComponent() {  const content = useIntlayer("app");  const navigate = useLocalizedNavigate();  return (    <div className="grid place-items-center h-screen">      <div className="flex flex-col gap-4 items-center text-center">        {content.title}        <LocaleSwitcher />        <div className="flex gap-4">          <a href="/">Индекс</a>          <LocalizedLink to="/">{content.links.home}</LocalizedLink>          <LocalizedLink to="/about">{content.links.about}</LocalizedLink>        </div>        <div className="flex gap-4">          <button onClick={() => navigate({ to: "/" })}>            {content.links.home}          </button>          <button onClick={() => navigate({ to: "/about" })}>            {content.links.about}          </button>        </div>      </div>    </div>  );}

    Чтобы узнать больше о хуке useIntlayer, обратитесь к документации.

    Шаг 9: Создайте компонент переключения локали

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

    src/components/locale-switcher.tsx
    import { useLocation } from "@tanstack/react-router";import {  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,  Locales,} from "intlayer";import { useIntlayer, useLocale } from "react-intlayer";export default function LocaleSwitcher() {  const { pathname, searchStr } = useLocation();  const content = useIntlayer("locale-switcher");  const { availableLocales, locale, setLocale } = useLocale({    onLocaleChange: (newLocale) => {      const pathWithLocale = getLocalizedUrl(pathname + searchStr, newLocale);      location.replace(pathWithLocale);    },  });  return (    <select      aria-label={content.label.toString()}      onChange={(e) => setLocale(e.target.value)}      value={locale}    >      {availableLocales.map((localeItem) => (        <option          dir={getHTMLTextDir(localeItem)}          key={localeItem}          lang={localeItem}          value={localeItem}        >          {/* Пример: Français (Французский) */}          {getLocaleName(localeItem, locale)} (          {getLocaleName(localeItem, Locales.ENGLISH)})        </option>      ))}    </select>  );}

    Чтобы узнать больше о хуке useLocale, обратитесь к документации.

    Шаг 10: Добавление управления атрибутами HTML (необязательно)

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

    src/hooks/useI18nHTMLAttributes.tsx
    // src/hooks/useI18nHTMLAttributes.tsximport { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  useEffect(() => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale); // установка атрибута dir для документа  }, [locale]);};

    Затем используйте его в вашем корневом компоненте:

    src/routes/{-$locale}/index.tsx
    import { createFileRoute, Navigate, Outlet } from "@tanstack/react-router";import { configuration } from "intlayer";import { IntlayerProvider, useLocale } from "react-intlayer";import { useI18nHTMLAttributes } from "@/hooks/useI18nHTMLAttributes"; // импорт хукаexport const Route = createFileRoute("/{-$locale}")({  component: LayoutComponent,});function LayoutComponent() {  useI18nHTMLAttributes(); // добавьте эту строку  const { locale } = Route.useParams();  return (    <IntlayerProvider locale={locale}>      <Outlet />    </IntlayerProvider>  );}

    Шаг 11: Сборка и запуск вашего приложения

    Соберите словари контента и запустите ваше приложение:

    bash
    # Сборка словарей Intlayernpm run intlayer:build# Запуск сервера разработкиnpm run dev

    Шаг 12: Настройка TypeScript (необязательно)

    Intlayer использует расширение модулей (module augmentation), чтобы использовать преимущества TypeScript и сделать ваш код более надежным.

    Убедитесь, что ваша конфигурация TypeScript включает автоматически сгенерированные типы:

    tsconfig.json
    {  compilerOptions: {    // ... ваши существующие настройки TypeScript  },  include: [    // ... ваши существующие включения    ".intlayer/**/*.ts", // Включить автоматически сгенерированные типы  ],}

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

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

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

    .gitignore
    # Игнорировать файлы, сгенерированные Intlayer.intlayer

    Шаг 13: Создание перенаправления (опционально)

    src/routes/{-$locale}/rotue.tsx
    function LayoutComponent() {  useI18nHTMLAttributes();  const { locale } = Route.useParams();  const { locale: selectedLocale } = useLocale();  const { defaultLocale } = configuration.internationalization;  const { prefixDefault } = configuration.middleware;  // Перенаправление на локаль по умолчанию, если в URL отсутствует локаль и prefixDefault установлен в true  if (selectedLocale === defaultLocale && !locale && prefixDefault) {    return <Navigate replace to={defaultLocale} />;  }  // Перенаправление на выбранную локаль, если локаль в URL не совпадает с выбранной локалью  if (selectedLocale !== defaultLocale && !locale) {    return <Navigate replace to={selectedLocale} />;  }  return (    <IntlayerProvider locale={locale}>      <Outlet />    </IntlayerProvider>  );}

    Развертывание в продакшн

    При развертывании вашего приложения:

    1. Соберите ваше приложение:

      bash
      npm run build
    2. Соберите словари Intlayer:

      bash
      npm run intlayer:build
    3. Переместите vite-intlayer в зависимости, если используете middleware в продакшн:

      bash
      npm install vite-intlayer --save

    Теперь ваше приложение будет поддерживать:

    • Структуру URL: /en, /en/about, /tr, /tr/about
    • Автоматическое определение локали на основе настроек браузера
    • Маршрутизацию с учётом локали с использованием Tanstack Start
    • Поддержку TypeScript с автогенерируемыми типами
    • Серверный рендеринг с правильной обработкой локали

    Расширение для VS Code

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

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

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

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

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


    Продвинутые возможности

    Чтобы продвинуться дальше, вы можете реализовать визуальный редактор или вынести ваш контент, используя CMS.


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

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

    История документации

    Версия Дата Изменения
    5.8.1 2025-09-09 Добавлено для Tanstack Start
    Получайте уведомления о предстоящих релизах Intlayer