Переведите ваш сайт на Tanstack Start с Solid.js, используя Intlayer

Содержание

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

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

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

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

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

1. 1

   Создание проекта

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

2. 2

   Установка пакетов Intlayer

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

   bash

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

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

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

   npx intlayer init --interactive
   

   флаг --interactive не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.

   Эта команда определит вашу среду и установит необходимые пакеты. Например:

   bash

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

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

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

   npm install intlayer solid-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

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

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

3. 3

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

   Архитектура

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

   bash

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

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

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

   .
   ├── src
   │   ├── components
   │   │   ├── Header.content.ts
   │   │   ├── Header.tsx
   │   │   ├── LocaleSwitcher.content.ts
   │   │   ├── LocaleSwitcher.tsx
   │   │   └── LocalizedLink.tsx
   │   ├── 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, имена куки, местоположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Полный список доступных параметров см. в документации по конфигурации.

   документации по конфигурации
4. 4

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

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

   vite.config.ts

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

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

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

   import { intlayer } from "vite-intlayer";
   import { defineConfig } from "vite";
   import { devtools } from "@tanstack/devtools-vite";
   import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
   import solidPlugin from "vite-plugin-solid";
   
   export default defineConfig({
     plugins: [
       devtools(),
       tanstackStart({
         router: {
           routeFileIgnorePattern:
             ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
         },
       }),
       solidPlugin({ ssr: true }),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

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

5. 5

   Создание корневого макета

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

   src/routes/__root.tsx

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

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

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

   import {
     HeadContent,
     Scripts,
     createRootRouteWithContext,
     getRouteApi,
   } from "@tanstack/solid-router";
   import { HydrationScript } from "solid-js/web";
   import { Suspense, type ParentComponent } from "solid-js";
   import { IntlayerProvider } from "solid-intlayer";
   import { defaultLocale, getHTMLTextDir } from "intlayer";
   
   const localeRoute = getRouteApi("/{-$locale}");
   
   export const Route = createRootRouteWithContext()({
     shellComponent: RootComponent,
   });
   
   const RootComponent: ParentComponent = (props) => {
     const params = localeRoute.useParams();
     const locale = params()?.locale ?? defaultLocale;
   
     return (
       <html dir={getHTMLTextDir(locale)} lang={locale}>
         <head>
           <HydrationScript />
           <HeadContent />
         </head>
         <body>
           <IntlayerProvider locale={locale}>
             <Suspense>{props.children}</Suspense>
           </IntlayerProvider>
           <Scripts />
         </body>
       </html>
     );
   };
   

6. 6

   Создание макета локали

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

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

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

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

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

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

   import { createFileRoute, Outlet, redirect } from "@tanstack/solid-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 },
           replace: true,
         });
       }
     },
     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/LocalizedLink.tsx

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

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

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

   import { Link, type LinkProps } from "@tanstack/solid-router";
   import { getPrefix } from "intlayer";
   import { useLocale } from "solid-intlayer";
   import type { JSX } from "solid-js";
   
   export const LOCALE_ROUTE = "{-$locale}" as const;
   
   export type RemoveLocaleParam<TVal> = TVal extends string
     ? RemoveLocaleFromString<TVal>
     : TVal;
   
   export type To = RemoveLocaleParam<LinkProps["to"]>;
   
   type CollapseDoubleSlashes<TString extends string> =
     TString extends `${infer THead}//${infer TTail}`
       ? CollapseDoubleSlashes<`${THead}/${TTail}`>
       : TString;
   
   export type LocalizedLinkProps = Omit<LinkProps, "to"> & {
     to?: To;
   } & JSX.AnchorHTMLAttributes<HTMLAnchorElement>;
   
   type RemoveAll<
     TString extends string,
     TSub extends string,
   > = TString extends `${infer THead}${TSub}${infer TTail}`
     ? RemoveAll<`${THead}${TTail}`, TSub>
     : TString;
   
   type RemoveLocaleFromString<TString extends string> = CollapseDoubleSlashes<
     RemoveAll<TString, typeof LOCALE_ROUTE>
   >;
   
   export const LocalizedLink = (props: LocalizedLinkProps) => {
     const { locale } = useLocale();
   
     return (
       <Link
         {...props}
         params={{
           locale: getPrefix(locale()).localePrefix,
           ...(typeof props.params === "object" ? props.params : {}),
         }}
         to={`/${LOCALE_ROUTE}${props.to ?? ""}` as LinkProps["to"]}
       />
     );
   };
   

   Этот компонент преследует две цели:

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

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

   src/hooks/useLocalizedNavigate.tsx

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

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

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

   import { useNavigate } from "@tanstack/solid-router";
   import { getLocalizedUrl } from "intlayer";
   import { useLocale } from "solid-intlayer";
   
   export const useLocalizedNavigate = () => {
     const navigate = useNavigate();
     const { locale } = useLocale();
   
     const localizedNavigate = (to: string) => {
       const localizedTo = getLocalizedUrl(to, locale());
       return navigate({ to: localizedTo });
     };
   
     return localizedNavigate;
   };
   

