Creation:2025-09-09Last update:2026-05-31

    Перекладіть ваш вебсайт Tanstack Start за допомогою Intlayer | Інтернаціоналізація (i18n)

    Зміст

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

    Чому варто обрати Intlayer, а не альтернативи?

    Порівняно з основними рішеннями, такими як react-i18next або use-intl або paraglide, Intlayer — це рішення, яке має такі інтегровані оптимізації, як:

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

    Замість того, щоб завантажувати великі файли JSON на свої сторінки, завантажуйте лише необхідний вміст. Intlayer допомагає зменшити розмір бандлу і сторінок до 50%.

    Організація вмісту за окремими областями (scoping) полегшує технічне обслуговування великомасштабних програм. Ви можете скопіювати або видалити окрему папку функцій без розумового навантаження перегляду всієї кодової бази вмісту. Крім того, Intlayer повністю типізований (fully typed), щоб забезпечити точність вашого вмісту.

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

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

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

    Більше ніж просто рішення i18n, Intlayer пропонує власний візуальний редактор і повний CMS, щоб допомогти вам керувати своїм багатомовним вмістом у реальному часі, спрощуючи співпрацю з перекладачами, копірайтерами та іншими членами команди. Контент можна зберігати локально та/або віддалено.

    Покроковий посібник з налаштування Intlayer у застосунку Tanstack Start

    www.youtube.com

    Перегляньте Шаблон додатка на GitHub.

    1. Створіть проект

      Почніть зі створення нового проєкту TanStack Start, дотримуючись інструкції Створення нового проєкту на сайті TanStack Start.

    2. Встановіть пакети Intlayer

      Встановіть необхідні пакети, використовуючи обраний менеджер пакетів:

      bash
      npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer init

      • intlayer

        Основний пакет, який надає інструменти інтернаціоналізації для керування конфігурацією, перекладу, оголошення контенту, транспіляції та команд CLI.

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

      • vite-intlayer Містить плагін Vite для інтеграції Intlayer з бандлером Vite, а також middleware для визначення пріоритетної локалі користувача, керування 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 { 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(),    tanstackStart({      router: {        routeFileIgnorePattern:          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",      },    }),    viteReact(),  ],});export default config;
      Плагін Vite intlayer() використовується для інтеграції Intlayer з Vite. Він забезпечує побудову файлів декларацій контенту та відстежує їх у режимі розробки. Він визначає змінні середовища Intlayer у Vite-застосунку. Додатково він надає аліаси для оптимізації продуктивності.

    5. Створіть кореневий Layout

      Налаштуйте кореневий layout для підтримки інтернаціоналізації, використовуючи useParams для визначення поточної локалі та встановлення атрибутів lang і dir на тезі html.

      src/routes/__root.tsx
      import {  createRootRouteWithContext,  HeadContent,  Scripts,} from "@tanstack/react-router";import { defaultLocale, getHTMLTextDir } from "intlayer";import { type ReactNode } from "react";import { IntlayerProvider } from "react-intlayer";import { Route as LocaleRoute } from "./{-$locale}/route";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>  );}
      Якщо ви хочете використовувати свій вміст в атрибуті типу 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)}" />

    6. Створіть Locale Layout

      Створіть layout, який обробляє префікс локалі та виконує валідацію.

      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 на ваших сторінках

      Отримуйте доступ до словників контенту по всьому застосунку:

      Локалізована головна сторінка

      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,});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>  );}
      Щоб дізнатися більше про хук 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
      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.
      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, intlayerProxy } from "vite-intlayer";export default defineConfig({  plugins: [    intlayerProxy(), // Проксі слід розміщувати перед сервером, якщо ви використовуєте Nitro    nitro(),    intlayer(),    tanstackStart({      router: {        routeFileIgnorePattern:          ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5)$",      },    }),    viteReact(),  ],});

    13. Інтернаціоналізуйте свої метадані

      Ви також можете використовувати хук getIntlayer, щоб отримувати ваші словники контенту по всьому застосунку:

      src/routes/{-$locale}/index.tsx
      import { createFileRoute } from "@tanstack/react-router";import { getIntlayer } from "intlayer";export const Route = createFileRoute("/{-$locale}/")({  component: RouteComponent,  head: ({ params }) => {    const { locale } = params;    const path = "/"; // The path for this route    const metaContent = getIntlayer("app", locale);    return {      links: [        // Canonical link: Points to the current localized page        { rel: "canonical", href: getLocalizedUrl(path, locale) },        // Hreflang: Tell Google about all localized versions        ...localeMap(({ locale: mapLocale }) => ({          rel: "alternate",          hrefLang: mapLocale,          href: getLocalizedUrl(path, mapLocale),        })),        // x-default: For users in unmatched languages        // Define the default fallback locale (usually your primary language)        {          rel: "alternate",          hrefLang: "x-default",          href: getLocalizedUrl(path, defaultLocale),        },      ],      meta: [        { title: metaContent.title },        { name: "description", content: metaContent.meta.description },      ],    };  },});

    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),  });  // Отримати певний контент за допомогою getIntlayer()  const content = getIntlayer("app", locale);  return { locale, content };});

    15. Керування сторінками «Не знайдено»

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

      Розуміння обробки 404 у TanStack Router з префіксами локалі

      У TanStack Router обробка сторінок 404 для локалізованих маршрутів вимагає багаторівневого підходу:

      1. Виділений маршрут 404: спеціальний маршрут для відображення інтерфейсу сторінки 404
      2. Валідація на рівні маршруту: перевіряє префікси локалі та перенаправляє некоректні на 404
      3. Catch-all route: Перехоплює будь-які невідповідні шляхи в межах сегмента локалі
      src/routes/{-$locale}/404.tsx
      import { createFileRoute } from "@tanstack/react-router";// Це створює спеціальний маршрут /[locale]/404// Використовується як прямий маршрут і імпортується як компонент в інших файлахexport const Route = createFileRoute("/{-$locale}/404")({  component: NotFoundComponent,});// Експортується окремо, щоб його можна було повторно використовувати в notFoundComponent та catch-all маршрутахexport function NotFoundComponent() {  return (    <div>      <h1>404</h1>    </div>  );}
      src/routes/{-$locale}/route.tsx
      import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";import { validatePrefix } from "intlayer";import { NotFoundComponent } from "./404";export const Route = createFileRoute("/{-$locale}")({  // beforeLoad виконується перед відображенням маршруту (як на сервері, так і на клієнті)  // Це ідеальне місце для валідації префіксу локалі  beforeLoad: ({ params }) => {    const localeParam = params.locale;    // validatePrefix перевіряє, чи дійсна локаль згідно з вашою конфігурацією intlayer    const { isValid, localePrefix } = validatePrefix(localeParam);    if (!isValid) {      // Неприпустимий префікс локалі - перенаправити на сторінку 404 з дійсним префіксом локалі      throw redirect({        to: "/{-$locale}/404",        params: { locale: localePrefix },      });    }  },  component: Outlet,  // notFoundComponent викликається, коли дочірній маршрут не існує  // наприклад, /en/non-existent-page спричиняє це в межах layout для /en  notFoundComponent: NotFoundComponent,});
      src/routes/{-$locale}/$.tsx
      import { createFileRoute } from "@tanstack/react-router";import { NotFoundComponent } from "./404";// Маркер $ (splat/catch-all) маршрут відповідає будь-якому шляху, який не відповідає іншим маршрутам// наприклад, /en/some/deeply/nested/invalid/path// Це гарантує, що ВСІ невідповідні шляхи всередині локалі показуватимуть сторінку 404// Без цього, невідповідні глибокі шляхи можуть показувати порожню сторінку або викликати помилкуexport const Route = createFileRoute("/{-$locale}/$")({  component: NotFoundComponent,});

    16. Налаштування TypeScript

      Intlayer використовує module augmentation, щоб отримати переваги TypeScript і зміцнити ваш codebase.

      Переконайтеся, що ваша конфігурація TypeScript включає автогенеровані типи:

      tsconfig.json
      {  // ... ваші наявні конфігурації  include: [    // ... ваші наявні includes    ".intlayer/**/*.ts", // Включає автогенеровані типи  ],}

    17. Витягніть вміст ваших компонентів

      Необов'язково

      Якщо у вас є існуюча кодова база, перетворення тисяч файлів може зайняти багато часу.

      Щоб спростити цей процес, Intlayer пропонує компілятор / екстрактор для перетворення ваших компонентів і витягування вмісту.

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

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

const config: IntlayerConfig = {
  // ... Інша частина вашої конфігурації
  compiler: {
    /**
     * Вказує, чи повинен бути включений компілятор.
     */
    enabled: true,

    /**
     * Визначає шлях до вихідних файлів
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Вказує, чи повинні компоненти зберігатися після перетворення. Таким чином, компілятор можна запустити лише один раз для перетворення програми, а потім видалити.
     */
    saveComponents: false,

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

export default config;

      Запустіть екстрактор для перетворення компонентів і витягування вмісту

      bash
      npx intlayer extract

    Налаштування Git

    Рекомендується ігнорувати файли, згенеровані Intlayer. Це дозволить уникнути їх коміту в ваш Git-репозиторій.

    Для цього ви можете додати наступні інструкції до файлу .gitignore:

    .gitignore
    # Ігнорувати файли, згенеровані Intlayer.intlayer

    Розширення VS Code

    Щоб покращити досвід розробки з Intlayer, ви можете встановити офіційне Intlayer VS Code Extension.

    Встановити з VS Code Marketplace

    Це розширення надає:

    • Автозаповнення для ключів перекладу.
    • Виявлення помилок у реальному часі для відсутніх перекладів.
    • Вбудовані попередні перегляди перекладеного вмісту.
    • Швидкі дії для простого створення та оновлення перекладів.

    Для детальнішої інформації про використання розширення зверніться до документації Intlayer VS Code Extension.

    Рухатися далі

    Щоб піти далі, ви можете реалізувати візуальний редактор або винести свій вміст у зовнішню систему, використовуючи CMS.

    Посилання на документацію

    Compiler
    Tanstack Start Solid