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

Дивіться Шаблон програми на GitHub.

Зміст

Що таке Intlayer?

Intlayer, це інноваційна бібліотека інтернаціоналізації (i18n) з відкритим вихідним кодом, розроблена для спрощення багатомовної підтримки в сучасних вебдодатках. Intlayer безшовно інтегрується з останнім фреймворком Next.js 16, включаючи його потужний App Router. Він оптимізований для роботи з Server Components для ефективного рендерингу та повністю сумісний з Turbopack.

За допомогою Intlayer ви можете:

• Легко керувати перекладами, використовуючи декларативні словники на рівні компонентів.
• Динамічно локалізувати метадані, маршрути та контент.
• Отримувати доступ до перекладів як у клієнтських, так і в серверних компонентах.
• Забезпечити підтримку TypeScript з автогенерованими типами, покращуючи автодоповнення та виявлення помилок.
• Скористатися розширеними функціями, такими як динамічне визначення та перемикання локалі.

Intlayer сумісний з Next.js 12, 13, 14 та 16. Якщо ви використовуєте Next.js Page Router, ви можете звернутися до цього посібника. Роутинг на основі локалі корисний для SEO, розміру бандла та продуктивності. Якщо він вам не потрібен, ви можете звернутися до цього посібника. Для Next.js 12, 13, 14 з App Router зверніться до цього посібника.

Покроковий посібник із налаштування Intlayer у додатку Next.js

Крок 1: Встановлення залежностей

Встановіть необхідні пакети за допомогою npm:

npm install intlayer next-intlayernpx intlayer init

• intlayer

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

• next-intlayer

  Пакет, який інтегрує Intlayer з Next.js. Він надає провайдери контексту та хуки для інтернаціоналізації в Next.js. Крім того, він включає плагін Next.js для інтеграції Intlayer з Webpack або Turbopack, а також проксі для визначення пріоритетної локалі користувача, керування файлами cookie та обробки перенаправлення URL.

Крок 2: Налаштуйте свій проєкт

Ось остаточна структура, яку ми створимо:

.├── src│   ├── app│   │   ├── [locale]│   │   │   ├── layout.tsx            # Локальний макет для провайдера Intlayer│   │   │   ├── page.content.ts│   │   │   └── page.tsx│   │   └── layout.tsx                # Кореневий макет для стилів та глобальних провайдерів│   ├── components│   │   ├── client-component-example.content.ts│   │   ├── ClientComponentExample.tsx│   │   ├── LocaleSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   ├── server-component-example.content.ts│   │   └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

Якщо ви не хочете використовувати роутинг на основі локалі, intlayer можна використовувати як простий провайдер / хук. Дивіться цей посібник для отримання детальнішої інформації.

Створіть файл конфігурації для налаштування мов вашого додатка:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Ваші інші локалі
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Через цей файл конфігурації ви можете налаштувати локалізовані URL-адреси, перенаправлення через проксі, назви файлів cookie, розташування та розширення декларацій вашого контенту, вимкнути логи Intlayer у консолі та багато іншого. Повний список доступних параметрів можна знайти в документації з конфігурації.

Крок 3: Інтегруйте Intlayer у конфігурацію Next.js

Налаштуйте Next.js для використання Intlayer:

import type { NextConfig } from "next";
import { withIntlayer } from "next-intlayer/server";

const nextConfig: NextConfig = {
  /* параметри конфігурації тут */
};

export default withIntlayer(nextConfig);

Плагін Next.js withIntlayer() використовується для інтеграції Intlayer з Next.js. Він забезпечує створення файлів декларації контенту та відстежує їх у режимі розробки. Він визначає змінні оточення Intlayer у середовищах Webpack або Turbopack. Крім того, він надає аліаси для оптимізації продуктивності та забезпечує сумісність із серверними компонентами.

Функція withIntlayer() повертає Promise. Вона дозволяє підготувати словники Intlayer перед початком збірки. Якщо ви хочете використовувати її з іншими плагінами, ви можете застосувати await. Приклад:

ts

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

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

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

const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