9. 9

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

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

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

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

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

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

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

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

   import { createFileRoute } from "@tanstack/solid-router";
   import { useIntlayer } from "solid-intlayer";
   import { LocalizedLink } from "@/components/LocalizedLink";
   
   export const Route = createFileRoute("/{-$locale}/")({
     component: RouteComponent,
   });
   
   function RouteComponent() {
     const content = useIntlayer("index-page");
   
     return (
       <main>
         <h1>{content.heroTitle}</h1>
         <p>{content.heroDesc}</p>
         <div>
           <LocalizedLink to="/">{content.navHome}</LocalizedLink>
           <LocalizedLink to="/about">{content.navAbout}</LocalizedLink>
         </div>
       </main>
     );
   }
   

   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)} />
   

   В Solid useIntlayer возвращает реактивный контент (например, content). Вы можете обращаться к его свойствам напрямую.

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

   Документация хука useIntlayer | solid-intlayer
10. 10

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

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

    src/components/LocaleSwitcher.tsx

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

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

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

    import { useLocation } from "@tanstack/solid-router";
    import { getLocaleName, getPathWithoutLocale, getPrefix } from "intlayer";
    import { For } from "solid-js";
    import { useIntlayer, useLocale } from "solid-intlayer";
    import { LocalizedLink, type To } from "./LocalizedLink";
    
    export const LocaleSwitcher = () => {
      const content = useIntlayer("locale-switcher");
      const location = useLocation();
    
      const { availableLocales, locale, setLocale } = useLocale();
    
      const pathWithoutLocale = () => getPathWithoutLocale(location().pathname);
    
      return (
        <div class="flex flex-row gap-2">
          <For each={availableLocales}>
            {(localeEl) => (
              <LocalizedLink
                aria-current={localeEl === locale() ? "page" : undefined}
                onClick={() => setLocale(localeEl)}
                params={{ locale: getPrefix(localeEl).localePrefix }}
                to={pathWithoutLocale() as To}
              >
                {getLocaleName(localeEl)}
              </LocalizedLink>
            )}
          </For>
        </div>
      );
    };
    
    export default LocaleSwitcher;
    

    В Solid locale из useLocale - это аксессор сигнала. Используйте locale() (со скобками) для реактивного чтения текущего значения.

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

    Документация хука useLocale | solid-intlayer
11. 11

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

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

    src/routes/__root.tsx

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

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

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

    const RootComponent: ParentComponent = (props) => {
      const params = localeRoute.useParams();
      const locale = params()?.locale ?? defaultLocale;
    
      return (
        <html dir={getHTMLTextDir(locale)} lang={locale}>
          {/* ... */}
        </html>
      );
    };
    

12. 12

    Добавление промежуточного ПО

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

    Обратите внимание, что для использования intlayerProxy в режиме production вам необходимо перенести пакет vite-intlayer из devDependencies в dependencies.

    Начиная с Intlayer v9, intlayerProxy() встроен непосредственно в плагин intlayer() и включен по умолчанию через параметр routing.enableProxy (true по умолчанию). Регистрация его отдельно, как показано ниже, теперь опциональна: она сохранена для обратной совместимости и для конфигураций, которым нужно контролировать порядок плагинов. Установите routing.enableProxy: false, чтобы отключить эту функцию. См. примечания к выпуску v9.

    примечания к выпуску v9

    vite.config.ts

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

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

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

    import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
    import solid from "vite-plugin-solid";
    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)$",
          },
        }),
        solid(),
      ],
    });
    

