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

Зміст

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

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

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

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

ВідеоКодДемо

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-tanstack-start-template.vercel.app

Open embedded page in fullscreen

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

1. 1

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

   Почніть зі створення нового проєкту TanStack Start, дотримуючись інструкції Створення нового проєкту на сайті 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, а також middleware для визначення пріоритетної локалі користувача, керування cookie та обробки перенаправлень URL.

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

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

   Налаштуйте кореневий layout для підтримки інтернаціоналізації, використовуючи 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

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

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

   Щоб дізнатися більше про hook 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>
      );
    };
    

    Щоб дізнатися більше про hook 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 залишається синхронним, і нічого не очікується, але весь багатомовний словник витягується в шматок маршруту, надісланий браузеру.

    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: [
            // Канонічне посилання: вказує на поточну локалізовану сторінку
            { 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, але плагін побудови вказує його на шматок для кожної локалі в .intlayer/dynamic_dictionaries/ замість об'єднаного словника. Сторінка тому поставляється тільки локаллю, яку вона відображає. Оскільки цей шматок завантажується за запитом, 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: [
            // Канонічне посилання: вказує на поточну локалізовану сторінку
            { 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. Завантажувачі відповідних маршрутів запускаються паралельно, а staleTime: Infinity повідомляє TanStack Router, що результат ніколи не стає застарілим, тому шматок для кожної локалі розв'язується один раз і служить з кешу маршрутизатора після цього, залишаючи 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) };
      },
      // Словник ніколи не змінюється для заданої локалі: розв'яжіть шматок один раз
      staleTime: Infinity,
      head: ({ params, loaderData }) => {
        const { locale = defaultLocale } = params;
        const path = "/"; // Шлях для цього маршруту
    
        return {
          links: [
            // Канонічне посилання: вказує на поточну локалізовану сторінку
            { 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 може бути викликаний до того, як завантажувач розв'яжеться, тому loaderData набирає тип як можливо undefined. Зберігайте необов'язковий ланцюг, або повертайте резервний заголовок.

    Ви зберігаєте шматок для кожної локалі без сплати його вартості на критичному шляху head. Ціна - досвід розробника: вміст має бути явно потокований із завантажувача до 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 endpoints. Ви можете це зробити, використовуючи помічник 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 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. 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
    

    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

    Pre-render & Generate Sitemap

    Intlayer має вбудований генератор sitemap, який допомагає легко створити sitemap для вашої програми. Він обробляє локалізовані маршрути та додає необхідні метадані для пошукових систем.

    Карта сайту, згенерована Intlayer, підтримує простір імен xhtml:link (Hreflang XML Extensions). На відміну від генераторів карт сайту за замовчуванням, які лише перелічують необроблені URL-адреси, Intlayer автоматично створює необхідні двосторонні посилання між усіма мовними версіями сторінки (наприклад, /about, /about?lang=fr та /about?lang=es). Це забезпечує правильне індексування пошуковими системами та подачу правильної мовної версії відповідній аудиторії.

    Щоб використовувати це, спочатку потрібно налаштувати ваш vite.config.ts для увімкнення попередньої обробки локалізованих маршрутів і вимкнення генерування карти сайту 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";
    
    const SITE_URL = (
      import.meta.env.VITE_SITE_URL ?? "http://localhost:3000"
    ).replace(/\/$/, "");
    
    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: SITE_URL }
            );
    
            return new Response(sitemap, {
              headers: { "Content-Type": "application/xml" },
            });
          },
        },
      },
    });
    

18. 17

    Налаштувати TypeScript

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

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

    tsconfig.json

    Копіювати вміст

    Копіювати код

    Скопіюйте код у буфер обміну

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

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

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

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

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

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

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

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

Це розширення забезпечує:

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

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

Йти далі

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

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

• Документація Intlayer
• Документація Tanstack Start
• useIntlayer hook
• useLocale hook
• Content Declaration
• Configuration

Часто задавані запитання