Якщо ви хочете використовувати її синхронно, ви можете скористатися функцією withIntlayerSync(). Приклад:

ts

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

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

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

const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

Intlayer автоматично визначає, чи використовує ваш проєкт webpack чи Turbopack, на основі прапорів командного рядка --webpack, --turbo або --turbopack, а також вашої поточної версії Next.js.

Починаючи з next>=16, якщо ви використовуєте Rspack, ви повинні явно змусити Intlayer використовувати конфігурацію webpack, вимкнувши Turbopack:

ts

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

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

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

withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

Крок 4: Визначте динамічні маршрути локалей

Видаліть усе з RootLayout і замініть його наступним кодом:

import type { PropsWithChildren, FC } from "react";
import "./globals.css";

const RootLayout: FC<PropsWithChildren> = ({ children }) => (
  // Ви все ще можете обгорнути дочірні елементи іншими провайдерами, наприклад `next-themes`, `react-query`, `framer-motion` тощо.
  <>{children}</>
);

export default RootLayout;

Залишення компонента RootLayout порожнім дозволяє встановити атрибути lang та dir для тегу <html>.

Щоб реалізувати динамічну маршрутизацію, вкажіть шлях для локалі, додавши новий макет у вашу директорію [locale]:

import { type NextLayoutIntlayer, IntlayerClientProvider } from "next-intlayer";
import { Inter } from "next/font/google";
import { getHTMLTextDir } from "intlayer";

const inter = Inter({ subsets: ["latin"] });

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  const { locale } = await params;
  return (
    <html lang={locale} dir={getHTMLTextDir(locale)}>
      <body className={inter.className}>
        <IntlayerClientProvider locale={locale}>
          {children}
        </IntlayerClientProvider>
      </body>
    </html>
  );
};

export default LocaleLayout;

Сегмент шляху [locale] використовується для визначення локалі. Приклад: /en-US/about посилатиметься на en-US, а /fr/about, на fr.

На цьому етапі ви зіткнетеся з помилкою: Error: Missing <html> and <body> tags in the root layout.. Це очікувано, оскільки файл /app/page.tsx більше не використовується і його можна видалити. Замість цього сегмент шляху [locale] активує сторінку /app/[locale]/page.tsx. Отже, сторінки будуть доступні за такими шляхами, як /en, /fr, /es у вашому браузері. Щоб встановити локаль за замовчуванням як кореневу сторінку, зверніться до налаштування proxy на кроці 7.

Потім реалізуйте функцію generateStaticParams у макеті вашого додатка.

export { generateStaticParams } from "next-intlayer"; // Рядок для вставки

const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
  /*... Решта коду*/
};

export default LocaleLayout;

generateStaticParams гарантує, що ваш додаток попередньо збирає необхідні сторінки для всіх локалей, зменшуючи обчислення під час виконання та покращуючи взаємодію з користувачем. Для отримання додаткової інформації зверніться до документації Next.js щодо generateStaticParams.

Intlayer працює з export const dynamic = 'force-static';, щоб забезпечити попередню збірку сторінок для всіх локалей.

Крок 5: Оголосіть свій контент

Створюйте декларації контенту та керуйте ними для зберігання перекладів:

import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    getStarted: {
      main: t({
        en: "Get started by editing",
        fr: "Commencez par éditer",
        es: "Comience por editar",
      }),
      pageLink: "src/app/page.tsx",
    },
  },
} satisfies Dictionary;

export default pageContent;

