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

Содержание

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

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

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

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

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

1. 1

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

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

2. 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. 3

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

   Архитектура

   В этой архитектуре все локализованные маршруты вложены в сегмент маршрута {-$locale}. Такой подход гарантирует, что каждый язык имеет выделенный URL-адрес, обеспечивая при этом автоматическое добавление префикса локали, валидацию и SEO-оптимизацию.

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   .
   ├── src
   │   ├── components
   │   │   ├── Header.tsx
   │   │   ├── locale-switcher.content.ts
   │   │   ├── locale-switcher.tsx
   │   │   └── localized-link.tsx
   │   ├── hooks
   │   │   ├── useI18nHTMLAttributes.tsx
   │   │   └── useLocalizedNavigate.ts
   │   ├── routes
   │   │   ├── {-$locale}
   │   │   │   ├── 404.content.ts
   │   │   │   ├── 404.tsx
   │   │   │   ├── about.content.ts
   │   │   │   ├── about.tsx
   │   │   │   ├── index.content.tsx
   │   │   │   ├── index.tsx
   │   │   │   └── route.tsx             # Locale layout & prefix validation
   │   │   ├── __root.tsx                # Root route with IntlayerProvider
   │   │   └── sitemap[.]xml.ts
   │   ├── router.tsx
   │   └── styles.css
   ├── intlayer.config.ts
   ├── package.json
   ├── tsconfig.json
   └── vite.config.ts
   

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

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

   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. 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. 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. 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. 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. 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. 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 и т. д., вы можете использовать значение функции, например:

   tsx

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   <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. 9

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

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

    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. 10

    Управление атрибутами 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. 11

    Добавить 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. 12

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

    Статическое разрешениеДинамическое разрешениеРазрешение с кешированием

    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. 13

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

    Вы можете захотеть получить доступ к текущему языковому стандарту из ваших серверных действий или конечных точек 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. 14

    Управление страницами "не найдено"

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

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

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

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

    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/несуществующая-страница запускает это в макете /en
      notFoundComponent: NotFoundComponent,
    });
    

    src/routes/{-$locale}/$.tsx

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { createFileRoute } from "@tanstack/react-router";
    
    import { NotFoundComponent } from "./404";
    
    // Маршрут $ (splat/catch-all) соответствует любому пути, который не соответствует другим маршрутам
    // например, /en/какой-то/глубоко/вложенный/недействительный/путь
    // Это гарантирует, что ВСЕ несоответствующие пути в локали показывают страницу 404
    // Без этого несоответствующие глубокие пути могут показать пустую страницу или ошибку
    export const Route = createFileRoute("/{-$locale}/$")({
      component: NotFoundComponent,
    });
    

16. 15

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

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

    isOptional={true}>

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

    Чтобы упростить этот процесс, 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;
    

    Команда извлеченияКомпилятор Babel

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

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npx intlayer extract
    

    intlayer >= 9intlayer < 9

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    Обновите ваш vite.config.ts, чтобы включить плагин intlayerCompiler:

    vite.config.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    Соберите приложение, чтобы преобразовать ваши компоненты и извлечь контент

    bash

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    npm run build # Или npm run dev
    

17. 16

    Генерация карты сайта (Sitemap)

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

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

    Создаваемая Intlayer карта сайта поддерживает пространство имен xhtml:link (Hreflang XML Extensions). В отличие от стандартных генераторов карт сайта, которые просто перечисляют прямые URL-адреса, Intlayer автоматически создает необходимые двусторонние связи между всеми языковыми версиями страницы (например, /about, /about?lang=fr и /about?lang=es). Это гарантирует, что поисковые системы будут правильно индексировать и показывать нужную языковую версию соответствующей аудитории.

    Чтобы использовать его, вам сначала нужно настроить ваш файл vite.config.ts, чтобы включить предварительный рендеринг (pre-rendering) для ваших локализованных маршрутов и отключить генерацию карты сайта по умолчанию в TanStack Start.

    vite.config.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { localeFlatMap } from "intlayer";
    // ... другие импорты
    
    export const pathList = ["", "/about", "/404"];
    
    const localizedPages = localeFlatMap(({ urlPrefix }) =>
      pathList.map((path) => ({
        path: `${urlPrefix}${path}`,
        prerender: {
          enabled: true,
        },
      }))
    );
    
    export default defineConfig({
      plugins: [
        // ... другие плагины
        tanstackStart({
          // ... другие настройки
          sitemap: {
            enabled: false,
          },
          prerender: {
            enabled: true,
            crawlLinks: false,
            concurrency: 10,
          },
          pages: localizedPages,
        }),
      ],
    });
    

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

    src/routes/sitemap[.]xml.ts

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

    import { createFileRoute } from "@tanstack/react-router";
    import { generateSitemap } from "intlayer";
    
    export const Route = createFileRoute("/sitemap.xml")({
      server: {
        handlers: {
          GET: async () => {
            const sitemap = generateSitemap(
              [
                { path: "/", changefreq: "daily", priority: 1.0 },
                { path: "/about", changefreq: "monthly", priority: 0.8 },
              ],
              { siteUrl: "https://example.com" }
            );
    
            return new Response(sitemap, {
              headers: { "Content-Type": "application/xml" },
            });
          },
        },
      },
    });
    

18. 17

    Настройка TypeScript

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

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

    tsconfig.json

    Копировать содержимое

    Копировать код

    Копировать код в буфер обмена

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

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

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

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

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

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

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

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

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

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

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

Дальше

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

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

• Документация Intlayer
• Документация Tanstack Start
• хук useIntlayer
• хук useLocale
• Объявление контента
• Конфигурация

Часто задаваемые вопросы