13. 13

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

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

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

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

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

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

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

    import { createFileRoute } from "@tanstack/solid-router";
    import {
      defaultLocale,
      getIntlayer,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: ({ params }) => {
        const { locale = defaultLocale } = 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 },
          ],
        };
      },
    });
    

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

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

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

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

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

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

    import { createFileRoute } from "@tanstack/solid-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      head: async ({ params }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // The path for this route
    
        const metaContent = await getIntlayerAsync("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 },
          ],
        };
      },
    });
    

    Если head читает несколько словарей, разрешайте их через Promise.all: ожидание каждого getIntlayerAsync отдельной строкой выстраивает запросы в цепочку вместо параллельного выполнения.

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

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

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

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

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

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

    import { createFileRoute } from "@tanstack/solid-router";
    import {
      defaultLocale,
      getIntlayerAsync,
      getLocalizedUrl,
      localeMap,
    } from "intlayer";
    
    export const Route = createFileRoute("/{-$locale}/")({
      component: RouteComponent,
      // Resolved in parallel with the other matched routes, off the head critical path
      loader: async ({ params }) => {
        const { locale = defaultLocale } = params;
    
        return { metaContent: await getIntlayerAsync("app", locale) };
      },
      // The dictionary never changes for a given locale: resolve the chunk once
      staleTime: Infinity,
      head: ({ params, loaderData }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // The path for this route
    
        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: loaderData?.metaContent.title },
            {
              name: "description",
              content: loaderData?.metaContent.meta.description,
            },
          ],
        };
      },
    });
    

    head может быть вызван до того, как загрузчик завершится, поэтому loaderData типизирован как возможно undefined. Сохраните опциональную цепочку либо возвращайте запасной заголовок.

    Вы сохраняете пер-локальный чанк, не оплачивая его стоимость на критическом пути head. Платой становится DX: контент приходится явно прокидывать из загрузчика в head через loaderData.

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

    Показать все данные таблицы

    Показать все данные таблицы

    Открыть таблицу в модальном окне для четкого просмотра всех данных

    	Статическое разрешение	Динамическое разрешение	Кэшированное динамическое разрешение
    API	getIntlayer	getIntlayerAsync (v9.4+)	getIntlayerAsync в loader (v9.4+)
    Сигнатура head	синхронная	async	синхронная, читает loaderData
    Отправляемые локали	все объявленные локали	только запрошенная локаль	только запрошенная локаль
    Клиентские переходы	разрешать нечего	выполняется заново при каждом совпадении	отдаётся из кэша роутера
    DX	самый простой	один await	контент прокидывается через loaderData

14. 13

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

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

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

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

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

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

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

    import { createServerFn } from "@tanstack/solid-start";
    import {
      getRequestHeader,
      getRequestHeaders,
    } from "@tanstack/solid-start/server";
    import { getCookie, getIntlayer, getLocale } from "intlayer";
    
    export const getLocaleServer = createServerFn().handler(async () => {
      const locale = await getLocale({
        // Получение куки из запроса (по умолчанию: '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. 14

    Управление страницами 404

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

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

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

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

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

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

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

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

    import { createFileRoute } from "@tanstack/solid-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/solid-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 вызывает это внутри макета /en
      notFoundComponent: NotFoundComponent,
    });
    

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

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

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

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

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

16. 15

    Извлечение контента из ваших компонентов

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

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

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

    компилятор

    экстрактор

    Для настройки добавьте раздел compiler в ваш файл intlayer.config.ts:

    intlayer.config.ts

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

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

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

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Остальная часть конфига
      compiler: {
        /**
         * Указывает, должен ли компилятор быть включен.
         */
        enabled: true,
    
        /**
         * Определяет путь к выходным файлам
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Указывает, должны ли компоненты сохраняться после трансформации.
         *
         * - Если `true`, компилятор перезапишет файл компонента на диске. Таким образом, трансформация станет постоянной, и компилятор пропустит ее при следующем запуске. Таким образом, компилятор может трансформировать приложение, а затем его можно удалить.
         *
         * - Если `false`, компилятор будет внедрять вызов функции `useIntlayer()` в код только в выходных файлах сборки, оставляя основную базу кода нетронутой. Трансформация будет выполняться только в памяти.
         */
        saveComponents: false,
    
        /**
         * Префикс ключей словаря
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Команда extractBabel-компилятор

    Запустите экстрактор для трансформации ваших компонентов и извлечения контента:

    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 { intlayer, intlayerCompiler } from "vite-intlayer";
    import { defineConfig } from "vite";
    import { devtools } from "@tanstack/devtools-vite";
    import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
    import solidPlugin from "vite-plugin-solid";
    
    export default defineConfig({
      plugins: [
        devtools(),
        tanstackStart({
          router: {
            routeFileIgnorePattern:
              ".content.(ts|tsx|js|mjs|cjs|jsx|json|jsonc|json5|md|mdx|yaml|yml)$",
          },
        }),
        solidPlugin({ ssr: true }),
        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 { localeMap, 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/solid-router";
    import { generateSitemap } from "intlayer";
    
    const SITE_URL = "http://localhost:3000";
    
    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.

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

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

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

Что дальше?

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

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

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