Ваші декларації контенту можуть бути визначені будь-де у вашому додатку, якщо вони включені в директорію contentDir (за замовчуванням, ./src). І вони повинні відповідати розширенню файлу декларації контенту (за замовчуванням, .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Для отримання додаткової інформації зверніться до документації з декларації контенту.

Крок 6: Використовуйте контент у своєму коді

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

import type { FC } from "react";
import { ClientComponentExample } from "@components/ClientComponentExample";
import { ServerComponentExample } from "@components/ServerComponentExample";
import { type NextPageIntlayer } from "next-intlayer";
import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";

const PageContent: FC = () => {
  const content = useIntlayer("page");

  return (
    <>
      <p>{content.getStarted.main}</p>
      <code>{content.getStarted.pageLink}</code>
    </>
  );
};

const Page: NextPageIntlayer = async ({ params }) => {
  const { locale } = await params;

  return (
    <IntlayerServerProvider locale={locale}>
      <PageContent />
      <ServerComponentExample />

      <ClientComponentExample />
    </IntlayerServerProvider>
  );
};

export default Page;

• IntlayerClientProvider використовується для надання локалі клієнтським компонентам. Його можна розмістити в будь-якому батьківському компоненті, включаючи макет. Однак рекомендується розміщувати його в макеті, оскільки Next.js спільно використовує код макета між сторінками, що робить його ефективнішим. Використовуючи IntlayerClientProvider у макеті, ви уникаєте повторної ініціалізації для кожної сторінки, підвищуючи продуктивність і підтримуючи послідовний контекст локалізації у всьому додатку.

• IntlayerServerProvider використовується для надання локалі серверним дочірнім компонентам. Його не можна встановити в макеті.

  Макет і сторінка не можуть ділити загальний серверний контекст, оскільки система серверного контексту базується на сховищі даних для кожного запиту (через механізм кешування React), що призводить до повторного створення кожного "контексту" для різних сегментів додатка. Розміщення провайдера в спільному макеті порушить цю ізоляцію, запобігаючи правильному поширенню значень серверного контексту до ваших серверних компонентів.

"use client";

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

export const ClientComponentExample: FC = () => {
  const content = useIntlayer("client-component-example"); // Створіть відповідну декларацію контенту

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

import type { FC } from "react";
import { useIntlayer } from "next-intlayer/server";

export const ServerComponentExample: FC = () => {
  const content = useIntlayer("server-component-example"); // Створіть відповідну декларацію контенту

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

Якщо ви хочете використовувати свій контент у рядковому атрибуті, такому як 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)}" />

Щоб дізнатися більше про хук useIntlayer, зверніться до документації.

Якщо ваш застосунок уже існує, ви можете скористатися Intlayer Compiler у поєднанні з командой extract, щоб перетворити тисячі компонентів за одну секунду.

(Опціонально) Крок 7: Налаштуйте проксі для виявлення локалі

Налаштуйте проксі для виявлення бажаної локалі користувача:

export { intlayerProxy as proxy } from "next-intlayer/proxy";

export const config = {
  matcher:
    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
};

intlayerProxy використовується для виявлення бажаної локалі користувача та перенаправлення його на відповідний URL, як зазначено в конфігурації. Крім того, він дозволяє зберігати бажану локаль користувача у файлі cookie.

Якщо вам потрібно об'єднати кілька проксі разом (наприклад, intlayerProxy з аутентифікацією або кастомними проксі), Intlayer тепер надає помічника під назвою multipleProxies.

import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

(Опціонально) Крок 8: Інтернаціоналізація ваших метаданих

У випадку, якщо ви хочете інтернаціоналізувати свої метадані, наприклад заголовок вашої сторінки, ви можете скористатися функцією generateMetadata, наданою Next.js. Всередині ви можете отримати контент за допомогою функції getIntlayer, щоб перекласти ваші метадані.

import { type Dictionary, t } from "intlayer";
import { Metadata } from "next";

const metadataContent = {
  key: "page-metadata",
  content: {
    title: t({
      en: "Create Next App",
      fr: "Créer une application Next.js",
      es: "Crear una aplicación Next.js",
    }),
    description: t({
      en: "Generated by create next app",
      fr: "Généré par create next app",
      es: "Generado por create next app",
    }),
  },
} satisfies Dictionary<Metadata>;

export default metadataContent;

import { getIntlayer, getMultilingualUrls } from "intlayer";
import type { Metadata } from "next";
import type { LocalPromiseParams } from "next-intlayer";

export const generateMetadata = async ({
  params,
}: LocalPromiseParams): Promise<Metadata> => {
  const { locale } = await params;

  const metadata = getIntlayer("page-metadata", locale);

  /**
   * Генерує об'єкт, що містить усі URL-адреси для кожної локалі.
   *
   * Приклад:
   * ```ts
   *  getMultilingualUrls('/about');
   *
   *  // Повертає
   *  // {
   *  //   en: '/about',
   *  //   fr: '/fr/about',
   *  //   es: '/es/about',
   *  // }
   * ```
   */
  const multilingualUrls = getMultilingualUrls("/");
  const localizedUrl =
    multilingualUrls[locale as keyof typeof multilingualUrls];

  return {
    ...metadata,
    alternates: {
      canonical: localizedUrl,
      languages: { ...multilingualUrls, "x-default": "/" },
    },
    openGraph: {
      url: localizedUrl,
    },
  };
};

// ... Решта коду

Зверніть увагу, що функція getIntlayer, імпортована з next-intlayer, повертає ваш контент, загорнутий в IntlayerNode, що дозволяє інтеграцію з візуальним редактором. На відміну від неї, функція getIntlayer, імпортована з intlayer, повертає ваш контент безпосередньо без додаткових властивостей.

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

import {
  type IConfigLocales,
  getTranslation,
  getMultilingualUrls,
} from "intlayer";
import type { Metadata } from "next";
import type { LocalPromiseParams } from "next-intlayer";

export const generateMetadata = async ({
  params,
}: LocalPromiseParams): Promise<Metadata> => {
  const { locale } = await params;
  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);

  return {
    title: t<string>({
      en: "My title",
      fr: "Mon titre",
      es: "Mi título",
    }),
    description: t({
      en: "My description",
      fr: "Ma description",
      es: "Mi descripción",
    }),
  };
};

// ... Решта коду

Дізнайтеся більше про оптимізацію метаданих в офіційній документації Next.js.

(Опціонально) Крок 9: Інтернаціоналізація ваших sitemap.xml та robots.txt

Щоб інтернаціоналізувати ваші sitemap.xml та robots.txt, ви можете скористатися функцією getMultilingualUrls, наданою Intlayer. Ця функція дозволяє генерувати багатомовні URL-адреси для вашої карти сайту.

import { getMultilingualUrls } from "intlayer";
import type { MetadataRoute } from "next";

const sitemap = (): MetadataRoute.Sitemap => [
  {
    url: "https://example.com",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com"),
        "x-default": "https://example.com",
      },
    },
  },
  {
    url: "https://example.com/login",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/login"),
        "x-default": "https://example.com/login",
      },
    },
  },
  {
    url: "https://example.com/register",
    alternates: {
      languages: {
        ...getMultilingualUrls("https://example.com/register"),
        "x-default": "https://example.com/register",
      },
    },
  },
];

export default sitemap;

import type { MetadataRoute } from "next";
import { getMultilingualUrls } from "intlayer";

const getAllMultilingualUrls = (urls: string[]) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);

const robots = (): MetadataRoute.Robots => ({
  rules: {
    userAgent: "*",
    allow: ["/"],
    disallow: getAllMultilingualUrls(["/login", "/register"]),
  },
  host: "https://example.com",
  sitemap: `https://example.com/sitemap.xml`,
});

export default robots;

Дізнайтеся більше про оптимізацію карти сайту в офіційній документації Next.js. Дізнайтеся більше про оптимізацію robots.txt в офіційній документації Next.js.

(Опціонально) Крок 10: Зміна мови вашого контенту

Щоб змінити мову вашого контенту в Next.js, рекомендованим способом є використання компонента Link для перенаправлення користувачів на відповідну локалізовану сторінку. Компонент Link дозволяє попередньо завантажувати сторінку, що допомагає уникнути повного перезавантаження сторінки.

"use client";

import type { FC } from "react";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "next-intlayer";
import Link from "next/link";

export const LocaleSwitcher: FC = () => {
  const { locale, pathWithoutLocale, availableLocales, setLocale } =
    useLocale();

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <Link
            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
            key={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={() => setLocale(localeItem)}
            replace // Це гарантує, що кнопка "назад" у браузері перенаправлятиме на попередню сторінку
          >
            <span>
              {/* Локаль - наприклад, FR */}
              {localeItem}
            </span>
            <span>
              {/* Мова у її власній локалі - наприклад, Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Мова у поточній локалі - наприклад, Francés, якщо поточна локаль встановлена як Locales.SPANISH */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Мова англійською - наприклад, French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </Link>
        ))}
      </div>
    </div>
  );
};

Альтернативним способом є використання функції setLocale, наданої хуком useLocale. Ця функція не дозволяє попередньо завантажувати сторінку. Дивіться документацію хука useLocale для отримання детальнішої інформації.

Ви також можете встановити функцію в опції onLocaleChange, щоб викликати кастомну функцію при зміні локалі.

"use client";import { useRouter } from "next/navigation";import { useLocale } from "next-intlayer";import { getLocalizedUrl } from "intlayer";// ... Решта кодуconst router = useRouter();const { setLocale } = useLocale({  onLocaleChange: (locale) => {    router.push(getLocalizedUrl(pathWithoutLocale, locale));  },});return (  <button onClick={() => setLocale(Locales.FRENCH)}>    Переключити на французьку  </button>);

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

• хук useLocale
• хук getLocaleName
• хук getLocalizedUrl
• хук getHTMLTextDir
• атрибут hrefLang
• атрибут lang
• атрибут dir
• атрибут aria-current

(Опціонально) Крок 11: Створення локалізованого компонента Link

Щоб навигація вашого додатка відповідала поточній локалі, ви можете створити кастомний компонент Link. Цей компонент автоматично додає префікс поточної мови до внутрішніх URL-адрес. Наприклад, коли франкомовний користувач натискає на посилання на сторінку "Про нас", він перенаправляється на /fr/about замість /about.

Ця поведінка корисна з кількох причин:

• SEO та досвід користувача: Локалізовані URL-адреси допомагають пошуковим системам правильно індексувати сторінки на певних мовах і надають користувачам контент на їхній улюбленій мові.
• Послідовність: Використовуючи локалізоване посилання у всьому додатку, ви гарантуєте, що навігація залишається в межах поточної локалі, запобігаючи несподіваним змінам мови.
• Підтримка: Централізація логіки локалізації в одному компоненті спрощує керування URL-адресами, роблячи ваш код легшим для підтримки та розширення в міру зростання додатка.

Нижче наведено реалізацію локалізованого компонента Link на TypeScript:

"use client";

import { getLocalizedUrl } from "intlayer";
import NextLink, { type LinkProps as NextLinkProps } from "next/link";
import { useLocale } from "next-intlayer";
import type { PropsWithChildren, FC } from "react";

/**
 * Допоміжна функція для перевірки, чи є дана URL-адреса зовнішньою.
 * Якщо URL-адреса починається з http:// або https://, вона вважається зовнішньою.
 */
export const checkIsExternalLink = (href?: string): boolean =>
  /^https?:\/\//.test(href ?? "");

/**
 * Кастомний компонент Link, який адаптує атрибут href залежно від поточної локалі.
 * Для внутрішніх посилань він використовує `getLocalizedUrl`, щоб додати префікс локалі до URL (наприклад, /fr/about).
 * Це гарантує, що навігація залишається в контексті тієї ж локалі.
 */
export const Link: FC<PropsWithChildren<NextLinkProps>> = ({
  href,
  children,
  ...props
}) => {
  const { locale } = useLocale();
  const isExternalLink = checkIsExternalLink(href.toString());

  // Якщо посилання внутрішнє і вказано валідний href, отримуємо локалізований URL.
  const hrefI18n: NextLinkProps["href"] =
    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;

  return (
    <NextLink href={hrefI18n} {...props}>
      {children}
    </NextLink>
  );
};

Як це працює

• Виявлення зовнішніх посилань:
  Допоміжна функція checkIsExternalLink визначає, чи є URL-адреса зовнішньою. Зовнішні посилання залишаються без змін, оскільки вони не потребують локалізації.

• Отримання поточної локалі:
  Хук useLocale надає поточну локаль (наприклад, fr для французької).

• Локалізація URL-адреси:
  Для внутрішніх посилань (тобто не зовнішніх) використовується getLocalizedUrl для автоматичного додавання префікса поточної локалі до URL. Це означає, що якщо ваш користувач перебуває на французькій версії сайту, передача /about як href перетворить його на /fr/about.

• Повернення посилання:
  Компонент повертає елемент <a> з локалізованим URL, забезпечуючи відповідність навігації локалі.

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

(Опціонально) Крок 12: Отримання поточної локалі в Server Actions

Якщо вам потрібна активна локаль всередині Server Action (наприклад, для локалізації електронних листів або запуску логіки, залежної від локалі), викличте getLocale з next-intlayer/server:

"use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // Зробіть щось із локаллю};

Функція getLocale використовує каскадну стратегію для визначення локалі користувача:

1. Спочатку вона перевіряє заголовки запиту на наявність значення локалі, яке могло бути встановлено проксі.
2. Якщо локаль не знайдена в заголовках, вона шукає локаль, збережену у файлах cookie.
3. Якщо файли cookie не знайдені, вона намагається визначити улюблену мову користувача за налаштуваннями його браузера.
4. В останню чергу вона повертається до налаштованої в додатку локалі за замовчуванням.

Це гарантує вибір найбільш підходящої локалі на основі доступного контексту.

(Опціонально) Крок 13: Оптимізація розміру вашого бандла

При використанні next-intlayer словники за замовчуванням включаються в бандл для кожної сторінки. Для оптимізації розміру бандла Intlayer надає додатковий плагін SWC, який інтелектуально замінює виклики useIntlayer за допомогою макросів. Це гарантує, що словники включаються в бандли тільки для тих сторінок, які їх дійсно використовують.

Щоб увімкнути цю оптимізацію, встановіть пакет @intlayer/swc. Після встановлення next-intlayer автоматично виявить і почне використовувати плагін:

npm install @intlayer/swc --save-dev

Примітка: Ця оптимізація доступна тільки для Next.js 13 і вище.

Примітка: Цей пакет не встановлюється за замовчуванням, оскільки плагіни SWC все ще є експериментальними в Next.js. Це може змінитися в майбутньому.

Примітка: Якщо ви встановите опцію importMode: 'dynamic' або importMode: 'fetch' (у конфігурації dictionary), вона буде покладатися на Suspense, тому вам доведеться обгорнути ваші виклики useIntlayer в межу Suspense. Це означає, що ви не зможете використовувати useIntlayer безпосередньо на верхньому рівні вашого компонента Page / Layout.

Відстеження змін словників у Turbopack

При використанні Turbopack як сервера розробки за допомогою команди next dev зміни в словниках за замовчуванням не будуть виявлятися автоматично.

Це обмеження виникає через те, що Turbopack не може запускати плагіни webpack паралельно для моніторингу змін у ваших файлах контенту. Щоб обійти це, вам потрібно буде використовувати команду intlayer watch, щоб одночасно запустити сервер розробки та спостерігач за збіркою Intlayer.

{  // ... Ваші існуючі конфігурації package.json  "scripts": {    // ... Ваші існуючі конфігурації скриптів    "dev": "intlayer watch --with 'next dev'",  },}

Якщо ви використовуєте next-intlayer@<=6.x.x, вам потрібно залишити прапор --turbopack, щоб додаток Next.js 16 коректно працював із Turbopack. Ми рекомендуємо використовувати next-intlayer@>=7.x.x, щоб уникнути цього обмеження.

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

Intlayer використовує розширення модулів (module augmentation), щоб отримати переваги TypeScript і зробити вашу кодову базу надійнішою.

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

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

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

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

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

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

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

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

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

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

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

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

(Необов'язково) Крок 1 : Витягніть вміст ваших компонентів

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

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

Щоб налаштувати його, ви можете додати розділ compiler у свій файл 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;

npx intlayer extract

npm install @intlayer/babel --save-dev

const { intlayerExtractBabelPlugin, getExtractPluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Витягування вмісту з компонентів у словники   [intlayerExtractBabelPlugin, getExtractPluginOptions()], ],};

npm run build # Або npm run dev

Йдіть далі

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